{ "components": { "examples": { "forbidden": { "summary": "The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code.", "value": { "error": { "code": "forbidden", "message": "The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 403, "retryable": false, "param": null, "remediation": "Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "doc_url": "https://socialtap.dev/docs/errors/#forbidden", "details": {}, "charged": false } } }, "idempotency_key_in_progress": { "summary": "A request with this Idempotency-Key is still running.", "value": { "error": { "code": "idempotency_key_in_progress", "message": "A request with this Idempotency-Key is still running.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 409, "retryable": true, "param": null, "remediation": "Retry after the seconds in the retry-after header to get that request's result.", "doc_url": "https://socialtap.dev/docs/errors/#idempotency_key_in_progress", "details": {}, "charged": false } } }, "idempotency_key_reused": { "summary": "This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another.", "value": { "error": { "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 422, "retryable": false, "param": null, "remediation": "Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "doc_url": "https://socialtap.dev/docs/errors/#idempotency_key_reused", "details": {}, "charged": false } } }, "insufficient_credits": { "summary": "The account does not have enough credits for this request.", "value": { "error": { "code": "insufficient_credits", "message": "The account does not have enough credits for this request.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 402, "retryable": false, "param": null, "remediation": "Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.", "doc_url": "https://socialtap.dev/docs/errors/#insufficient_credits", "details": {}, "charged": false } } }, "internal": { "summary": "An unexpected error on SocialTap's side.", "value": { "error": { "code": "internal", "message": "An unexpected error on SocialTap's side.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 500, "retryable": true, "param": null, "remediation": "Retry with backoff. If it keeps happening, contact support with the request_id.", "doc_url": "https://socialtap.dev/docs/errors/#internal", "details": {}, "charged": false } } }, "invalid_cursor": { "summary": "The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it.", "value": { "error": { "code": "invalid_cursor", "message": "The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 400, "retryable": false, "param": null, "remediation": "Repeat the original request without cursor to start the list again.", "doc_url": "https://socialtap.dev/docs/errors/#invalid_cursor", "details": {}, "charged": false } } }, "invalid_input": { "summary": "A parameter is missing or malformed, or the link is not one this endpoint takes.", "value": { "error": { "code": "invalid_input", "message": "A parameter is missing or malformed, or the link is not one this endpoint takes.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 400, "retryable": false, "param": null, "remediation": "Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "doc_url": "https://socialtap.dev/docs/errors/#invalid_input", "details": {}, "charged": false } } }, "job_not_found": { "summary": "The account has no job with this ID: the ID is wrong, or the job is past its retention.", "value": { "error": { "code": "job_not_found", "message": "The account has no job with this ID: the ID is wrong, or the job is past its retention.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 404, "retryable": false, "param": null, "remediation": "Check the job ID. Finished jobs are kept for a limited time.", "doc_url": "https://socialtap.dev/docs/errors/#job_not_found", "details": {}, "charged": false } } }, "no_live": { "summary": "The account exists but has no live broadcast to show: nothing on air or scheduled, and no past broadcast the platform still shows.", "value": { "error": { "code": "no_live", "message": "The account exists but has no live broadcast to show: nothing on air or scheduled, and no past broadcast the platform still shows.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 404, "retryable": false, "param": null, "remediation": "Do not retry now. Ask again later, when the account may be live.", "doc_url": "https://socialtap.dev/docs/errors/#no_live", "details": {}, "charged": false } } }, "no_media": { "summary": "The post exists but has no file to download: a text or link post, or one whose media the platform does not serve logged out.", "value": { "error": { "code": "no_media", "message": "The post exists but has no file to download: a text or link post, or one whose media the platform does not serve logged out.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 404, "retryable": false, "param": null, "remediation": "Do not retry. Fetch the post itself for its text and links.", "doc_url": "https://socialtap.dev/docs/errors/#no_media", "details": {}, "charged": false } } }, "no_transcript": { "summary": "The video or audio exists but has no transcript: no caption track and no speech to transcribe.", "value": { "error": { "code": "no_transcript", "message": "The video or audio exists but has no transcript: no caption track and no speech to transcribe.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 404, "retryable": false, "param": null, "remediation": "Do not retry. If the platform offers other languages, try one with lang.", "doc_url": "https://socialtap.dev/docs/errors/#no_transcript", "details": {}, "charged": false } } }, "not_found": { "summary": "The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).", "value": { "error": { "code": "not_found", "message": "The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 404, "retryable": false, "param": null, "remediation": "Check the link or ID. Do not retry.", "doc_url": "https://socialtap.dev/docs/errors/#not_found", "details": {}, "charged": false } } }, "overloaded": { "summary": "SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged.", "value": { "error": { "code": "overloaded", "message": "SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 503, "retryable": true, "param": null, "remediation": "Retry after the seconds in the retry-after header. Failed requests are free.", "doc_url": "https://socialtap.dev/docs/errors/#overloaded", "details": {}, "charged": false } } }, "private_or_unavailable": { "summary": "The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.", "value": { "error": { "code": "private_or_unavailable", "message": "The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 403, "retryable": false, "param": null, "remediation": "Only public items can be fetched. Do not retry.", "doc_url": "https://socialtap.dev/docs/errors/#private_or_unavailable", "details": {}, "charged": false } } }, "rate_limited": { "summary": "The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it.", "value": { "error": { "code": "rate_limited", "message": "The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 429, "retryable": true, "param": null, "remediation": "Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "doc_url": "https://socialtap.dev/docs/errors/#rate_limited", "details": {}, "charged": false } } }, "spend_limit_reached": { "summary": "The API key reached its spend limit for this period. The account may still have credits.", "value": { "error": { "code": "spend_limit_reached", "message": "The API key reached its spend limit for this period. The account may still have credits.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 402, "retryable": false, "param": null, "remediation": "Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "doc_url": "https://socialtap.dev/docs/errors/#spend_limit_reached", "details": {}, "charged": false } } }, "unauthorized": { "summary": "The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired.", "value": { "error": { "code": "unauthorized", "message": "The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 401, "retryable": false, "param": null, "remediation": "Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "doc_url": "https://socialtap.dev/docs/errors/#unauthorized", "details": {}, "charged": false } } }, "upstream_blocked": { "summary": "The platform refused every attempt, our own retries included.", "value": { "error": { "code": "upstream_blocked", "message": "The platform refused every attempt, our own retries included.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 503, "retryable": true, "param": null, "remediation": "Retry later with backoff. Failed requests are free.", "doc_url": "https://socialtap.dev/docs/errors/#upstream_blocked", "details": {}, "charged": false } } }, "upstream_error": { "summary": "The platform failed, or answered with something we could not read.", "value": { "error": { "code": "upstream_error", "message": "The platform failed, or answered with something we could not read.", "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "status": 502, "retryable": true, "param": null, "remediation": "Retry with backoff. Failed requests are free.", "doc_url": "https://socialtap.dev/docs/errors/#upstream_error", "details": {}, "charged": false } } } }, "headers": { "age": { "description": "Seconds since the data was fetched (cache hits only).", "schema": { "type": "integer" } }, "allow": { "description": "Methods the endpoint accepts (method_not_allowed only).", "schema": { "type": "string" } }, "deprecation": { "description": "RFC 9745: the endpoint is deprecated, as of this date (@; may be in the future). Also in meta.warnings.", "schema": { "type": "string" } }, "idempotent-replayed": { "description": "true when the answer replays an earlier request with the same Idempotency-Key (it shows the resource's current state).", "schema": { "type": "boolean" } }, "link": { "description": "RFC 8288 links: rel=\"next\" is the next page of a list (while page.has_more), the same request with cursor set; rel=\"deprecation\" is a deprecated endpoint's notice.", "schema": { "type": "string" } }, "location": { "description": "On 202 answers: the job's URL (GET it, free, for its status).", "schema": { "type": "string" } }, "preference-applied": { "description": "RFC 7240: respond-async when Prefer: respond-async turned the request into a job (202).", "schema": { "type": "string" } }, "ratelimit": { "description": "What is left of the ceiling (IETF RateLimit field): \"account\";r=;t=.", "schema": { "type": "string" } }, "ratelimit-policy": { "description": "The account's runaway-protection ceiling as an IETF RateLimit-Policy field, as enforced: a token bucket of q requests (twice the ceiling in requests per second, at least 10) that refills in w seconds: \"account\";q=;w=. Not a plan limit.", "schema": { "type": "string" } }, "retry-after": { "description": "Seconds to wait before retrying; sent only with the codes whose retry_after is set in the error codes list (never on credit errors).", "schema": { "type": "integer" } }, "sunset": { "description": "RFC 8594: when a deprecated endpoint stops answering (HTTP-date); from then on it answers endpoint_retired.", "schema": { "type": "string" } }, "x-client-request-id": { "description": "Your x-client-request-id, echoed (also meta.client_request_id).", "schema": { "type": "string" } }, "x-credits-charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "schema": { "type": "integer" } }, "x-credits-remaining": { "description": "Account balance after this request; for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance.", "schema": { "type": "integer" } }, "x-request-id": { "description": "Unique request ID; include it when contacting support.", "schema": { "type": "string" } } }, "responses": { "AsyncAccepted": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cancel_requested_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "credits": { "properties": { "charged": { "description": "Credits charged so far, each page once (items' prices; failed items are free).", "type": "integer" }, "max": { "description": "max_credits: the most the job may spend.", "type": "integer" }, "reserved": { "description": "Credits its running pages may still use (0 once the job ends).", "type": "integer" } }, "required": [ "max", "reserved", "charged" ], "type": "object" }, "expires_at": { "description": "The deadline: items not ended by then expire.", "format": "date-time", "type": "string" }, "finished_at": { "description": "When the job ended; null while it runs.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The job ID (job_…).", "type": "string" }, "max_age": { "description": "The job's max_age; null when it accepts no cached results.", "type": [ "integer", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Your metadata; {} when none.", "type": "object" }, "object": { "description": "Always job.", "enum": [ "job" ], "type": "string" }, "request_counts": { "properties": { "canceled": { "type": "integer" }, "expired": { "type": "integer" }, "failed": { "type": "integer" }, "queued": { "description": "Not started.", "type": "integer" }, "running": { "description": "Started (fetching, waiting for a retry or walking pages).", "type": "integer" }, "succeeded": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "total", "queued", "running", "succeeded", "failed", "canceled", "expired" ], "type": "object" }, "results_expire_at": { "description": "When results are deleted; null while the job runs.", "format": "date-time", "type": [ "string", "null" ] }, "results_url": { "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.", "type": [ "string", "null" ] }, "results_url_expires_at": { "format": "date-time", "type": [ "string", "null" ] }, "started_at": { "description": "When the first item started; null before.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.", "enum": [ "queued", "running", "canceling", "completed", "canceled", "expired" ], "type": "string" }, "webhook_url": { "description": "The job's own webhook URL; null when none.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "status", "request_counts", "credits", "max_age", "metadata", "webhook_url", "created_at", "started_at", "finished_at", "cancel_requested_at", "expires_at", "results_url", "results_url_expires_at", "results_expire_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Accepted (only with `prefer: respond-async`): the request runs as a one-request job (`custom_id` \"request\", the `jobs` scope); its result is the job's result, priced as this request.", "headers": { "location": { "$ref": "#/components/headers/location" }, "preference-applied": { "$ref": "#/components/headers/preference-applied" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "schemas": { "Ad": { "properties": { "advertiser": { "$ref": "#/components/schemas/ProfileRef", "description": "The advertising page, business or account." }, "approximate_fields": { "description": "JSON paths of values that are rounded, date-only or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "audience_size": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Estimated target audience size range; null when not disclosed." }, "country_codes": { "description": "ISO 3166-1 alpha-2 countries where it was shown; [] if not disclosed.", "items": { "type": "string" }, "type": "array" }, "creatives": { "description": "The ad's creatives: one per card of a carousel and per variation of a dynamic or catalog ad, else one for the ad itself; [] if none are shown.", "items": { "$ref": "#/components/schemas/AdCreative" }, "type": "array" }, "first_shown_at": { "description": "First delivery, RFC 3339 UTC (often date-only: see approximate_fields).", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Library ad ID (string).", "type": "string" }, "impressions": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Impressions or times shown range; null when not disclosed." }, "is_active": { "description": "True while the ad is running.", "type": [ "boolean", "null" ] }, "is_political": { "description": "Categorized as a political or social-issue ad; false when the library files it under another category, null when it shows none.", "type": [ "boolean", "null" ] }, "languages": { "description": "BCP-47 languages of the ad; [] if not disclosed.", "items": { "type": "string" }, "type": "array" }, "last_shown_at": { "description": "Last delivery, RFC 3339 UTC; null while active.", "format": "date-time", "type": [ "string", "null" ] }, "paid_by": { "description": "Disclosed payer (\"Paid for by\").", "type": [ "string", "null" ] }, "platform": { "description": "Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/AdPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "publisher_platforms": { "description": "Where it ran, lowercase IDs (facebook, instagram, messenger, audience_network, youtube, …); [] if not disclosed.", "items": { "type": "string" }, "type": "array" }, "reach": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Unique users reached range; null when not disclosed." }, "spend": { "anyOf": [ { "$ref": "#/components/schemas/MoneyRange" }, { "type": "null" } ], "description": "Spend range; null when not disclosed." }, "type": { "description": "Creative shape. New values may be added; treat unknown values as other.", "enum": [ "image", "video", "carousel", "text", "dynamic", "other" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Public library page of the ad.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "advertiser", "paid_by", "is_active", "first_shown_at", "last_shown_at", "type", "publisher_platforms", "creatives", "languages", "country_codes", "is_political", "impressions", "reach", "audience_size", "spend", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "AdCreative": { "properties": { "body": { "description": "Primary text.", "type": [ "string", "null" ] }, "cta_text": { "description": "Call-to-action label (e.g. Shop now).", "type": [ "string", "null" ] }, "link_description": { "description": "Link description text.", "type": [ "string", "null" ] }, "link_url": { "description": "Destination URL.", "format": "uri", "type": [ "string", "null" ] }, "media": { "description": "Images and videos of this creative; [] if none.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "title": { "description": "Headline.", "type": [ "string", "null" ] } }, "required": [ "title", "body", "link_url", "link_description", "cta_text", "media" ], "type": "object" }, "AdPlatformSpecific": { "properties": { "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookAdSpecific" }, { "type": "null" } ], "description": "A Meta Ad Library ad's own fields." }, "google": { "anyOf": [ { "$ref": "#/components/schemas/GoogleAdSpecific" }, { "type": "null" } ], "description": "A Google ad's own fields." }, "linkedin": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdSpecific" }, { "type": "null" } ], "description": "A LinkedIn Ad Library ad's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokAdSpecific" }, { "type": "null" } ], "description": "A TikTok ad's own fields." } }, "type": "object" }, "Album": { "properties": { "approximate_fields": { "description": "JSON paths of values that are date-only, rounded by the platform or parsed from display text (released_at from a date, duration_ms from \"1 hour 1 minute\"). A list path means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "artist_name": { "description": "Who the platform credits for the release, as one display string (it can name more people than have an account linked: artists holds the linked ones); null when the source does not name them.", "type": [ "string", "null" ] }, "artists": { "description": "The platform accounts of the artists credited on the release, main artist first, in the platform's order; [] when none is linked, as on a Various Artists compilation (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "copyrights": { "description": "The release's copyright lines as the platform shows them; [] when none.", "items": { "$ref": "#/components/schemas/AlbumCopyright" }, "type": "array" }, "cover_url": { "description": "Cover art URL at the largest size the platform serves; null when it has none.", "format": "uri", "type": [ "string", "null" ] }, "description": { "description": "About the release, as plain text (the service's editorial notes, or what its uploader wrote); null when it has none or the platform shows none.", "type": [ "string", "null" ] }, "duration_ms": { "description": "Total length of the release in milliseconds; null when neither the platform nor a complete tracks list gives it.", "format": "int64", "type": [ "integer", "null" ] }, "genres": { "description": "Genres the platform files it under, as shown (not normalized), the main one first; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Platform-native album ID (string), the one in its page's URL.", "type": "string" }, "is_explicit": { "description": "Marked as holding explicit content (by the platform, or on any of its tracks); null when the platform does not say.", "type": [ "boolean", "null" ] }, "label": { "description": "The record label as the platform names it; null when none is shown.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/AlbumMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (applemusic, spotify, soundcloud, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/AlbumPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "released_at": { "description": "When it was released, RFC 3339 UTC. A release date with no time (nearly all) is midnight UTC of that date, listed in approximate_fields, and so is a year or month alone (its first day). Null when the platform states none.", "format": "date-time", "type": [ "string", "null" ] }, "title": { "description": "The release's title as the platform shows it (with an edition or a suffix like \"- Single\" where it writes one).", "type": "string" }, "tracks": { "description": "The release's tracks in album order (by disc, then track number). A list of albums, whose source shows none, answers [] and lists tracks in unknown_fields; a list the source could only read part of is listed in approximate_fields.", "items": { "$ref": "#/components/schemas/AlbumTrack" }, "type": "array" }, "type": { "description": "What kind of release it is, as the platform says: album, single, ep or compilation; null when the platform does not say. New values may be added; treat unknown values as album.", "enum": [ "album", "single", "ep", "compilation", null ], "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them), tracks[].artists for that list on every track; null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "upc": { "description": "The release's barcode: its UPC or EAN, digits only; null when the platform does not show it.", "type": [ "string", "null" ] }, "url": { "description": "Canonical album page URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "type", "title", "description", "artist_name", "artists", "cover_url", "released_at", "label", "upc", "copyrights", "genres", "is_explicit", "duration_ms", "tracks", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "AlbumCopyright": { "properties": { "text": { "description": "The line as the platform shows it.", "type": "string" }, "type": { "description": "c: the copyright in the work (©); p: in the sound recording (℗); null when the line does not say or states both. New values may be added.", "enum": [ "c", "p", null ], "type": [ "string", "null" ] } }, "required": [ "type", "text" ], "type": "object" }, "AlbumMetrics": { "properties": { "track_count": { "description": "Tracks on the release as the platform counts them, null when it does not state a count; tracks answers fewer only when listed in approximate_fields or unknown_fields.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "track_count" ], "type": "object" }, "AlbumPlatformSpecific": { "properties": { "applemusic": { "anyOf": [ { "$ref": "#/components/schemas/ApplemusicAlbumSpecific" }, { "type": "null" } ], "description": "An Apple Music album's own fields." }, "soundcloud": { "anyOf": [ { "$ref": "#/components/schemas/SoundcloudAlbumSpecific" }, { "type": "null" } ], "description": "A SoundCloud album set's own fields." }, "spotify": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyAlbumSpecific" }, { "type": "null" } ], "description": "A Spotify release's own fields." } }, "type": "object" }, "AlbumTrack": { "properties": { "artist_name": { "description": "Who the platform credits for this track, as one display string (a feature included); null when the source does not name them.", "type": [ "string", "null" ] }, "artists": { "description": "The platform accounts of the artists credited on this track, in the platform's order; [] when none is linked (listed in unknown_fields as tracks[].artists when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "disc_number": { "description": "The disc it is on, from 1; null when the platform does not say (a release of one disc, on platforms without discs).", "format": "int64", "type": [ "integer", "null" ] }, "duration_ms": { "description": "Length of the track in milliseconds; null when the source does not state it.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Platform-native track ID (string): the one the platform's track endpoint takes and answers.", "type": "string" }, "is_explicit": { "description": "Marked as explicit by the platform; null when it does not say.", "type": [ "boolean", "null" ] }, "isrc": { "description": "International Standard Recording Code, 12 characters without hyphens; null when the platform does not show it.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/AlbumTrackMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "play_url": { "description": "Audio file URL: a short preview, where the platform serves only one. Signed links expire within hours; null when not exposed.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The track's title as the platform shows it; null when the source names the track only by its ID.", "type": [ "string", "null" ] }, "track_number": { "description": "Its position on its disc, from 1; null when the source does not state it (tracks stay in album order).", "format": "int64", "type": [ "integer", "null" ] }, "url": { "description": "The track's page; null when the source does not show it.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "artist_name", "artists", "track_number", "disc_number", "duration_ms", "is_explicit", "isrc", "play_url", "metrics" ], "type": "object" }, "AlbumTrackMetrics": { "properties": { "view_count": { "description": "Plays; null when the platform does not show them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "view_count" ], "type": "object" }, "AmazonCaptionTrack": { "properties": { "language": { "description": "Language code (en, …).", "type": [ "string", "null" ] }, "url": { "description": "WebVTT file URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "language", "url" ], "type": "object" }, "AmazonCategory": { "properties": { "id": { "description": "Amazon's browse node ID of the category (what its category pages take as node=); null when the link names none.", "type": [ "string", "null" ] }, "name": { "description": "Category name, as shown.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "AmazonContributor": { "properties": { "name": { "description": "The contributor's name, as the byline shows it.", "type": "string" }, "role": { "description": "Their role, as Amazon words it (Author, Narrator, Translator); null when the byline gives none.", "type": [ "string", "null" ] } }, "required": [ "name", "role" ], "type": "object" }, "AmazonCuration": { "properties": { "id": { "description": "Amazon's ID of the curation, as its link writes it (a UUID).", "type": "string" }, "post_count": { "description": "Posts in it, as its card counts them.", "format": "int64", "type": [ "integer", "null" ] }, "thumbnail_url": { "description": "Its cover image URL.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Its title, as the influencer wrote it.", "type": [ "string", "null" ] }, "url": { "description": "Its link.", "format": "uri", "type": "string" } }, "required": [ "id", "title", "url", "thumbnail_url", "post_count" ], "type": "object" }, "AmazonDeal": { "properties": { "badge": { "description": "The deal's badge, as shown (23% off, Up to 40% off); null when it shows none.", "type": [ "string", "null" ] }, "claimed_percent": { "description": "Share of the deal's units already claimed, in percent (0 to 100) as Amazon rounds it; null when Amazon shows none (most deals but lightning deals).", "format": "double", "maximum": 100, "minimum": 0, "type": [ "number", "null" ] }, "coupon_id": { "description": "Amazon's ID of the coupon's promotion (its page is amazon.com/promo/); null when the product has no coupon.", "type": [ "string", "null" ] }, "coupon_price": { "description": "The price after the product's clippable coupon, in major units of the product's currency; null when it has no coupon or the coupon shows no price.", "format": "double", "type": [ "number", "null" ] }, "department_ids": { "description": "The browse nodes Amazon's deals list files the deal under, in no particular order (one to several, from a department down to a sub-category): each is a category the Amazon Deals API takes. Empty when it names none.", "items": { "type": "string" }, "type": "array" }, "ends_at": { "description": "When the deal ends, RFC 3339 UTC, from the badge's countdown; null when the badge shows none (most deals but lightning deals).", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Amazon's ID of the deal; null for a product listed for its coupon alone.", "type": [ "string", "null" ] }, "label": { "description": "The deal's label, as shown (Limited time deal, Early Black Friday Deal, Limited Prime deal); null when the badge shows a countdown instead (see ends_at) or nothing.", "type": [ "string", "null" ] }, "original_price_label": { "description": "What original_price is: list (the list price), typical (the typical price of the last 90 days), rrp (the recommended retail price) or was (the price before the deal); null when no earlier price is shown or Amazon labels it otherwise. New values may be added; treat unknown values as null.", "enum": [ "list", "typical", "rrp", "was", null ], "type": [ "string", "null" ] }, "status": { "description": "The deal's state, as Amazon names it, lowercased (available: it can be bought at the deal price now); null for a coupon alone.", "type": [ "string", "null" ] }, "type": { "description": "The kind of deal, as Amazon names it, lowercased: lightning_deal (a limited number of units for a few hours), best_deal (a limited time deal), others as Amazon adds them; coupon when the product is listed for its coupon alone.", "type": "string" } }, "required": [ "id", "type", "status", "badge", "label", "ends_at", "claimed_percent", "original_price_label", "department_ids", "coupon_price", "coupon_id" ], "type": "object" }, "AmazonDeal_productsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Amazon's Today's Deals order (its own ranking, as the grid shows it).", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonOfferSpecific": { "properties": { "condition_note": { "description": "The seller's or Amazon's notes on the item's condition (Item will come in original packaging.), as shown under it; null when none is shown, as on new offers.", "type": [ "string", "null" ] }, "is_fulfilled_by_amazon": { "description": "Amazon ships the offer from its own warehouses (Fulfillment by Amazon, or sold by Amazon); false when the seller ships it; null when not shown.", "type": [ "boolean", "null" ] }, "seller_positive_percent": { "description": "Share of the seller's ratings in the last 12 months that were positive, a whole percent (77); over the seller's lifetime for a seller Amazon shows that for (a new one); null when not shown (Amazon's own retail shows none).", "format": "int64", "type": [ "integer", "null" ] }, "ships_from": { "description": "Who ships the offer (Amazon, or the seller), as the offer says; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "ships_from", "is_fulfilled_by_amazon", "seller_positive_percent", "condition_note" ], "type": "object" }, "AmazonOffersResponse": { "properties": { "data": { "description": "Up to limit items (page size 11), The buy box offer first, then every other offer in Amazon's order: by price plus delivery, lowest first.", "items": { "$ref": "#/components/schemas/Offer" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonPlaylistSpecific": { "properties": { "heart_count": { "description": "Hearts shoppers gave the list (Amazon's likes), exact.", "format": "int64", "type": [ "integer", "null" ] }, "is_pinned": { "description": "True when the influencer pinned the list to the top of its storefront.", "type": [ "boolean", "null" ] }, "product_count": { "description": "Products in the list, as its card counts them.", "format": "int64", "type": [ "integer", "null" ] }, "products": { "description": "The list's first products as its card shows them (up to 20), in its order; the path is in approximate_fields when the list holds more.", "items": { "$ref": "#/components/schemas/AmazonProductRef" }, "type": "array" } }, "required": [ "product_count", "heart_count", "is_pinned", "products" ], "type": "object" }, "AmazonPostSpecific": { "properties": { "caption_tracks": { "description": "The video's caption tracks (WebVTT, public); [] when none, and for photos.", "items": { "$ref": "#/components/schemas/AmazonCaptionTrack" }, "type": "array" }, "products": { "description": "The products the post tags, in its order; [] when none. The path is in approximate_fields when the post may tag more than it shows.", "items": { "$ref": "#/components/schemas/AmazonProductRef" }, "type": "array" } }, "required": [ "products", "caption_tracks" ], "type": "object" }, "AmazonProductMetrics": { "properties": { "bought_past_month_count": { "description": "Units bought in the past month as Amazon's badge rounds them (10K+ is 10000): a lower bound; null when the page shows no badge.", "format": "int64", "type": [ "integer", "null" ] }, "offer_count": { "description": "Offers from every seller, new and used, as the other sellers box counts them; null when the page shows no such box.", "format": "int64", "type": [ "integer", "null" ] }, "rating_count": { "description": "Customer ratings behind rating (with or without a written review), exact.", "format": "int64", "type": [ "integer", "null" ] }, "rating_distribution": { "anyOf": [ { "$ref": "#/components/schemas/RatingDistribution" }, { "type": "null" } ], "description": "Ratings per star, from the histogram's whole percentages times rating_count (so each can be off by half a percent of rating_count); null when unrated." } }, "required": [ "rating_count", "bought_past_month_count", "offer_count", "rating_distribution" ], "type": "object" }, "AmazonProductRef": { "properties": { "asin": { "description": "The product's ASIN (what amazon.product takes).", "type": "string" }, "image_url": { "description": "The product's image URL, as the card shows it.", "format": "uri", "type": [ "string", "null" ] }, "url": { "description": "The product's page in the list's marketplace.", "format": "uri", "type": "string" } }, "required": [ "asin", "url", "image_url" ], "type": "object" }, "AmazonProductResponse": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "AmazonProductSpecific": { "properties": { "availability_label": { "description": "The buy box's stock line, as Amazon words it (Only 1 left in stock - order soon.); null when the page shows none.", "type": [ "string", "null" ] }, "best_sellers_ranks": { "description": "The product's sales rank in each category Amazon ranks it in (#49 in Electronics, #7 in Earbud & In-Ear Headphones), department first; [] when the page shows none.", "items": { "$ref": "#/components/schemas/AmazonRank" }, "type": "array" }, "brand": { "description": "Brand name, as Amazon shows it; null when it shows none (most books: their authors are contributors).", "type": [ "string", "null" ] }, "categories": { "description": "The product's category path, from the department down to category (the last one); [] when the page shows none.", "items": { "$ref": "#/components/schemas/AmazonCategory" }, "type": "array" }, "contributors": { "description": "The people the byline credits (a book's authors, narrators and translators), in Amazon's order; [] when the byline names none.", "items": { "$ref": "#/components/schemas/AmazonContributor" }, "type": "array" }, "deal": { "anyOf": [ { "$ref": "#/components/schemas/AmazonDeal" }, { "type": "null" } ], "description": "The deal Amazon's deals list shows the product with: its type, badge, end time, share claimed and coupon; null outside a deals list." }, "features": { "description": "The \"About this item\" bullet points, in Amazon's order; [] when the page has none (books, most media).", "items": { "type": "string" }, "type": "array" }, "is_sponsored": { "description": "The product is a paid placement among a search's results (Amazon labels it Sponsored); null outside search results.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/AmazonProductMetrics", "description": "Counts at fetch time; null = not shown, 0 = zero." }, "parent_asin": { "description": "ASIN of the variation family this product belongs to (every color and size of it shares it); null for a product without variations.", "type": [ "string", "null" ] }, "rank": { "description": "Position in the requested Best Sellers or other ranked list (1 = top); null off a list.", "format": "int64", "minimum": 1, "type": [ "integer", "null" ] }, "rating": { "description": "Average customer rating out of 5 (metrics.rating_count ratings behind it), as Amazon shows it, to one decimal; null when unrated.", "format": "double", "type": [ "number", "null" ] }, "ships_from": { "description": "Who ships the featured offer (Amazon, or the seller), as the buy box says; null when not shown.", "type": [ "string", "null" ] }, "variants": { "description": "Every variation of the product (its colors, sizes, styles), each an ASIN with its options, in Amazon's order; prices and stock are this product's only, so they are null on variants. [] for a product without variations.", "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array" } }, "required": [ "brand", "contributors", "rating", "metrics", "features", "is_sponsored", "categories", "best_sellers_ranks", "rank", "parent_asin", "variants", "availability_label", "ships_from", "deal" ], "type": "object" }, "AmazonProfileSpecific": { "properties": { "seller_business": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerBusiness" }, { "type": "null" } ], "description": "A seller's business identity, as its page discloses it (by law in the US and the EU): legal name, registration and VAT numbers, phone, email and addresses. Null on an account that is not a seller, or a seller whose page discloses none." }, "seller_feedback": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerFeedback" }, { "type": "null" } ], "description": "A seller's feedback from its buyers: the share of positive ratings, and per period its star rating and its ratings per star. Null on an account that is not a seller, or a seller whose page shows no feedback (Amazon's own subsidiaries)." }, "shop": { "anyOf": [ { "$ref": "#/components/schemas/AmazonStorefront" }, { "type": "null" } ], "description": "An influencer's storefront: its Top Creator badge, its curations and its trending picks. Null on an account that is not an influencer (a seller)." } }, "required": [ "seller_feedback", "seller_business", "shop" ], "type": "object" }, "AmazonRank": { "properties": { "category": { "description": "Category name, as shown.", "type": "string" }, "category_id": { "description": "Amazon's ID of the ranking: a browse node ID, or a department's slug (electronics) for a department's rank; null when the row links none.", "type": [ "string", "null" ] }, "rank": { "description": "The product's sales rank in the category (1 is the best seller).", "format": "int64", "type": "integer" } }, "required": [ "rank", "category", "category_id" ], "type": "object" }, "AmazonReviewsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), Amazon's top reviews: the marketplace's own first, then other countries'.", "items": { "$ref": "#/components/schemas/Review" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonSearch_productsResponse": { "properties": { "data": { "description": "Up to limit items (page size 60), Amazon's Newest Arrivals: the most recently listed first with sort=newest, Amazon's Best Sellers order: the most bought first with sort=popular, the lowest price first with sort=price_asc, the highest price first with sort=price_desc, Amazon's Featured order, sponsored results among them with sort=relevance.", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonSellerBusiness": { "properties": { "address": { "description": "Its registered business address on one line, as declared, ending with the country's code; null when not disclosed.", "type": [ "string", "null" ] }, "business_type": { "description": "The kind of business, as Amazon words it (Privately-owned business, Sole proprietorship); null when not disclosed (US marketplaces show none).", "type": [ "string", "null" ] }, "customer_service_address": { "description": "The address it gives for customer service on one line, when it gives one apart from the business address; null otherwise.", "type": [ "string", "null" ] }, "customer_service_phone": { "description": "The customer service phone number its page shows beside Ask a question, as written; null when it shows none.", "type": [ "string", "null" ] }, "email": { "description": "The business email address it declared; null when not disclosed.", "type": [ "string", "null" ] }, "legal_name": { "description": "The seller's registered business name, as declared (its display name is the shop's); null when not disclosed.", "type": [ "string", "null" ] }, "phone": { "description": "The business phone number it declared, as written; null when not disclosed.", "type": [ "string", "null" ] }, "trade_register_number": { "description": "Its commercial register number, as declared (HRB 40534); null when not disclosed.", "type": [ "string", "null" ] }, "vat_number": { "description": "Its VAT identification number (DE453729570); null when not disclosed.", "type": [ "string", "null" ] } }, "required": [ "legal_name", "business_type", "trade_register_number", "vat_number", "phone", "email", "address", "customer_service_address", "customer_service_phone" ], "type": "object" }, "AmazonSellerFeedback": { "properties": { "last_12_months": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerRatings" }, { "type": "null" } ], "description": "Ratings from the last 12 months; null when the page shows none." }, "last_30_days": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerRatings" }, { "type": "null" } ], "description": "Ratings from the last 30 days (the page's 1 month); null when the page shows none." }, "last_90_days": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerRatings" }, { "type": "null" } ], "description": "Ratings from the last 90 days (the page's 3 months); null when the page shows none." }, "lifetime": { "anyOf": [ { "$ref": "#/components/schemas/AmazonSellerRatings" }, { "type": "null" } ], "description": "Every rating the seller has received; null when the page shows none." }, "positive_percent": { "description": "Share of the last 12 months' ratings that are positive (4 or 5 stars), as Amazon rounds it to a whole percent; null when the page shows none (no ratings in the last 12 months).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "positive_percent", "last_30_days", "last_90_days", "last_12_months", "lifetime" ], "type": "object" }, "AmazonSellerRatings": { "properties": { "rating": { "description": "Star rating out of 5 over the period, as Amazon shows it, to one decimal; null when the period has no ratings.", "format": "double", "type": [ "number", "null" ] }, "rating_count": { "description": "Ratings buyers gave the seller over the period, exact.", "format": "int64", "type": [ "integer", "null" ] }, "rating_distribution": { "anyOf": [ { "$ref": "#/components/schemas/RatingDistribution" }, { "type": "null" } ], "description": "Ratings per star over the period, exact; null when the page does not count them." }, "review_count": { "description": "Ratings that came with a written review, exact; null when the page does not count them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "rating", "rating_count", "review_count", "rating_distribution" ], "type": "object" }, "AmazonSellerResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "AmazonShopResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "AmazonShop_listsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), the storefront's order: the list created or changed most recently first, with the lists the influencer pinned at the top of the first page.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonShop_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), the storefront's: newest first within each tab, after the posts the influencer pinned; type=all lists the videos, then the photos. In Amazon's words: `metrics.like_count` is hearts.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonStorefront": { "properties": { "curations": { "description": "Its curations, named collections of its posts, in the storefront's order; [] when it has none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/AmazonCuration" }, "type": "array" }, "is_top_creator": { "description": "True when Amazon shows its Top Creator badge (a leading Amazon creator by customer engagement and sales), false when it shows none; null when unknown.", "type": [ "boolean", "null" ] }, "trending_picks": { "description": "The products Amazon shows as trending from this storefront, in its order; [] when it shows none.", "items": { "$ref": "#/components/schemas/AmazonTrendingPick" }, "type": "array" } }, "required": [ "is_top_creator", "curations", "trending_picks" ], "type": "object" }, "AmazonTop_productsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Amazon's rank in the list (1 = top).", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "AmazonTrendingPick": { "properties": { "asin": { "description": "The product's ASIN (what amazon.product takes).", "type": "string" }, "badge": { "description": "The badge on its card, as shown (Deal); null when it has none.", "type": [ "string", "null" ] }, "currency": { "description": "ISO 4217 code of price; null when there is no price.", "type": [ "string", "null" ] }, "image_url": { "description": "The product's image URL, as the card shows it.", "format": "uri", "type": [ "string", "null" ] }, "price": { "description": "Its current price in major units of currency, as the card shows it; null when it shows none (no offer).", "format": "double", "type": [ "number", "null" ] }, "url": { "description": "The product's page in the storefront's marketplace.", "format": "uri", "type": "string" } }, "required": [ "asin", "url", "image_url", "price", "currency", "badge" ], "type": "object" }, "ApplemusicAlbumResponse": { "properties": { "data": { "$ref": "#/components/schemas/Album" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "ApplemusicAlbumSpecific": { "properties": { "audio_traits": { "description": "The audio formats it comes in (atmos, lossless, lossy-stereo, spatial, …); [] when none or the source does not show them (listed in unknown_fields). New values may be added.", "items": { "type": "string" }, "type": "array" }, "content_rating": { "description": "explicit, or clean for an edited version of something explicit; null when Apple marks neither.", "type": [ "string", "null" ] }, "editorial_summary": { "description": "Apple's one-line note on the album; null when none.", "type": [ "string", "null" ] }, "is_complete": { "description": "Every track of the release is available in this store.", "type": [ "boolean", "null" ] }, "is_mastered_for_itunes": { "description": "Carries Apple's Mastered for iTunes badge, which Apple now calls Apple Digital Master.", "type": [ "boolean", "null" ] }, "is_prerelease": { "description": "Announced, and not released yet.", "type": [ "boolean", "null" ] }, "more_by_artist": { "description": "Apple's other releases by the same artist, as many as its page shows at first; [] when none or the source does not show them (listed in unknown_fields).", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "other_versions": { "description": "Other versions of the release (the clean or explicit one, a deluxe edition); [] when none or the source does not show them (listed in unknown_fields).", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "rank": { "description": "Position on the requested chart (1 = top); null off a chart.", "format": "int64", "type": [ "integer", "null" ] }, "storefront": { "description": "The Apple Music store this answer is from, as a lowercase country code (us, jp): titles, availability, track lists and links differ by store.", "type": [ "string", "null" ] } }, "required": [ "storefront", "rank", "editorial_summary", "content_rating", "audio_traits", "is_complete", "is_prerelease", "is_mastered_for_itunes", "more_by_artist", "other_versions" ], "type": "object" }, "ApplemusicArtistResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "ApplemusicItem": { "properties": { "artist_name": { "description": "Who Apple credits for it, or a playlist's curator; null on an artist.", "type": [ "string", "null" ] }, "cover_url": { "description": "Its artwork at the largest size Apple states; null when none.", "format": "uri", "type": [ "string", "null" ] }, "duration_ms": { "description": "A song's or music video's length in milliseconds, null on other kinds.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Apple Music's ID of the item (string).", "type": "string" }, "is_explicit": { "description": "Apple marks it explicit; null on kinds it does not mark.", "type": [ "boolean", "null" ] }, "kind": { "description": "What it is. New values may be added.", "enum": [ "song", "music_video", "album", "playlist", "artist", "station" ], "type": "string" }, "released_at": { "description": "Its release date, midnight UTC of that date; null when Apple does not state it.", "format": "date-time", "type": [ "string", "null" ] }, "title": { "description": "Its title, or an artist's name.", "type": [ "string", "null" ] }, "track_count": { "description": "An album's tracks, null on other kinds.", "format": "int64", "type": [ "integer", "null" ] }, "url": { "description": "Its page; null when Apple does not state it.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "kind", "url", "title", "artist_name", "cover_url", "released_at", "track_count", "duration_ms", "is_explicit" ], "type": "object" }, "ApplemusicPlaylistSpecific": { "properties": { "audio_traits": { "description": "The audio formats the playlist comes in; [] on a station or when none. New values may be added.", "items": { "type": "string" }, "type": "array" }, "band": { "description": "How a live station is carried, as Apple says: FM, AM, DAB, Sat, Stream, …; null when it says nothing, and on a playlist. New values may be added.", "type": [ "string", "null" ] }, "curator_id": { "description": "Apple's ID of the playlist's curator; null when none is linked, as on a station.", "type": [ "string", "null" ] }, "editorial_kind": { "description": "What Apple says an editorial playlist is built around: artist-franchise (one artist, such as their Essentials or a set list); null when it says nothing, and on a station. New values may be added.", "type": [ "string", "null" ] }, "editorial_sub_kind": { "description": "Apple's finer word for that: artist-set-list, artist-created-set-list; null when it says nothing, and on a station. New values may be added.", "type": [ "string", "null" ] }, "editorial_summary": { "description": "Apple's one-line note on it; null when none.", "type": [ "string", "null" ] }, "frequency": { "description": "A broadcast station's frequency as Apple states it, in its band's usual unit (90.1 on FM, 1026 on AM); a station on several frequencies lists them separated by / (105.1/105.3/105.7); null when it states none, and on a playlist.", "type": [ "string", "null" ] }, "is_chart": { "description": "The playlist is one of Apple's charts; null on a station.", "type": [ "boolean", "null" ] }, "is_collaborative": { "description": "Several people edit the playlist; null on a station.", "type": [ "boolean", "null" ] }, "is_live": { "description": "A station that streams live rather than picking songs; null on a playlist.", "type": [ "boolean", "null" ] }, "is_subscription_required": { "description": "A station only subscribers can play; null on a playlist.", "type": [ "boolean", "null" ] }, "last_modified_at": { "description": "When the playlist last changed, RFC 3339 UTC; null on a station.", "format": "date-time", "type": [ "string", "null" ] }, "media_kind": { "description": "A station's medium, audio or video; null on a playlist.", "type": [ "string", "null" ] }, "playlist_type": { "description": "Who makes the playlist, as Apple says: editorial, external (a curator's), personal-mix, user-shared, …; null on a station. New values may be added.", "type": [ "string", "null" ] }, "rank": { "description": "Position on the requested chart (1 = top); null off a chart.", "format": "int64", "type": [ "integer", "null" ] }, "station_kind": { "description": "A station's kind as Apple says: streaming (a live stream), artistOnly, songSeeded, …; null on a playlist. New values may be added.", "type": [ "string", "null" ] }, "storefront": { "description": "The Apple Music store this answer is from, as a lowercase country code (us, jp).", "type": [ "string", "null" ] } }, "required": [ "storefront", "rank", "editorial_summary", "curator_id", "playlist_type", "editorial_kind", "editorial_sub_kind", "last_modified_at", "is_chart", "is_collaborative", "audio_traits", "station_kind", "media_kind", "band", "frequency", "is_live", "is_subscription_required" ], "type": "object" }, "ApplemusicPostSpecific": { "properties": { "air_ended_at": { "description": "When a radio episode's broadcast ended, RFC 3339 UTC; null on other posts.", "format": "date-time", "type": [ "string", "null" ] }, "album_artist_name": { "description": "Who Apple credits for the album it is on (Various Artists on a compilation); null when on none.", "type": [ "string", "null" ] }, "album_id": { "description": "The ID of the album it is on (applemusic.album takes it); null for a music video or radio episode on none.", "type": [ "string", "null" ] }, "album_title": { "description": "The title of the album it is on; null when on none.", "type": [ "string", "null" ] }, "album_url": { "description": "The album's page; null when on none.", "format": "uri", "type": [ "string", "null" ] }, "artist_name": { "description": "Who Apple credits for it, as one display string (Lady Gaga & Bradley Cooper), which can name more people than author and coauthors link.", "type": [ "string", "null" ] }, "attribution": { "description": "Who a classical work is attributed to (its composer); null on other music.", "type": [ "string", "null" ] }, "audio_locale": { "description": "The language it is sung or spoken in, as Apple's tag (en-US); null when Apple does not say.", "type": [ "string", "null" ] }, "audio_traits": { "description": "The audio formats it comes in (atmos, lossless, lossy-stereo, spatial, …); [] when none or the source does not show them. New values may be added.", "items": { "type": "string" }, "type": "array" }, "composer_name": { "description": "The writers Apple credits, as one display string; null when none or the source does not show them.", "type": [ "string", "null" ] }, "content_rating": { "description": "explicit, or clean for an edited version of something explicit; null when Apple marks neither.", "type": [ "string", "null" ] }, "curator_id": { "description": "Apple's ID of a radio episode's show, which is a curator and no artist; null on other posts.", "type": [ "string", "null" ] }, "disc_number": { "description": "The disc of that album it is on, from 1.", "format": "int64", "type": [ "integer", "null" ] }, "genres": { "description": "The genres Apple files it under, as shown in the answer's language, the main one first; [] when none.", "items": { "type": "string" }, "type": "array" }, "is_4k": { "description": "A music video that comes in 4K; null on a song.", "type": [ "boolean", "null" ] }, "is_apple_digital_master": { "description": "Carries Apple's Apple Digital Master badge.", "type": [ "boolean", "null" ] }, "is_explicit": { "description": "Apple marks it explicit.", "type": [ "boolean", "null" ] }, "is_hdr": { "description": "A music video that comes in HDR; null on a song.", "type": [ "boolean", "null" ] }, "is_live": { "description": "A radio episode on the air now; null on other posts.", "type": [ "boolean", "null" ] }, "is_lyrics_available": { "description": "Apple has its lyrics (they are for subscribers: this answer does not hold them).", "type": [ "boolean", "null" ] }, "is_mastered_for_itunes": { "description": "Carries Apple's Mastered for iTunes badge, which Apple now calls Apple Digital Master.", "type": [ "boolean", "null" ] }, "is_time_synced_lyrics_available": { "description": "Apple has its lyrics line by line in time with the audio.", "type": [ "boolean", "null" ] }, "isrc": { "description": "International Standard Recording Code, 12 characters without hyphens: what joins a recording across services. Null when the source does not show it.", "type": [ "string", "null" ] }, "long_note": { "description": "A radio episode's longer note, as Apple writes it: often the name of its show, or a shorter or older form of it, and sometimes something else, such as a date; so a hint, not an identity. Null when Apple has none, which depends on the store and language, and on other posts.", "type": [ "string", "null" ] }, "movement_count": { "description": "How many movements the work has.", "format": "int64", "type": [ "integer", "null" ] }, "movement_name": { "description": "The movement of that work; null on other music.", "type": [ "string", "null" ] }, "movement_number": { "description": "That movement's number in the work.", "format": "int64", "type": [ "integer", "null" ] }, "rank": { "description": "Position on the requested chart (1 = top); null off a chart.", "format": "int64", "type": [ "integer", "null" ] }, "storefront": { "description": "The Apple Music store this answer is from, as a lowercase country code (us, jp): titles, availability and links differ by store.", "type": [ "string", "null" ] }, "track_number": { "description": "Its position on that disc, from 1.", "format": "int64", "type": [ "integer", "null" ] }, "video_traits": { "description": "A music video's formats, as Apple names them; [] on a song or when none.", "items": { "type": "string" }, "type": "array" }, "work_name": { "description": "The classical work this is part of; null on other music.", "type": [ "string", "null" ] } }, "required": [ "storefront", "rank", "artist_name", "album_id", "album_title", "album_url", "album_artist_name", "disc_number", "track_number", "isrc", "composer_name", "genres", "is_explicit", "content_rating", "audio_traits", "audio_locale", "is_lyrics_available", "is_time_synced_lyrics_available", "is_apple_digital_master", "is_mastered_for_itunes", "work_name", "movement_name", "movement_number", "movement_count", "attribution", "is_4k", "is_hdr", "video_traits", "curator_id", "long_note", "air_ended_at", "is_live" ], "type": "object" }, "ApplemusicProfileSpecific": { "properties": { "albums": { "description": "The artist's albums, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "amg_artist_id": { "description": "The artist's ID at AllMusic (AMG), from the lookup API; null on most answers, from the catalog API.", "type": [ "string", "null" ] }, "born_or_formed": { "description": "When the artist was born or the group formed, as Apple shows it in the answer's language; null when not shown.", "type": [ "string", "null" ] }, "editorial_summary": { "description": "Apple's one-line note on the artist; null when none.", "type": [ "string", "null" ] }, "genres": { "description": "The genres Apple files the artist under, as shown in the answer's language, the main one first; [] when none.", "items": { "type": "string" }, "type": "array" }, "is_group": { "description": "A band or other group; false for one person; null when Apple does not say.", "type": [ "boolean", "null" ] }, "latest_release": { "anyOf": [ { "$ref": "#/components/schemas/ApplemusicItem" }, { "type": "null" } ], "description": "The artist's latest release as Apple shows it; null when none." }, "music_videos": { "description": "The artist's music videos, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "playlists": { "description": "Playlists Apple makes of the artist, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "similar_artists": { "description": "Artists Apple lists as similar, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "singles": { "description": "The artist's singles and EPs, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" }, "storefront": { "description": "The Apple Music store this answer is from, as a lowercase country code (us, jp): the bio's language, the sections and links differ by store.", "type": [ "string", "null" ] }, "top_songs": { "description": "The artist's top songs, best first, as many as the page shows at first; [] when none.", "items": { "$ref": "#/components/schemas/ApplemusicItem" }, "type": "array" } }, "required": [ "storefront", "genres", "is_group", "born_or_formed", "editorial_summary", "amg_artist_id", "top_songs", "latest_release", "albums", "singles", "music_videos", "playlists", "similar_artists" ], "type": "object" }, "ApplemusicSearch_albumsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own relevance order for the query.", "items": { "$ref": "#/components/schemas/Album" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicSearch_artistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own relevance order for the query.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicSearch_playlistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own relevance order for the query.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicSearch_tracksResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own relevance order for the query.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicTop_albumsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own chart order (1 = most played).", "items": { "$ref": "#/components/schemas/Album" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicTop_playlistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Apple Music's own chart order (1 = most played).", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicTop_tracksResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Apple Music's own chart order (1 = most played).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ApplemusicTrackResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "BlueskyCommentSpecific": { "properties": { "bridged_from_url": { "description": "The link Bridgy Fed records for a reply it brought to Bluesky from the fediverse or the web, usually where it was first published; null when it was written on Bluesky.", "format": "uri", "type": [ "string", "null" ] }, "cid": { "description": "The content hash (CID) of this version of the reply's record.", "type": [ "string", "null" ] }, "created_at": { "description": "The time the reply's own record states, RFC 3339 UTC: the author's client writes it, so it can be earlier than the reply went public.", "format": "date-time", "type": [ "string", "null" ] }, "embedded_record_uri": { "description": "The at:// URI of a custom feed, list or starter pack the reply embeds; null when it embeds none.", "type": [ "string", "null" ] }, "hashtags": { "description": "Hashtags in the reply, without the #; [] when none.", "items": { "type": "string" }, "type": "array" }, "indexed_at": { "description": "When Bluesky's AppView first saw the reply, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "is_hidden": { "description": "Bluesky folds the reply under the thread's \"Show more replies\" button: the post's author hid it, or Bluesky's own ranking set it aside. Null when the thread was read from the route that does not say.", "type": [ "boolean", "null" ] }, "is_hidden_by_post_author": { "description": "The post's author hid this reply from their thread.", "type": [ "boolean", "null" ] }, "is_nsfw": { "description": "The reply carries an adult or sensitive label.", "type": [ "boolean", "null" ] }, "labels": { "description": "Moderation and self labels on the reply (porn, sexual, nudity, graphic-media, spam, …), as Bluesky names them; [] when none.", "items": { "type": "string" }, "type": "array" }, "languages": { "description": "Every language the author tagged the reply with, in the author's order; [] when none.", "items": { "type": "string" }, "type": "array" }, "link_card": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyLinkCard" }, { "type": "null" } ], "description": "The link preview card the reply shows; null when none." }, "links": { "description": "The full URLs the reply's text links to, in text order; the text itself shows them shortened. [] when none.", "items": { "type": "string" }, "type": "array" }, "media": { "description": "The reply's images and video; [] when none.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "mentions": { "description": "Accounts the reply mentions, by handle; [] when none.", "items": { "type": "string" }, "type": "array" }, "quote_count": { "description": "Times the reply was quoted in another post; never negative.", "format": "int64", "type": [ "integer", "null" ] }, "quoted_post": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyEmbeddedPost" }, { "type": "null" } ], "description": "The post this reply quotes, as Bluesky embeds it; null when it quotes none, or when the quoted post was deleted, is blocked, was detached by its author, or is by an account shown only to signed-in people." }, "quoted_post_id": { "description": "The at:// ID of the post this reply quotes; null when it quotes none. Stays set when the quoted post can't be shown.", "type": [ "string", "null" ] }, "reply_root_post_id": { "description": "The at:// ID of the post that started the thread: post_id itself unless the post asked about is a reply.", "type": [ "string", "null" ] }, "repost_count": { "description": "Times the reply was reposted; never negative.", "format": "int64", "type": [ "integer", "null" ] }, "save_count": { "description": "Times the reply was bookmarked; never negative.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "repost_count", "quote_count", "save_count", "is_hidden", "is_hidden_by_post_author", "reply_root_post_id", "cid", "indexed_at", "created_at", "languages", "labels", "is_nsfw", "hashtags", "mentions", "links", "media", "link_card", "quoted_post_id", "quoted_post", "embedded_record_uri", "bridged_from_url" ], "type": "object" }, "BlueskyCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 1000), newest first with sort=newest, oldest first with sort=oldest, Most liked first, the replies Bluesky folds under \"Show more replies\" last with sort=popular.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "BlueskyEmbeddedPost": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "id": { "description": "Its at:// ID.", "type": [ "string", "null" ] }, "media": { "description": "Its images and video; [] when none.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/PostMetrics", "description": "Its own counts at fetch time." }, "published_at": { "description": "When it went public, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Its text.", "type": [ "string", "null" ] }, "url": { "description": "Its URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "text", "published_at", "author", "media", "metrics" ], "type": "object" }, "BlueskyLinkCard": { "properties": { "description": { "description": "The card's description.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The card's title.", "type": [ "string", "null" ] }, "url": { "description": "The page it links to.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "thumbnail_url" ], "type": "object" }, "BlueskyPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "BlueskyPostSpecific": { "properties": { "bridged_from_url": { "description": "The link Bridgy Fed records for a post it brought to Bluesky from the fediverse or the web, usually where the post was first published; null when it was written on Bluesky.", "format": "uri", "type": [ "string", "null" ] }, "cid": { "description": "The content hash (CID) of this version of the post's record.", "type": [ "string", "null" ] }, "created_at": { "description": "The time the post's own record states, RFC 3339 UTC: the author's client writes it, so it can be earlier than the post went public (an imported archive) or later than it; null when it can't be read as a time.", "format": "date-time", "type": [ "string", "null" ] }, "embedded_record_uri": { "description": "The at:// URI of a custom feed, list or starter pack the post embeds; null when it embeds none.", "type": [ "string", "null" ] }, "indexed_at": { "description": "When Bluesky's AppView first saw the post, RFC 3339 UTC; null when the record was read from the account's own repository instead of the AppView.", "format": "date-time", "type": [ "string", "null" ] }, "labels": { "description": "Moderation and self labels on the post (porn, sexual, nudity, graphic-media, spam, …), as Bluesky names them; [] when none.", "items": { "type": "string" }, "type": "array" }, "languages": { "description": "Every language the author tagged the post with, in the author's order; [] when none.", "items": { "type": "string" }, "type": "array" }, "link_card": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyLinkCard" }, { "type": "null" } ], "description": "The link preview card the post shows; null when none." }, "links": { "description": "The full URLs the post's text links to, in text order; the text itself shows them shortened. [] when none.", "items": { "type": "string" }, "type": "array" }, "quoted_post": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyEmbeddedPost" }, { "type": "null" } ], "description": "The post this one quotes, as Bluesky embeds it; null when it quotes none, or when the quoted post was deleted, is blocked, was detached by its author, or its author shows it only to signed-in people." }, "quoted_post_id": { "description": "The at:// ID of the post this one quotes; null when it quotes none. Stays set when the quoted post can't be shown.", "type": [ "string", "null" ] }, "reply_root_post_id": { "description": "The at:// ID of the post that started the thread; null when this post is not a reply.", "type": [ "string", "null" ] }, "reply_to_post_id": { "description": "The at:// ID of the post this one replies to; null when it is not a reply.", "type": [ "string", "null" ] }, "reposted_at": { "description": "When the account reposted it, RFC 3339 UTC; null when it is the account's own post.", "format": "date-time", "type": [ "string", "null" ] }, "reposted_by": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account whose repost put this post in the list; null when it is the account's own post, and on an endpoint that reads one post." } }, "required": [ "cid", "indexed_at", "created_at", "languages", "labels", "links", "link_card", "quoted_post_id", "quoted_post", "embedded_record_uri", "reply_to_post_id", "reply_root_post_id", "bridged_from_url", "reposted_by", "reposted_at" ], "type": "object" }, "BlueskyPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), most recent activity first: a post by when it was posted, a repost by when it was reposted.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "BlueskyProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "BlueskyProfileSpecific": { "properties": { "feed_count": { "description": "How many custom feeds the account made; null when the public page answered instead of the AppView.", "format": "int64", "type": [ "integer", "null" ] }, "indexed_at": { "description": "When Bluesky's AppView last indexed the account's profile, RFC 3339 UTC; null when the public page answered instead of the AppView.", "format": "date-time", "type": [ "string", "null" ] }, "is_labeler": { "description": "True when the account runs a moderation service that labels other accounts and posts. Null when the public page answered instead of the AppView.", "type": [ "boolean", "null" ] }, "is_trusted_verifier": { "description": "True when Bluesky trusts this account to verify others; is_verified is then true too. Null when the public page answered instead of the AppView.", "type": [ "boolean", "null" ] }, "labels": { "description": "Moderation and self labels on the account (bot, porn, spam, …), as Bluesky names them; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "list_count": { "description": "How many lists the account made; null when the public page answered instead of the AppView.", "format": "int64", "type": [ "integer", "null" ] }, "pinned_post_id": { "description": "The at:// ID of the post the account pinned, which bluesky.post takes as url; null when it pinned none, or when the public page answered instead of the AppView.", "type": [ "string", "null" ] }, "pronouns": { "description": "The pronouns the account wrote on its profile; null when it wrote none, or when the public page answered instead of the AppView.", "type": [ "string", "null" ] }, "starter_pack_count": { "description": "How many starter packs the account made; null when the public page answered instead of the AppView.", "format": "int64", "type": [ "integer", "null" ] }, "verified_by": { "description": "Who verified this account, each with when; [] when nobody did (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/BlueskyVerification" }, "type": "array" } }, "required": [ "indexed_at", "pronouns", "is_trusted_verifier", "verified_by", "pinned_post_id", "labels", "list_count", "feed_count", "starter_pack_count", "is_labeler" ], "type": "object" }, "BlueskySearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), newest first, by the time each post states, to the second with sort=newest, Bluesky's Top ranking with sort=popular.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "BlueskyVerification": { "properties": { "created_at": { "description": "When the verifier made it, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The at:// URI of the verification record.", "type": [ "string", "null" ] }, "is_valid": { "description": "Whether Bluesky still honors the verification.", "type": [ "boolean", "null" ] }, "issuer": { "$ref": "#/components/schemas/ProfileRef", "description": "The account that verified this one. is_verified and avatar_url are null: Bluesky names the verifier without them." } }, "required": [ "id", "issuer", "is_valid", "created_at" ], "type": "object" }, "Comment": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The commenting account. An account the platform no longer names (a deleted account) has a null id and username and the platform's label as display_name (Reddit: [deleted])." }, "edited_at": { "description": "When the comment was last edited, RFC 3339 UTC; null when never edited or when the platform marks edits without a time (see is_edited).", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Platform-native comment ID (string; Reddit with its t1_ prefix).", "type": "string" }, "is_by_post_author": { "description": "Written by the post's author (the creator's own comment, marked as such by the platform).", "type": [ "boolean", "null" ] }, "is_edited": { "description": "The comment was edited after posting (the platform's edited mark); null when the platform does not say.", "type": [ "boolean", "null" ] }, "is_liked_by_author": { "description": "Liked or hearted by the post's author.", "type": [ "boolean", "null" ] }, "is_pinned": { "description": "Pinned by the post's author.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/CommentMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "parent_id": { "description": "ID of the comment this replies to; null for top-level comments.", "type": [ "string", "null" ] }, "platform": { "description": "Platform ID (tiktok, youtube, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/CommentPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "post_id": { "description": "ID of the post commented on (equals post.id).", "type": "string" }, "published_at": { "description": "When the comment was posted, RFC 3339 UTC. Where the platform shows only a relative time (\"3 weeks ago\"), the latest time that label allows (the fetch time minus the stated amount), listed in approximate_fields.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Comment body as plain text.", "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Permalink, when the platform has one.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "post_id", "parent_id", "url", "text", "author", "published_at", "edited_at", "is_edited", "is_pinned", "is_liked_by_author", "is_by_post_author", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "CommentMetrics": { "properties": { "like_count": { "description": "Likes or upvotes; never negative.", "format": "int64", "type": [ "integer", "null" ] }, "reply_count": { "description": "Direct replies.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "like_count", "reply_count" ], "type": "object" }, "CommentPlatformSpecific": { "properties": { "bluesky": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyCommentSpecific" }, { "type": "null" } ], "description": "Bluesky's own reply fields." }, "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookCommentSpecific" }, { "type": "null" } ], "description": "Facebook's own comment fields." }, "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramCommentSpecific" }, { "type": "null" } ], "description": "Instagram's own comment fields." }, "reddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditCommentSpecific" }, { "type": "null" } ], "description": "Reddit's own comment fields." }, "rumble": { "anyOf": [ { "$ref": "#/components/schemas/RumbleCommentSpecific" }, { "type": "null" } ], "description": "Rumble's own comment fields." }, "snapchat": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatCommentSpecific" }, { "type": "null" } ], "description": "Snapchat's own comment fields." }, "threads": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsCommentSpecific" }, { "type": "null" } ], "description": "Threads' own reply fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokCommentSpecific" }, { "type": "null" } ], "description": "TikTok's own comment fields." } }, "type": "object" }, "Community": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (\"762.0K members\": metrics.member_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "avatar_url": { "description": "The community's icon or picture; null when it has none. Platform CDN URLs can expire.", "format": "uri", "type": [ "string", "null" ] }, "banner_url": { "description": "Header or cover image URL; null when it has none.", "format": "uri", "type": [ "string", "null" ] }, "categories": { "description": "Topics or categories the platform files it under, as shown (not normalized); [] when none.", "items": { "type": "string" }, "type": "array" }, "created_at": { "description": "When it was created, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "description": { "description": "Its short description as plain text; null when it has none.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native community ID (string): Reddit's subreddit ID with its t5_ prefix, Facebook's numeric group ID.", "type": "string" }, "is_nsfw": { "description": "Marked adult (NSFW) by the platform; null where the platform has no such mark.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/CommunityMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "moderators": { "description": "Accounts that run it (admins and moderators) the platform shows; [] when none are shown (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "name": { "description": "The name its links use, without a prefix (golang for r/golang; a Facebook group's vanity name); null when it has none (a Facebook group known only by its number).", "type": [ "string", "null" ] }, "platform": { "description": "Platform ID (reddit, facebook, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/CommunityPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "privacy": { "description": "public: anyone can see its posts and any member can post; restricted: anyone can see its posts, only approved members can post; private: only members can see its posts (a private community answers private_or_unavailable unless its page shows these fields logged out). New values may be added; treat unknown values as restricted.", "enum": [ "public", "restricted", "private", null ], "type": [ "string", "null" ] }, "rules": { "description": "Its published rules, in the platform's order; [] when it has none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/CommunityRule" }, "type": "array" }, "title": { "description": "The community's title as its page shows it (\"The Go Programming Language\"; what Facebook calls a group's name); null when it has none.", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical community URL (https://www.reddit.com/r/golang/, https://www.facebook.com/groups//).", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "name", "title", "description", "url", "avatar_url", "banner_url", "privacy", "is_nsfw", "categories", "rules", "moderators", "created_at", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "CommunityMetrics": { "properties": { "member_count": { "description": "Members (on Reddit, subscribers) as the platform counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "member_count" ], "type": "object" }, "CommunityPlatformSpecific": { "properties": { "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookCommunitySpecific" }, { "type": "null" } ], "description": "A Facebook group's own fields." }, "reddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditCommunitySpecific" }, { "type": "null" } ], "description": "A subreddit's own fields." }, "x": { "anyOf": [ { "$ref": "#/components/schemas/XCommunitySpecific" }, { "type": "null" } ], "description": "An X Community's own fields." } }, "type": "object" }, "CommunityRule": { "properties": { "description": { "description": "Its explanation as plain text; null when it has none.", "type": [ "string", "null" ] }, "title": { "description": "The rule's short title (Reddit short_name, Facebook rule_title).", "type": "string" } }, "required": [ "title", "description" ], "type": "object" }, "CommunitySummary": { "properties": { "avatar_url": { "description": "The community's icon or picture; null until the result is filled.", "format": "uri", "type": [ "string", "null" ] }, "description": { "description": "Its description as the index's snippet quotes it (often cut short: see approximate_fields); null when it quotes none (a platform's generic page text is not one).", "type": [ "string", "null" ] }, "id": { "description": "Platform-native community ID; null until the result is filled.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/CommunityMetrics", "description": "Counts as the index's text states them (\"762K members\"; rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "name": { "description": "The name its links use, as the matched link names it (golang for r/golang, a Facebook group's vanity name); null when the link names it only by number.", "type": [ "string", "null" ] }, "privacy": { "description": "Who can see and post, as the index's text says (\"Public group\"); null when it does not. New values may be added; treat unknown values as restricted.", "enum": [ "public", "restricted", "private", null ], "type": [ "string", "null" ] }, "title": { "description": "The community's title as the index's title shows it; null when it shows none.", "type": [ "string", "null" ] }, "url": { "description": "Canonical community URL (equals the result's url).", "format": "uri", "type": "string" } }, "required": [ "id", "name", "title", "description", "url", "avatar_url", "privacy", "metrics" ], "type": "object" }, "Download": { "properties": { "approximate_fields": { "description": "JSON paths of estimated or rounded values (a size from bitrate × duration, a duration in whole seconds). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The posting account." }, "duration_ms": { "description": "Length of the post's primary video or audio in milliseconds; null for photo posts.", "format": "int64", "type": [ "integer", "null" ] }, "files": { "description": "The post's files by item_index, the sound last; each item's best first (a url, the item's own kind before its separate audio, no watermark, with sound, not a manifest, then resolution). At least one has a url.", "items": { "$ref": "#/components/schemas/DownloadFile" }, "type": "array" }, "id": { "description": "Platform-native ID of the post (equals post.id).", "type": "string" }, "platform": { "description": "Platform ID (tiktok, instagram, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/DownloadPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "platform_type": { "description": "The platform's own product label, lowercase (reel, short, story, …), as post.platform_type.", "type": [ "string", "null" ] }, "published_at": { "description": "When the post went public, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Caption or body as plain text.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Largest cover or poster image URL of the post (the first attachment's; each file's own is files[].thumbnail_url); CDN links can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Headline (Reddit title, Facebook video title); null on caption-only platforms.", "type": [ "string", "null" ] }, "type": { "description": "The post's content shape, as post.type. New values may be added; treat unknown values as other.", "enum": [ "video", "image", "carousel", "audio" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical URL of the post.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "type", "platform_type", "title", "text", "author", "published_at", "duration_ms", "thumbnail_url", "files", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "DownloadFile": { "properties": { "audio_codec": { "description": "Audio codec of the file's sound; null when it has none. New values may be added; treat unknown values as other.", "enum": [ "aac", "opus", "mp3", null ], "type": [ "string", "null" ] }, "bitrate_kbps": { "description": "Average bitrate in kbit/s (video and audio), rounded; null when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "duration_ms": { "description": "Duration in milliseconds (video and audio); null for images and when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "expires_at": { "description": "When url stops working, RFC 3339 UTC, read from its signature; null when unknown or it does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "frame_rate": { "description": "Frames per second (video and gif), to two decimals (an NTSC 30000/1001 is 29.97); null for images and audio and when unknown.", "format": "double", "type": [ "number", "null" ] }, "height": { "description": "Height in pixels (images and video).", "format": "int64", "type": [ "integer", "null" ] }, "is_video_only": { "description": "True: video without its sound, which is the audio file of the same item_index. False: it plays with its sound, or has none. Null for images and audio.", "type": [ "boolean", "null" ] }, "is_watermarked": { "description": "The platform's logo or the author's handle is burned into the picture (TikTok's download file); false: the clean original. Null for audio.", "type": [ "boolean", "null" ] }, "item_index": { "description": "0-based position of the file's attachment in display order (post.media[item_index]); null for the post's sound (a slideshow's soundtrack).", "format": "int64", "type": [ "integer", "null" ] }, "mime_type": { "description": "IANA media type without parameters (video/mp4, image/jpeg, audio/mp4); application/vnd.apple.mpegurl (HLS) or application/dash+xml (DASH) for a streaming manifest.", "type": [ "string", "null" ] }, "size_bytes": { "description": "File size in bytes; an estimate from bitrate × duration is in approximate_fields.", "format": "int64", "type": [ "integer", "null" ] }, "thumbnail_url": { "description": "Cover image of this file's attachment (post.media[item_index].thumbnail_url), built like url; null for images and audio and when unknown.", "format": "uri", "type": [ "string", "null" ] }, "type": { "description": "Kind of file, as media[].type. New values may be added; treat unknown values as other.", "enum": [ "video", "image", "audio", "gif" ], "type": "string" }, "url": { "description": "Direct CDN file URL, fetchable without cookies or headers; null when the platform serves it only with its cookie or to the IP that asked.", "format": "uri", "type": [ "string", "null" ] }, "video_codec": { "description": "Video codec (h264 plays everywhere; h265, vp9 and av1 need newer players); null for images and audio. New values may be added; treat unknown values as other.", "enum": [ "h264", "h265", "vp9", "av1", null ], "type": [ "string", "null" ] }, "width": { "description": "Width in pixels (images and video).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "item_index", "type", "url", "expires_at", "mime_type", "size_bytes", "width", "height", "duration_ms", "bitrate_kbps", "frame_rate", "video_codec", "audio_codec", "is_watermarked", "is_video_only", "thumbnail_url" ], "type": "object" }, "DownloadPlatformSpecific": { "properties": { "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokDownloadSpecific" }, { "type": "null" } ], "description": "A TikTok download's own fields." } }, "type": "object" }, "Effect": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count from \"304.5M videos\"). A list path (media) means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "creator": { "$ref": "#/components/schemas/ProfileRef", "description": "The account that made the effect. Fields are null where the platform names no account (TikTok's own effects show only a display name)." }, "description": { "description": "The creator's description of the effect; null when empty or not exposed.", "type": [ "string", "null" ] }, "icon_url": { "description": "The effect's icon image URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "Platform-native effect ID (string; TikTok's effect ID, the number ending its /effect/ link).", "type": "string" }, "is_official": { "description": "True when the platform itself made the effect, false for an effect made by a community creator; null when not exposed.", "type": [ "boolean", "null" ] }, "media": { "description": "Preview images and videos the platform shows of the effect in use; [] if none or not exposed.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/EffectMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "name": { "description": "The effect's name as the platform shows it.", "type": "string" }, "platform": { "description": "Platform ID (tiktok, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/EffectPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "published_at": { "description": "When the effect was published, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical public page of the effect.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "name", "description", "creator", "is_official", "icon_url", "media", "published_at", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "EffectMetrics": { "properties": { "post_count": { "description": "Public posts made with the effect, as the platform counts them (TikTok's \"videos\" figure on the effect page).", "format": "int64", "type": [ "integer", "null" ] }, "total_view_count": { "description": "Views across all posts made with the effect.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "post_count", "total_view_count" ], "type": "object" }, "EffectPlatformSpecific": { "properties": { "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokEffectSpecific" }, { "type": "null" } ], "description": "A TikTok effect's own fields." } }, "type": "object" }, "Embed": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The account the embedded item belongs to: the post's author, the playlist's owner, or for a profile the account itself." }, "embed_url": { "description": "The platform's embed page alone, for an iframe's src (what html's script loads); null when the platform has none.", "format": "uri", "type": [ "string", "null" ] }, "height": { "description": "Height in pixels; null when the embed sizes itself to its content (Instagram's always do).", "format": "int64", "type": [ "integer", "null" ] }, "html": { "description": "The platform's embed code, ready to paste into an HTML page: its markup and, unless asked to leave it out, the script tag that turns it into the embedded post or profile. It loads the platform's script and content in the visitor's browser.", "type": "string" }, "id": { "description": "The ID the platform's embed is addressed by (as in embed_url): a post's ID (equals post.id), a playlist's ID, and for a profile the account's username on platforms whose profile embeds are addressed by it (Instagram, TikTok); the account's numeric ID, when known, is author.id.", "type": "string" }, "platform": { "description": "Platform ID (instagram, youtube, tiktok, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/EmbedPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "thumbnail_height": { "description": "Height of thumbnail_url in pixels; null when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "thumbnail_url": { "description": "Preview image URL the platform names for the embed (a post's image or cover, a profile's picture); platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "thumbnail_width": { "description": "Width of thumbnail_url in pixels; null when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The title the platform gives the embed: a post's caption or a video's title, a profile's page title; null when it has none.", "type": [ "string", "null" ] }, "type": { "description": "What is embedded, named by its resource: post (any post: photo, carousel, video, reel), profile (an account), or playlist. New values may be added; treat unknown values as other.", "enum": [ "post", "profile", "playlist" ], "type": "string" }, "url": { "description": "Canonical public URL of what is embedded (post.url, profile.url): the link the embed opens.", "format": "uri", "type": "string" }, "width": { "description": "Width in pixels the embed is laid out for (its maximum when it is responsive); null when the platform does not say.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "platform", "type", "id", "url", "html", "embed_url", "width", "height", "title", "author", "thumbnail_url", "thumbnail_width", "thumbnail_height", "platform_specific" ], "type": "object" }, "EmbedPlatformSpecific": { "type": "object" }, "Engagement": { "properties": { "approximate_fields": { "description": "JSON paths of figures computed from an approximate input (a rounded follower or view count, a relative publish time); a posts[] path means at least one post's. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "bottom_post_id": { "description": "ID of the rated post with the fewest interactions; the first on a tie.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native account ID (equals profile.id).", "type": "string" }, "metrics": { "$ref": "#/components/schemas/EngagementMetrics", "description": "Figures over the counted posts (by the account, not pinned); each null when no counted post has its inputs." }, "newest_post_at": { "description": "Publish time of the newest counted post, RFC 3339 UTC: when the account last posted.", "format": "date-time", "type": [ "string", "null" ] }, "oldest_post_at": { "description": "Publish time of the oldest counted post, RFC 3339 UTC: where the sample starts.", "format": "date-time", "type": [ "string", "null" ] }, "platform": { "description": "Platform ID (tiktok, instagram, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/EngagementPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "posts": { "description": "The sampled recent posts in the profile's order, each with its own figures. [] when none; [] and in unknown_fields when unreadable (a private account, a failed posts request).", "items": { "$ref": "#/components/schemas/EngagementPost" }, "type": "array" }, "profile": { "$ref": "#/components/schemas/Profile", "description": "The account, as its profile endpoint returns it; its metrics.follower_count divides every engagement_rate." }, "top_post_id": { "description": "ID of the rated post with the most interactions (likes + comments); the first on a tie.", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (posts, metrics.formats). [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical profile URL (equals profile.url).", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "profile", "posts", "metrics", "oldest_post_at", "newest_post_at", "top_post_id", "bottom_post_id", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "EngagementFormat": { "properties": { "counted_post_count": { "description": "Counted posts of this type.", "format": "int64", "type": "integer" }, "engagement_rate": { "description": "Mean engagement_rate of the rated posts of this type.", "format": "double", "type": [ "number", "null" ] }, "interactions_per_post": { "description": "Mean interactions per rated post of this type.", "format": "double", "type": [ "number", "null" ] }, "type": { "description": "Post type (post.type). New values may be added; treat unknown values as other.", "enum": [ "video", "image", "carousel", "text", "link", "audio" ], "type": "string" }, "views_per_post": { "description": "Mean views per post of this type.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "type", "counted_post_count", "views_per_post", "interactions_per_post", "engagement_rate" ], "type": "object" }, "EngagementMetrics": { "properties": { "comment_to_like_ratio": { "description": "The rated posts' comments over their likes.", "format": "double", "type": [ "number", "null" ] }, "comments_per_post": { "description": "Mean comments per counted post with a comment count.", "format": "double", "type": [ "number", "null" ] }, "counted_post_count": { "description": "Sampled posts that enter the figures.", "format": "int64", "type": [ "integer", "null" ] }, "engagement_rate": { "description": "Mean of the rated posts' engagement_rate (interactions per follower), as a fraction (0.042 = 4.2%).", "format": "double", "type": [ "number", "null" ] }, "engagement_rate_stddev": { "description": "Population standard deviation of the rated posts' engagement_rate: how uneven they perform. Null under 2 rated posts.", "format": "double", "type": [ "number", "null" ] }, "formats": { "description": "The counted posts by post type, most posts first; [] when none are counted.", "items": { "$ref": "#/components/schemas/EngagementFormat" }, "type": "array" }, "interactions_per_post": { "description": "Mean interactions (likes + comments) per rated post; known without a follower count.", "format": "double", "type": [ "number", "null" ] }, "likes_per_post": { "description": "Mean likes per counted post with a like count.", "format": "double", "type": [ "number", "null" ] }, "median_engagement_rate": { "description": "Median of the rated posts' engagement_rate.", "format": "double", "type": [ "number", "null" ] }, "median_views_per_post": { "description": "Median views per counted post: the typical post, unmoved by one viral hit.", "format": "double", "type": [ "number", "null" ] }, "posts_per_week": { "description": "Posting cadence: intervals between counted posts per week from oldest_post_at to newest_post_at.", "format": "double", "type": [ "number", "null" ] }, "quotes_per_post": { "description": "Mean quote posts per counted post with a quote count.", "format": "double", "type": [ "number", "null" ] }, "rated_post_count": { "description": "Counted posts with known like and comment counts: what interaction figures and rates are over.", "format": "int64", "type": [ "integer", "null" ] }, "reposts_per_post": { "description": "Mean reposts per counted post with a repost count.", "format": "double", "type": [ "number", "null" ] }, "sampled_post_count": { "description": "Posts in the sample, the length of posts; null when unreadable.", "format": "int64", "type": [ "integer", "null" ] }, "saves_per_post": { "description": "Mean saves per counted post with a save count.", "format": "double", "type": [ "number", "null" ] }, "shares_per_post": { "description": "Mean shares per counted post with a share count.", "format": "double", "type": [ "number", "null" ] }, "view_engagement_rate": { "description": "Mean of the rated posts' view_engagement_rate (interactions per view), as a fraction.", "format": "double", "type": [ "number", "null" ] }, "views_per_post": { "description": "Mean views per counted post with a view count.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "sampled_post_count", "counted_post_count", "rated_post_count", "views_per_post", "median_views_per_post", "likes_per_post", "comments_per_post", "shares_per_post", "reposts_per_post", "quotes_per_post", "saves_per_post", "interactions_per_post", "engagement_rate", "median_engagement_rate", "engagement_rate_stddev", "view_engagement_rate", "comment_to_like_ratio", "posts_per_week", "formats" ], "type": "object" }, "EngagementPlatformSpecific": { "type": "object" }, "EngagementPost": { "properties": { "engagement_rate": { "description": "Interactions (likes + comments) per follower, as a fraction (0.042 = 4.2%); can exceed 1. Null when a count is unknown or there are no followers.", "format": "double", "type": [ "number", "null" ] }, "engagement_vs_median": { "description": "Interactions over the rated posts' median: 1 is typical for the account, 3 three times typical.", "format": "double", "type": [ "number", "null" ] }, "is_counted": { "description": "True when the post enters the figures: by the account itself and not pinned.", "type": "boolean" }, "post": { "$ref": "#/components/schemas/Post", "description": "The post, as the platform's posts endpoint returns it." }, "view_engagement_rate": { "description": "Interactions (likes + comments) per view, as a fraction. Null when a count is unknown or there are no views.", "format": "double", "type": [ "number", "null" ] }, "views_vs_median": { "description": "Views over metrics.median_views_per_post: 1 is typical, 3 three times typical.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "post", "is_counted", "engagement_rate", "view_engagement_rate", "engagement_vs_median", "views_vs_median" ], "type": "object" }, "ErrorBody": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ], "type": "object" }, "ErrorDetail": { "properties": { "charged": { "description": "Whether the request was charged: always false, failed requests are free.", "type": "boolean" }, "code": { "description": "Machine-readable error code (see the error codes list); stable.", "enum": [ "invalid_input", "invalid_cursor", "unauthorized", "forbidden", "insufficient_credits", "spend_limit_reached", "rate_limited", "request_too_large", "method_not_allowed", "endpoint_retired", "idempotency_key_reused", "idempotency_key_in_progress", "job_not_found", "unknown_endpoint", "not_found", "private_or_unavailable", "no_transcript", "no_live", "no_media", "upstream_blocked", "upstream_error", "overloaded", "internal" ], "type": "string" }, "details": { "description": "The code's dynamic values (the error codes list documents each code's keys); {} when none.", "type": "object" }, "doc_url": { "description": "URL of this code's documentation.", "type": "string" }, "message": { "description": "What went wrong and how to fix it, for humans and agents; wording may change.", "type": "string" }, "param": { "description": "The query parameter or header the error is about; null when it is not about one input.", "type": [ "string", "null" ] }, "remediation": { "description": "What to do about this code, one sentence.", "type": "string" }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "retryable": { "description": "True when repeating the same request later may succeed (after details.retry_after when present).", "type": "boolean" }, "status": { "description": "The HTTP status of the response, repeated for clients that only see the body.", "format": "int64", "type": "integer" } }, "required": [ "code", "message", "request_id", "status", "retryable", "param", "remediation", "doc_url", "details", "charged" ], "type": "object" }, "EventMetrics": { "properties": { "attendee_count": { "description": "People who said they are going (after the event: who went), as the platform counts them; null when not shown.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "attendee_count" ], "type": "object" }, "EventPlatformSpecific": { "properties": { "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookEventSpecific" }, { "type": "null" } ], "description": "A Facebook event's own fields." } }, "type": "object" }, "FacebookAdAgeGenderReach": { "properties": { "age_range": { "description": "The age range (18-24, 65+).", "type": "string" }, "female": { "description": "Women reached; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "male": { "description": "Men reached; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "unknown": { "description": "Accounts of unknown gender reached; null when not shown.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "age_range", "male", "female", "unknown" ], "type": "object" }, "FacebookAdAgeGenderShare": { "properties": { "age_range": { "description": "The age range (18-24, 65+).", "type": "string" }, "female": { "description": "Share among women (0 to 1); null when not shown.", "format": "double", "type": [ "number", "null" ] }, "male": { "description": "Share among men (0 to 1); null when not shown.", "format": "double", "type": [ "number", "null" ] }, "unknown": { "description": "Share among people of unknown gender (0 to 1); null when not shown.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "age_range", "male", "female", "unknown" ], "type": "object" }, "FacebookAdCountryReach": { "properties": { "ages": { "description": "Unique accounts reached there per age range.", "items": { "$ref": "#/components/schemas/FacebookAdAgeGenderReach" }, "type": "array" }, "country_code": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string" } }, "required": [ "country_code", "ages" ], "type": "object" }, "FacebookAdImpressionShares": { "properties": { "by_age_gender": { "description": "Share of impressions per age range, by gender (0 to 1).", "items": { "$ref": "#/components/schemas/FacebookAdAgeGenderShare" }, "type": "array" }, "by_region": { "description": "Share of impressions per region (0 to 1).", "items": { "$ref": "#/components/schemas/FacebookAdRegionShare" }, "type": "array" } }, "required": [ "by_age_gender", "by_region" ], "type": "object" }, "FacebookAdLocation": { "properties": { "is_excluded": { "description": "The advertiser excluded the place rather than targeting it.", "type": "boolean" }, "name": { "description": "The place as Meta names it (United Kingdom, Berlin).", "type": "string" }, "type": { "description": "The kind of place (countries, regions, cities); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "name", "type", "is_excluded" ], "type": "object" }, "FacebookAdRegionShare": { "properties": { "region": { "description": "The region as Meta names it (California).", "type": "string" }, "share": { "description": "Its share (0 to 1); null when not shown.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "region", "share" ], "type": "object" }, "FacebookAdResponse": { "properties": { "data": { "$ref": "#/components/schemas/Ad" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookAdSpecific": { "properties": { "advertiser_categories": { "description": "The advertiser page's categories (Wine/spirits); [] when not shown (in unknown_fields when not shown).", "items": { "type": "string" }, "type": "array" }, "advertiser_instagram": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The advertiser's Instagram account, when Meta links one; null otherwise or outside the ad's details." }, "advertiser_instagram_follower_count": { "description": "Followers of the advertiser's Instagram account; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "advertiser_like_count": { "description": "The advertiser's page likes; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "beneficiary": { "description": "Whom the ad benefits, as disclosed for ads shown in the EU; null when not disclosed.", "type": [ "string", "null" ] }, "collation_count": { "description": "How many ads share this creative and text; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "collation_id": { "description": "The group of ads that share this creative and text; null when not shown.", "type": [ "string", "null" ] }, "cta_type": { "description": "The call to action's type (shop_now, learn_more), whatever language cta_text is in; null when the ad has none.", "type": [ "string", "null" ] }, "impression_shares": { "anyOf": [ { "$ref": "#/components/schemas/FacebookAdImpressionShares" }, { "type": "null" } ], "description": "A political or social-issue ad's audience: its share of impressions by age and gender and by region; null for other ads." }, "is_advertiser_deleted": { "description": "The advertiser's page has since been deleted; null when not shown.", "type": [ "boolean", "null" ] }, "is_removed": { "description": "Meta took the ad down for breaking its standards; null when not shown.", "type": [ "boolean", "null" ] }, "is_synthetic": { "description": "The advertiser disclosed digitally created or altered media (an AI disclosure); null when not shown.", "type": [ "boolean", "null" ] }, "link_caption": { "description": "The link caption shown under the creative (usually the destination's domain); null when none.", "type": [ "string", "null" ] }, "partner": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The creator whose post a branded content ad promotes for the advertiser; null for other ads." }, "removal_reasons": { "description": "Meta's reasons for taking it down; [] when none (in unknown_fields when not shown).", "items": { "type": "string" }, "type": "array" }, "special_ad_categories": { "description": "Meta's special ad categories the ad is filed under (political, housing, employment, credit); [] for an ordinary ad.", "items": { "type": "string" }, "type": "array" }, "targeting": { "description": "Whom the advertiser targeted and whom the ad reached, per region that discloses it (the EU, the UK); [] when not disclosed (in unknown_fields when not shown).", "items": { "$ref": "#/components/schemas/FacebookAdTargeting" }, "type": "array" } }, "required": [ "cta_type", "link_caption", "special_ad_categories", "collation_id", "collation_count", "partner", "advertiser_like_count", "advertiser_categories", "is_advertiser_deleted", "advertiser_instagram", "advertiser_instagram_follower_count", "beneficiary", "is_synthetic", "is_removed", "removal_reasons", "targeting", "impression_shares" ], "type": "object" }, "FacebookAdTargeting": { "properties": { "age_max": { "description": "Oldest age targeted (65 means 65 and over); null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "age_min": { "description": "Youngest age targeted; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "genders": { "description": "Genders targeted (female, male); [] when all.", "items": { "type": "string" }, "type": "array" }, "locations": { "description": "Places the advertiser targeted or excluded; [] when not shown.", "items": { "$ref": "#/components/schemas/FacebookAdLocation" }, "type": "array" }, "reach": { "description": "Unique accounts the ad reached in the region; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "reach_by_country": { "description": "Unique accounts reached per country, by age range and gender; [] when not shown.", "items": { "$ref": "#/components/schemas/FacebookAdCountryReach" }, "type": "array" }, "region": { "description": "The disclosing region. New values may be added.", "enum": [ "eu", "uk" ], "type": "string" } }, "required": [ "region", "reach", "genders", "age_min", "age_max", "locations", "reach_by_country" ], "type": "object" }, "FacebookAd_transcriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookAdminCountry": { "properties": { "count": { "description": "How many of the Page's admins are there.", "format": "int64", "type": [ "integer", "null" ] }, "country": { "description": "The country's name.", "type": [ "string", "null" ] } }, "required": [ "country", "count" ], "type": "object" }, "FacebookAdsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), most recently started first, in Meta's recency groups with sort=newest, most impressions first with sort=popular.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookBusinessDay": { "properties": { "day": { "description": "The day of the week, as Facebook names it (Monday).", "type": [ "string", "null" ] }, "hours": { "description": "The day's hours as shown, such as 11:00 AM - 2:30 PM, 4:30 PM - 9:30 PM, or Closed.", "type": [ "string", "null" ] }, "periods": { "description": "The same hours as 24-hour times, one per opening; [] on a closed day or when the text is not a list of times.", "items": { "$ref": "#/components/schemas/FacebookBusinessPeriod" }, "type": "array" } }, "required": [ "day", "hours", "periods" ], "type": "object" }, "FacebookBusinessPeriod": { "properties": { "close": { "description": "Closing time, 24-hour HH:MM, local to the business.", "type": "string" }, "open": { "description": "Opening time, 24-hour HH:MM, local to the business.", "type": "string" } }, "required": [ "open", "close" ], "type": "object" }, "FacebookCommentSpecific": { "properties": { "author_gender": { "description": "The commenter's gender as Facebook states it to logged-out visitors; null when it states none (Pages, most accounts that chose not to). New values may be added.", "enum": [ "male", "female", null ], "type": [ "string", "null" ] }, "image_url": { "description": "The photo the comment attaches, on Facebook's CDN (signed, expires within days); null when it attaches none.", "format": "uri", "type": [ "string", "null" ] }, "reactions": { "description": "Reactions by type, most first, as Facebook lists them under the comment; [] when none.", "items": { "$ref": "#/components/schemas/FacebookReaction" }, "type": "array" } }, "required": [ "reactions", "author_gender", "image_url" ], "type": "object" }, "FacebookCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), newest first with sort=newest, Facebook's All comments view: every top-level comment, the most relevant first with sort=relevance.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookCommunitySpecific": { "properties": { "admin_count": { "description": "Administrators of the group.", "format": "int64", "type": [ "integer", "null" ] }, "admin_ids": { "description": "The IDs of the administrators among moderators (the rest are its moderators), as far as Facebook shows them; [] when none are shown (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "daily_post_count": { "description": "Posts in the group in the last day, as Facebook counts them.", "format": "int64", "type": [ "integer", "null" ] }, "history_summary": { "description": "Facebook's summary of the group's history (created, name changes), as shown.", "type": [ "string", "null" ] }, "is_visible": { "description": "True when anyone can find the group in search (Facebook's Visible), false when only members can (Hidden).", "type": [ "boolean", "null" ] }, "locations": { "description": "The places the group's admins tie it to, as shown; [] when none.", "items": { "type": "string" }, "type": "array" }, "moderator_count": { "description": "Moderators of the group (not counting its administrators).", "format": "int64", "type": [ "integer", "null" ] }, "monthly_post_count": { "description": "Posts in the group in the last month, as Facebook counts them.", "format": "int64", "type": [ "integer", "null" ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The Page or account the group is shown as belonging to (Facebook's \"Group by ...\" on its cover); null when Facebook names none." }, "weekly_new_member_count": { "description": "Members who joined in the last week (parsed from Facebook's text).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "daily_post_count", "monthly_post_count", "weekly_new_member_count", "admin_count", "admin_ids", "moderator_count", "is_visible", "history_summary", "owner", "locations" ], "type": "object" }, "FacebookEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookEventMetrics": { "properties": { "interested_count": { "description": "People who marked themselves interested (not going), as Facebook counts them.", "format": "int64", "type": [ "integer", "null" ] }, "response_count": { "description": "People who responded going or interested, together, as Facebook counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "interested_count", "response_count" ], "type": "object" }, "FacebookEventResponse": { "properties": { "data": { "$ref": "#/components/schemas/ScheduledEvent", "description": "In Facebook's words: `metrics.attendee_count` is going." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookEventSpecific": { "properties": { "city_id": { "description": "ID of the city Facebook files it under (its city Page, the number in facebook.com/events/explore///, which lists that city's events); place.city is the city's name. Null when not shown.", "type": [ "string", "null" ] }, "date_text": { "description": "When it happens, as Facebook shows it, in the event's own time zone (\"Sun, Nov 8 at 3:00 PM EST and 7 more\", \"Sat, Nov 21 - Nov 22\", \"Happening now\"): on a recurring event its next date, where start_at is its first. Display text in the viewer's language; null when not shown.", "type": [ "string", "null" ] }, "frequency": { "description": "How often it repeats, as Facebook names it, lowercased (single for a one-off event); null when not shown.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/FacebookEventMetrics", "description": "Facebook's own counts at fetch time; null = hidden or not exposed, 0 = zero." }, "occurrence_count": { "description": "Dates of its recurring series (the parent's child events); 0 for a single event.", "format": "int64", "type": [ "integer", "null" ] }, "price_text": { "description": "The ticket price or range as Facebook shows it (\"$25 – $40\", \"Free\"); null when none is shown.", "type": [ "string", "null" ] }, "ticket_provider": { "description": "Who sells the tickets ticket_url links to (Ticketmaster, Eventbrite), as Facebook names it; null when none.", "type": [ "string", "null" ] } }, "required": [ "ticket_provider", "price_text", "date_text", "frequency", "occurrence_count", "city_id", "metrics" ], "type": "object" }, "FacebookEventsResponse": { "properties": { "data": { "description": "Up to limit items (page size 8), oldest first. In Facebook's words: `metrics.attendee_count` is going.", "items": { "$ref": "#/components/schemas/ScheduledEvent" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookGroupResponse": { "properties": { "data": { "$ref": "#/components/schemas/Community" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookGroup_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 3), the group's items for sale, newest first by when each entered the group's feed with sort=listings, Facebook's New posts: newest first by when a post entered the group's feed with sort=newest, the posts most recently commented on or reacted to first with sort=recent_activity, Facebook's Most relevant ranking of the group's posts with sort=relevance.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookLink": { "properties": { "image_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The card's headline.", "type": [ "string", "null" ] }, "url": { "description": "The linked page, as the author shared it (Facebook's l.facebook.com redirect removed).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "title", "image_url" ], "type": "object" }, "FacebookListingResponse": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookNameChange": { "properties": { "changed_at": { "description": "When it changed, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "name": { "description": "The name it took.", "type": "string" } }, "required": [ "name", "changed_at" ], "type": "object" }, "FacebookPhotosResponse": { "properties": { "data": { "description": "Up to limit items (page size 8), Newest first, as the Photos tab shows them.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookPlaceSpecific": { "properties": { "checkin_count": { "description": "People who checked in at the place, as Facebook shows it; null when Facebook shows no count (it shows none for a city).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "checkin_count" ], "type": "object" }, "FacebookPlace_eventsResponse": { "properties": { "data": { "description": "Up to limit items (page size 12), Facebook's ranking of the city's events, not by date. In Facebook's words: `metrics.attendee_count` is going.", "items": { "$ref": "#/components/schemas/ScheduledEvent" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookPostGroup": { "properties": { "id": { "description": "The group's numeric ID.", "type": "string" }, "name": { "description": "The group's name, as its page shows it.", "type": [ "string", "null" ] }, "url": { "description": "The group's URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "name", "url" ], "type": "object" }, "FacebookPostListing": { "properties": { "id": { "description": "The listing's ID.", "type": [ "string", "null" ] }, "is_sold": { "description": "Marked sold.", "type": [ "boolean", "null" ] }, "location": { "description": "Where it is, as Facebook shows it.", "type": [ "string", "null" ] }, "price_text": { "description": "Its price as Facebook shows it (BDT14,000, FREE).", "type": [ "string", "null" ] }, "title": { "description": "The item's name.", "type": [ "string", "null" ] }, "url": { "description": "The item's Marketplace page (facebook.com/marketplace/item/), which facebook.listing reads; null for an item listed only in the group.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "title", "price_text", "location", "is_sold", "url" ], "type": "object" }, "FacebookPostMusic": { "properties": { "id": { "description": "Facebook's ID of the sound.", "type": [ "string", "null" ] }, "is_original": { "description": "The creator's own audio (false: a track from Facebook's library).", "type": [ "boolean", "null" ] }, "title": { "description": "The sound's title as the reel shows it (\"National Geographic · Original audio\" for a creator's own).", "type": [ "string", "null" ] } }, "required": [ "id", "title", "is_original" ], "type": "object" }, "FacebookPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookPostSpecific": { "properties": { "feedback_id": { "description": "Facebook's feedback ID of the post: the thread its comments and reactions hang on.", "type": [ "string", "null" ] }, "group": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPostGroup" }, { "type": "null" } ], "description": "The group the post was published in; null when it is not a group's post." }, "is_attachment_unavailable": { "description": "What the post attached is gone: Facebook shows it as unavailable or empty, so the post can have no text and no media. Null when the page does not say.", "type": [ "boolean", "null" ] }, "link": { "anyOf": [ { "$ref": "#/components/schemas/FacebookLink" }, { "type": "null" } ], "description": "The link card a post shares (an article, a site, an event); null when none." }, "listing": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPostListing" }, { "type": "null" } ], "description": "The item for sale a group's post lists; null when it lists none, or none any more (a listing taken down: see is_attachment_unavailable)." }, "music": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPostMusic" }, { "type": "null" } ], "description": "The sound a reel credits; null when the post credits none, or the endpoint can't see it." }, "reactions": { "description": "Reactions by type, most first, as Facebook lists them under the post; [] when none.", "items": { "$ref": "#/components/schemas/FacebookReaction" }, "type": "array" }, "shared_post": { "anyOf": [ { "$ref": "#/components/schemas/FacebookSharedPost" }, { "type": "null" } ], "description": "The post this one reshares; null when it is not a reshare." }, "video_id": { "description": "The video's ID (facebook.com/reel/) on a video or reel post; null on other posts.", "type": [ "string", "null" ] } }, "required": [ "feedback_id", "video_id", "reactions", "shared_post", "link", "music", "group", "listing", "is_attachment_unavailable" ], "type": "object" }, "FacebookPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 3), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookProductSpecific": { "properties": { "delivery_types": { "description": "How the item changes hands, as Marketplace lists it: in_person (local pickup), shipping, door_pickup, door_dropoff, public_meetup. [] when not shown (listed in unknown_fields). New values may be added.", "items": { "type": "string" }, "type": "array" }, "is_buy_now_enabled": { "description": "The item can be bought on Facebook with Marketplace checkout (Buy now); false: the buyer arranges payment with the seller.", "type": [ "boolean", "null" ] }, "is_local_pickup": { "description": "The buyer can pick it up from the seller in person.", "type": [ "boolean", "null" ] }, "latitude": { "description": "WGS 84 latitude of the listing's area in degrees (Facebook shows an area, not the seller's address: always listed in approximate_fields); set together with longitude.", "format": "double", "type": [ "number", "null" ] }, "location": { "description": "Where the item is (a city or area, Austin, TX), as Marketplace shows it; null when not shown.", "type": [ "string", "null" ] }, "location_id": { "description": "Marketplace's ID of the city the item is in: a Marketplace search takes it as its location; null when not shown.", "type": [ "string", "null" ] }, "longitude": { "description": "WGS 84 longitude of the listing's area in degrees (always listed in approximate_fields); set together with latitude.", "format": "double", "type": [ "number", "null" ] }, "postal_code": { "description": "Postal code of the listing's area, as Marketplace shows it (homes and rentals); null when not shown.", "type": [ "string", "null" ] }, "price_period": { "description": "The period price pays for: month for a property rental's monthly rent (Marketplace shows $914 / Month); null for a sale price. New values may be added.", "enum": [ "month", null ], "type": [ "string", "null" ] }, "published_at": { "description": "When it was listed, RFC 3339 UTC; null when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "seller_joined_at": { "description": "When the seller joined Facebook, RFC 3339 UTC; null when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "seller_rating": { "description": "The seller's average Marketplace rating as a seller, 1 to 5 stars; null when the seller's ratings are private or there are none.", "format": "double", "type": [ "number", "null" ] }, "seller_rating_count": { "description": "Ratings behind seller_rating; null when the seller's ratings are private.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "location", "location_id", "published_at", "is_local_pickup", "latitude", "longitude", "delivery_types", "is_buy_now_enabled", "seller_rating", "seller_rating_count", "price_period", "postal_code", "seller_joined_at" ], "type": "object" }, "FacebookProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookProfileSpecific": { "properties": { "ad_library_entity_type": { "description": "Meta's own label for the advertiser in its Ad Library, as written there (PERSON_PROFILE, REGULAR_PAGE, IG_ADS_IDENTITY for an advertiser that exists only on Instagram). It labels brands PERSON_PROFILE too: it says how Meta files the advertiser, not what it is. New values may appear. Null for a profile read from elsewhere.", "type": [ "string", "null" ] }, "admin_countries": { "description": "Where the people who manage the Page are, as Page transparency counts them. [] when it shows none.", "items": { "$ref": "#/components/schemas/FacebookAdminCountry" }, "type": "array" }, "alternate_name": { "description": "The other name the account shows beside its name.", "type": [ "string", "null" ] }, "business_hours": { "description": "A business's weekly opening hours, a day at a time. [] when it shows none.", "items": { "$ref": "#/components/schemas/FacebookBusinessDay" }, "type": "array" }, "education": { "description": "The schools a person's intro lists, as written there. [] when it lists none.", "items": { "type": "string" }, "type": "array" }, "email": { "description": "The public contact email the profile shows.", "type": [ "string", "null" ] }, "gender": { "description": "A person's gender as Facebook states it, male or female; null for a Page or when it states none.", "type": [ "string", "null" ] }, "hometown": { "description": "The hometown a person's intro states.", "type": [ "string", "null" ] }, "hours_status": { "description": "Whether the business is open at fetch time, in Facebook's words (Open now, Closed now, Closing soon).", "type": [ "string", "null" ] }, "instagram_follower_count": { "description": "That Instagram account's exact followers, as the Ad Library's advertiser search shows them.", "format": "int64", "type": [ "integer", "null" ] }, "instagram_username": { "description": "The Instagram account Meta links to the advertiser, as its Ad Library's advertiser search shows it; null when it links none or for a profile read from elsewhere.", "type": [ "string", "null" ] }, "is_deleted": { "description": "True when the Page has been deleted, as the Ad Library's advertiser search states it: its ads stay in the library. Null for a profile read from elsewhere.", "type": [ "boolean", "null" ] }, "is_instagram_verified": { "description": "Whether that Instagram account has the verified badge, as the Ad Library's advertiser search shows it.", "type": [ "boolean", "null" ] }, "is_memorialized": { "description": "True for a memorialized account (\"Remembering …\").", "type": [ "boolean", "null" ] }, "is_political_advertiser": { "description": "True when the account has run ads about social issues, elections or politics.", "type": [ "boolean", "null" ] }, "is_running_ads": { "description": "True when the account is running ads now (Page transparency).", "type": [ "boolean", "null" ] }, "name_changes": { "description": "The Page's earlier name changes, newest first. [] when it has none.", "items": { "$ref": "#/components/schemas/FacebookNameChange" }, "type": "array" }, "owner_location": { "description": "The confirmed owner's location, as Page transparency states it.", "type": [ "string", "null" ] }, "owner_name": { "description": "The organization or person Facebook confirms is responsible for the Page.", "type": [ "string", "null" ] }, "page_id": { "description": "The Page ID Facebook shows under Page transparency, which is also the advertiser's ID in Meta's Ad Library; null for an account without one (most people's profiles).", "type": [ "string", "null" ] }, "phone": { "description": "The public contact phone number the profile shows, as written there.", "type": [ "string", "null" ] }, "price_range": { "description": "A business's price range as shown, such as $$.", "type": [ "string", "null" ] }, "rating": { "description": "The rating line as shown, such as 96% recommend (1,121 reviews).", "type": [ "string", "null" ] }, "recommend_percent": { "description": "The share of reviewers who recommend the Page, as a percentage; null when it is not yet rated.", "format": "int64", "type": [ "integer", "null" ] }, "relationship": { "description": "The relationship a person's intro states, as written there.", "type": [ "string", "null" ] }, "review_count": { "description": "How many reviews the Page has.", "format": "int64", "type": [ "integer", "null" ] }, "services": { "description": "What the business offers, as Facebook lists it (Delivery, Takeout, Dine-in). [] when it lists none.", "items": { "type": "string" }, "type": "array" }, "talking_about_count": { "description": "How many people Facebook counts as talking about the account. It is shown only on the profile's own page, which most requests are answered without: null when this answer did not read it.", "format": "int64", "type": [ "integer", "null" ] }, "were_here_count": { "description": "How many people have checked in at a place's Page. It is shown only on the profile's own page, which most requests are answered without: null when this answer did not read it, or for an account that is not a place.", "format": "int64", "type": [ "integer", "null" ] }, "work": { "description": "The jobs a person's intro lists, as written there (Founder and CEO at Meta). [] when it lists none.", "items": { "type": "string" }, "type": "array" } }, "required": [ "page_id", "gender", "alternate_name", "is_memorialized", "talking_about_count", "were_here_count", "email", "phone", "price_range", "rating", "recommend_percent", "review_count", "services", "hours_status", "business_hours", "work", "education", "hometown", "relationship", "owner_name", "owner_location", "is_running_ads", "is_political_advertiser", "admin_countries", "name_changes", "instagram_username", "instagram_follower_count", "is_instagram_verified", "is_deleted", "ad_library_entity_type" ], "type": "object" }, "FacebookReaction": { "properties": { "count": { "description": "How many people reacted with it.", "format": "int64", "type": [ "integer", "null" ] }, "type": { "description": "Reaction type. New values may be added.", "enum": [ "like", "love", "care", "haha", "wow", "sad", "angry" ], "type": "string" } }, "required": [ "type", "count" ], "type": "object" }, "FacebookReelsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookRepliesResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), oldest first.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_adsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), most impressions first.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_advertisersResponse": { "properties": { "data": { "description": "Up to limit items (page size 15), the search box's own order.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_eventsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), Facebook's ranking of the results, not by date. In Facebook's words: `metrics.attendee_count` is going.", "items": { "$ref": "#/components/schemas/ScheduledEvent" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_groupsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_listingsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), the closest to the place first with sort=nearest, the latest listed first, by the day: later pages can hold newer listings with sort=newest, the lowest price first with sort=price_asc, the highest price first with sort=price_desc, Marketplace's Suggested order with sort=relevance.", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_placesResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), most relevant first, as Marketplace's location picker ranks them.", "items": { "$ref": "#/components/schemas/Place" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "FacebookSharedPost": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "id": { "description": "Its post ID.", "type": [ "string", "null" ] }, "url": { "description": "Its URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "author" ], "type": "object" }, "FacebookTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "FacebookWebResultSpecific": { "properties": { "account_type": { "description": "What the index's text says the account is: page (Facebook describes it with counts, as it does a Page, and a person in professional mode) or person (Facebook's \"is on Facebook\" text). Null when the text doesn't say. New values may be added.", "enum": [ "page", "person", null ], "type": [ "string", "null" ] }, "like_count": { "description": "The Page's likes as the index's snippet states them; null when it does not, as for most Pages, which show followers instead.", "format": "int64", "type": [ "integer", "null" ] }, "place": { "description": "Where the account is, as the index's snippet names it after its name (a city, usually); null when it does not.", "type": [ "string", "null" ] }, "talking_about_count": { "description": "How many people Facebook counted as talking about the account, as the index's snippet states it; null when it does not.", "format": "int64", "type": [ "integer", "null" ] }, "were_here_count": { "description": "How many people have checked in at the account's place, as the index's snippet states it; null when it does not.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "account_type", "like_count", "talking_about_count", "were_here_count", "place" ], "type": "object" }, "GoogleAdLocation": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 code of its country; null when not resolved.", "type": [ "string", "null" ] }, "criterion_id": { "description": "Google Ads geo target criterion ID (2840 is the United States).", "type": "string" }, "full_name": { "description": "The name with the regions it lies in (California, United States); null when not resolved.", "type": [ "string", "null" ] }, "name": { "description": "The location's name (California); null when Google did not resolve it.", "type": [ "string", "null" ] } }, "required": [ "criterion_id", "name", "full_name", "country_code" ], "type": "object" }, "GoogleAdRegion": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string" }, "first_shown_at": { "description": "First day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "impressions": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Times shown there, Google's range; null when not disclosed." }, "last_shown_at": { "description": "Last day shown there, RFC 3339 UTC (date-only: approximate_fields); null when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "services": { "description": "Times shown there on each Google service; [] when not disclosed.", "items": { "$ref": "#/components/schemas/GoogleAdServiceImpressions" }, "type": "array" } }, "required": [ "country_code", "first_shown_at", "last_shown_at", "impressions", "services" ], "type": "object" }, "GoogleAdResponse": { "properties": { "data": { "$ref": "#/components/schemas/Ad" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "GoogleAdServiceImpressions": { "properties": { "impressions": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Times shown on it, Google's range (a lower bound of 0 when Google shows only \"under\" an upper bound)." }, "service": { "description": "The Google service. New values may be added; treat unknown values as other.", "enum": [ "google_search", "google_maps", "google_play", "google_shopping", "youtube", "other" ], "type": "string" } }, "required": [ "service", "impressions" ], "type": "object" }, "GoogleAdSpecific": { "properties": { "days_shown": { "description": "Days the ad was shown (the center's \"Ran for\"); null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "is_synthetic": { "description": "The advertiser disclosed synthetic (digitally altered or generated) content, as the ad's page labels it; false when it shows no such label.", "type": [ "boolean", "null" ] }, "product_category": { "description": "The product category Google files a Shopping ad under (Apparel & Accessories); null otherwise.", "type": [ "string", "null" ] }, "regions": { "description": "Per country it was shown in: when, how often and on which Google services; [] when not shown (in unknown_fields).", "items": { "$ref": "#/components/schemas/GoogleAdRegion" }, "type": "array" }, "targeting": { "anyOf": [ { "$ref": "#/components/schemas/GoogleAdTargeting" }, { "type": "null" } ], "description": "Whom the advertiser selected; null when not disclosed." }, "topic": { "description": "The ad's topic as Google labels it (Sports & Fitness); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "days_shown", "topic", "product_category", "is_synthetic", "regions", "targeting" ], "type": "object" }, "GoogleAdTargeting": { "properties": { "age_ranges": { "description": "Age ranges included (18-24, 25-34, 35-44, 45-54, 55-64, 65+, unknown); [] when none.", "items": { "type": "string" }, "type": "array" }, "criteria": { "description": "The kinds of criteria the advertiser included or excluded (the EU disclosure); [] when not disclosed.", "items": { "$ref": "#/components/schemas/GoogleAdTargetingCriterion" }, "type": "array" }, "excluded_age_ranges": { "description": "Age ranges excluded; [] when none.", "items": { "type": "string" }, "type": "array" }, "excluded_genders": { "description": "Genders excluded; [] when none.", "items": { "type": "string" }, "type": "array" }, "excluded_locations": { "description": "Locations excluded; [] when none.", "items": { "$ref": "#/components/schemas/GoogleAdLocation" }, "type": "array" }, "genders": { "description": "Genders included (male, female, unknown); [] when none.", "items": { "type": "string" }, "type": "array" }, "locations": { "description": "Locations included; [] when none.", "items": { "$ref": "#/components/schemas/GoogleAdLocation" }, "type": "array" } }, "required": [ "age_ranges", "excluded_age_ranges", "genders", "excluded_genders", "locations", "excluded_locations", "criteria" ], "type": "object" }, "GoogleAdTargetingCriterion": { "properties": { "category": { "description": "The kind of criteria. New values may be added; treat unknown values as other.", "enum": [ "demographics", "locations", "contextual", "topics_of_interest", "customer_lists" ], "type": "string" }, "is_excluded": { "description": "Criteria of this kind were excluded from the audience.", "type": "boolean" }, "is_included": { "description": "Criteria of this kind were included in the audience.", "type": "boolean" } }, "required": [ "category", "is_included", "is_excluded" ], "type": "object" }, "GoogleAdsResponse": { "properties": { "data": { "description": "Up to limit items (page size 40), last shown, most recent first with sort=newest, last shown, least recent first (topic=political) with sort=oldest, most impressions first (topic=political) with sort=popular, most spent first (topic=political) with sort=spend.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "GoogleAdvertiserResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Google's words: `metrics.post_count` is ads." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "GoogleElectionAdvertiser": { "properties": { "ad_count": { "description": "Election ads the center shows for the advertiser, exact.", "format": "int64", "type": [ "integer", "null" ] }, "country_codes": { "description": "ISO 3166-1 alpha-2 codes of the countries and territories it is verified to run election ads in; [] when not shown.", "items": { "type": "string" }, "type": "array" }, "regulatory_ids": { "description": "The advertiser's registrations with election regulators (a US FEC committee ID, or an individual's own registration); [] when it disclosed none.", "items": { "$ref": "#/components/schemas/GoogleRegulatoryID" }, "type": "array" } }, "required": [ "ad_count", "country_codes", "regulatory_ids" ], "type": "object" }, "GoogleProfileSpecific": { "properties": { "ads": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "The ads the center shows for the advertiser, as Google's range (equal bounds when exact), in the region the request names where it takes one; metrics.post_count is its lower bound. Null when not shown." }, "election": { "anyOf": [ { "$ref": "#/components/schemas/GoogleElectionAdvertiser" }, { "type": "null" } ], "description": "The advertiser's election-ads disclosure; null when it is not an election advertiser or the center does not show it." }, "is_election_advertiser": { "description": "True when Google verified the advertiser to run election ads (it has a page in the center's political ads view).", "type": [ "boolean", "null" ] }, "last_shown_at": { "description": "The last time one of the advertiser's ads was shown, RFC 3339 UTC (among the ads counted in ads); null when it has none or the center does not show it.", "format": "date-time", "type": [ "string", "null" ] }, "legal_name": { "description": "The advertiser's legal name, as Google verified it; null when the center shows none.", "type": [ "string", "null" ] } }, "required": [ "ads", "legal_name", "last_shown_at", "is_election_advertiser", "election" ], "type": "object" }, "GoogleRegulatoryID": { "properties": { "id": { "description": "The identifier, as registered (C00003418).", "type": "string" }, "type": { "description": "The kind of identifier. New values may be added; treat unknown values as other.", "enum": [ "us_fec_id", "us_employer_identification_number", "us_state_id", "us_individual", "other" ], "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "GoogleSearch_adsResponse": { "properties": { "data": { "description": "Up to limit items (page size 40), last shown, most recent first with sort=newest, last shown, least recent first (topic=political) with sort=oldest, most impressions first (topic=political) with sort=popular, most spent first (topic=political) with sort=spend.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "GoogleSearch_advertisersResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), most ads first, by the center's ad counts (the upper bound, then the lower), Google's order among equals with sort=popular, Google's order, as the center's search box lists the matches with sort=relevance. In Google's words: `metrics.post_count` is ads.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "GoogleSearch_suggestionsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), the center's search box order: on each page its advertisers, then its websites.", "items": { "$ref": "#/components/schemas/Suggestion" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "GoogleSuggestionSpecific": { "properties": { "ads": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "The ads the center shows for an advertiser suggestion's advertiser, as Google's range (equal bounds when exact), in the region the request names where it takes one; null for a website suggestion, or when not shown." }, "country_code": { "description": "The country an advertiser suggestion's advertiser is based in, an ISO 3166-1 alpha-2 code; null for a website suggestion, or when not shown.", "type": [ "string", "null" ] } }, "required": [ "country_code", "ads" ], "type": "object" }, "GoogleTrendMetrics": { "properties": { "search_count": { "description": "Searches for the term in the board's window, as the lower bound of Google's volume bucket (500 for \"500+\"), always approximate.", "format": "int64", "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "search_count" ], "type": "object" }, "GoogleTrendSpecific": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country whose searches the trend counts; null for a worldwide board.", "type": [ "string", "null" ] }, "ended_at": { "description": "When it stopped trending, RFC 3339 UTC; null while it is active (is_active) or when unknown.", "format": "date-time", "type": [ "string", "null" ] }, "growth": { "description": "How much the term's searches rose since it started trending, a fraction (1 = +100 %), in Google's steps; Google caps it at 10 (+1,000 %), a lower bound then (listed in approximate_fields).", "format": "double", "minimum": 0, "type": [ "number", "null" ] }, "history": { "description": "How much the term was searched over time, oldest first, each interval relative to the series' peak (1); [] on a board, which does not read the series (listed in unknown_fields): a trend's own endpoint fills it.", "items": { "$ref": "#/components/schemas/TrendPoint" }, "type": "array" }, "is_active": { "description": "Still trending: Google shows it as active (ended_at is null).", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/GoogleTrendMetrics", "description": "Google's counts for the trend; null = not shown." }, "related_searches": { "description": "Other searches Google groups under the trend, in its order (the term itself left out); each a term of its own. [] when none.", "items": { "type": "string" }, "type": "array" }, "started_at": { "description": "When the term started trending, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "country_code", "growth", "started_at", "ended_at", "is_active", "related_searches", "metrics", "history" ], "type": "object" }, "Hashtag": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (\"36M videos\": metrics.post_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "The hashtag's description as its page shows it; null when it has none.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native hashtag ID (TikTok's challenge ID, Threads' tag ID); on platforms whose public pages key a hashtag by its name (Instagram, YouTube, Facebook, X), the name lowercased.", "type": "string" }, "metrics": { "$ref": "#/components/schemas/HashtagMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "name": { "description": "The tag without #, as the platform shows it (case kept). Threads tags may contain spaces (\"book club\").", "type": "string" }, "platform": { "description": "Platform ID (tiktok, instagram, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/HashtagPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "thumbnail_url": { "description": "The hashtag's own picture (not one of its posts' images); null when it has none. Platform CDN URLs can expire.", "format": "uri", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical hashtag page URL (for a multi-word Threads tag, its tag search page).", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "name", "url", "description", "thumbnail_url", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "HashtagMetrics": { "properties": { "post_count": { "description": "Posts carrying the tag, as the platform counts them; rounded on YouTube and Threads (see approximate_fields).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "post_count" ], "type": "object" }, "HashtagPlatformSpecific": { "properties": { "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramHashtagSpecific" }, { "type": "null" } ], "description": "An Instagram hashtag's own fields." }, "threads": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsHashtagSpecific" }, { "type": "null" } ], "description": "A Threads tag's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokHashtagSpecific" }, { "type": "null" } ], "description": "A TikTok hashtag's own fields." }, "youtube": { "anyOf": [ { "$ref": "#/components/schemas/YouTubeHashtagSpecific" }, { "type": "null" } ], "description": "A YouTube hashtag's own fields." } }, "type": "object" }, "HashtagRef": { "properties": { "id": { "description": "The hashtag's ID as the platform's hashtag endpoints key it: its native ID, or the name lowercased where the platform's pages key a hashtag by name (Instagram).", "type": "string" }, "metrics": { "$ref": "#/components/schemas/HashtagMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "name": { "description": "The tag without #, as the platform shows it (case kept).", "type": "string" }, "url": { "description": "Canonical hashtag page URL.", "format": "uri", "type": "string" } }, "required": [ "id", "name", "url", "metrics" ], "type": "object" }, "HashtagSummary": { "properties": { "description": { "description": "The hashtag's description as the index's snippet quotes it; null when it quotes none (a platform's generic page text is not one).", "type": [ "string", "null" ] }, "id": { "description": "The hashtag's ID as the platform's hashtag endpoints key it; null until the result is filled.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/HashtagMetrics", "description": "Counts as the index's text states them (\"36.2M posts\"; rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "name": { "description": "The tag without #, as the matched link or the index's title spells it (case kept where the title shows it).", "type": "string" }, "thumbnail_url": { "description": "The hashtag's own picture; null until the result is filled.", "format": "uri", "type": [ "string", "null" ] }, "url": { "description": "Canonical hashtag page URL (equals the result's url).", "format": "uri", "type": "string" } }, "required": [ "id", "name", "url", "description", "thumbnail_url", "metrics" ], "type": "object" }, "InputRef": { "properties": { "id": { "description": "Platform-native ID of the item; null when it is only known after the fetch and the request failed.", "type": [ "string", "null" ] }, "kind": { "description": "What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.", "type": "string" }, "url": { "description": "Canonical URL of the item; null when unknown.", "type": [ "string", "null" ] } }, "required": [ "kind", "id", "url" ], "type": "object" }, "InstagramCommentResponse": { "properties": { "data": { "$ref": "#/components/schemas/Comment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramCommentSpecific": { "properties": { "gif_url": { "description": "The GIF the comment is (Instagram's GIPHY picker; text is then usually empty), on Meta's CDN; the URL is signed and expires within days. null when the comment has no GIF or the source does not show it (the post page's first comments).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "gif_url" ], "type": "object" }, "InstagramCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 24), newest first.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramEmbedResponse": { "properties": { "data": { "$ref": "#/components/schemas/Embed" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramHashtagResponse": { "properties": { "data": { "$ref": "#/components/schemas/Hashtag" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramHashtagSpecific": { "properties": { "is_restricted": { "description": "Instagram restricts the tag: its posts are hidden (a tag it reports as sensitive), though it exists.", "type": [ "boolean", "null" ] }, "is_trending": { "description": "Instagram marks the tag trending; null where it does not say (search results).", "type": [ "boolean", "null" ] }, "tag_id": { "description": "Instagram's own numeric ID of the hashtag; null where the source does not show it (a tag Instagram withholds).", "type": [ "string", "null" ] } }, "required": [ "is_restricted", "is_trending", "tag_id" ], "type": "object" }, "InstagramHashtag_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 24), Instagram's ranking of the hashtag's reels (its public results page's order).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramHighlightsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), the order of the account's highlights tray on its profile.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramLink": { "properties": { "url": { "description": "The linked page, as the author shared it (Instagram's l.instagram.com redirect removed).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url" ], "type": "object" }, "InstagramPlaceResponse": { "properties": { "data": { "$ref": "#/components/schemas/Place" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramPlaceSpecific": { "properties": { "facebook_place_id": { "description": "ID of the Facebook place (Page) behind the location: the id of the same place on facebook. Null when none is linked or the source does not show it.", "type": [ "string", "null" ] } }, "required": [ "facebook_place_id" ], "type": "object" }, "InstagramPlace_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 18), newest first with sort=newest, Instagram's Top posts for the location (its ranking) with sort=popular.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramPlaylist_storiesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), oldest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramPostLocation": { "properties": { "id": { "description": "Instagram location ID (equals the place's id: the number in instagram.com/explore/locations//).", "type": "string" }, "latitude": { "description": "WGS 84 latitude in degrees (set together with longitude).", "format": "double", "type": [ "number", "null" ] }, "longitude": { "description": "WGS 84 longitude in degrees (set together with latitude).", "format": "double", "type": [ "number", "null" ] }, "name": { "description": "Place name as Instagram shows it.", "type": [ "string", "null" ] }, "url": { "description": "The place's page on Instagram.", "format": "uri", "type": "string" } }, "required": [ "id", "name", "url", "latitude", "longitude" ], "type": "object" }, "InstagramPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramPostSpecific": { "properties": { "is_ai_generated": { "description": "Instagram shows its AI label (made or edited with AI); false when it shows none.", "type": [ "boolean", "null" ] }, "link": { "anyOf": [ { "$ref": "#/components/schemas/InstagramLink" }, { "type": "null" } ], "description": "The link a story's link sticker (or swipe-up link) opens; null when none, and on every post that is not a story." }, "location": { "anyOf": [ { "$ref": "#/components/schemas/InstagramPostLocation" }, { "type": "null" } ], "description": "The tagged place; null when none or not shown by the endpoint's source." } }, "required": [ "is_ai_generated", "location", "link" ], "type": "object" }, "InstagramPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 12), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramProfileSpecific": { "properties": { "account_type": { "description": "The kind of account Instagram says it is: personal, or one of its professional kinds, business or creator (an account picks one; it says nothing of whether a person or an organization runs it). Null when the source does not show it. New values may be added; treat unknown values as unknown.", "enum": [ "personal", "business", "creator", null ], "type": [ "string", "null" ] }, "fbid": { "description": "The account's Meta-wide ID (17841…), the one Meta's Instagram Graph API uses; id is Instagram's own user ID. Null when the source does not show it.", "type": [ "string", "null" ] }, "is_highlights_shown": { "description": "True when the profile shows story highlights, false when it shows none; null when unknown (private accounts, or a source that does not show them).", "type": [ "boolean", "null" ] }, "is_memorialized": { "description": "True when Instagram has memorialized the account (its owner has died), false otherwise; null when unknown.", "type": [ "boolean", "null" ] }, "is_story_live": { "description": "True when the account has a story up now (stories last 24 hours), false when it has none; null when unknown (Instagram does not say for private accounts).", "type": [ "boolean", "null" ] }, "pronouns": { "description": "The pronouns the owner chose to show on the profile, as shown; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" } }, "required": [ "fbid", "is_memorialized", "is_story_live", "is_highlights_shown", "account_type", "pronouns" ], "type": "object" }, "InstagramReelsResponse": { "properties": { "data": { "description": "Up to limit items (page size 12), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_hashtagsResponse": { "properties": { "data": { "description": "Up to limit items (page size 55), Instagram's search ranking (most relevant first).", "items": { "$ref": "#/components/schemas/Hashtag" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_placesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 24), Instagram's ranking for the keyword (its popular page's order).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_soundsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSearch_suggestionsResponse": { "properties": { "data": { "description": "Up to limit items (page size 56), the exact account first, then Instagram's tag search ranking.", "items": { "$ref": "#/components/schemas/Suggestion" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSimilar_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Instagram's suggestion order.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramSoundResponse": { "properties": { "data": { "$ref": "#/components/schemas/Sound" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramSoundSourcePost": { "properties": { "id": { "description": "The reel's shortcode: its post ID (equals post.id of instagram.post).", "type": [ "string", "null" ] }, "url": { "description": "The reel's link (instagram.com/reel//).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url" ], "type": "object" }, "InstagramSoundSpecific": { "properties": { "asset_id": { "description": "ID of a licensed track's audio asset (not the sound's page ID); null for original audio.", "type": [ "string", "null" ] }, "created_at": { "description": "When the creator's original audio was created (RFC 3339 UTC): when the reel it comes from was published; null for a licensed track.", "format": "date-time", "type": [ "string", "null" ] }, "is_explicit": { "description": "Instagram marks the track explicit.", "type": [ "boolean", "null" ] }, "is_lyrics_shown": { "description": "Instagram has the licensed track's lyrics and shows them with it; null for original audio.", "type": [ "boolean", "null" ] }, "is_trending": { "description": "Instagram labels the audio trending in reels.", "type": [ "boolean", "null" ] }, "source_post": { "anyOf": [ { "$ref": "#/components/schemas/InstagramSoundSourcePost" }, { "type": "null" } ], "description": "The reel an original audio comes from (the first published with it); null for a licensed track." } }, "required": [ "asset_id", "is_explicit", "is_trending", "is_lyrics_shown", "created_at", "source_post" ], "type": "object" }, "InstagramSound_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 12), Instagram's ranking of the audio's reels (the order its audio page shows).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramStoryResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramSuggestionSpecific": { "properties": { "tag_id": { "description": "Instagram's own numeric ID of a hashtag suggestion's tag; null for every other type.", "type": [ "string", "null" ] } }, "required": [ "tag_id" ], "type": "object" }, "InstagramTopicResponse": { "properties": { "data": { "$ref": "#/components/schemas/Topic" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramTopicSpecific": { "properties": { "is_category": { "description": "Instagram shows the topic as a category (a broad topic made of narrower ones, without a post count of its own); null when the source cannot tell.", "type": [ "boolean", "null" ] }, "post_count": { "description": "Reels Instagram counts under the topic, cut to the digits it shows (46M for 46,656,326; in approximate_fields); null when the page shows none.", "format": "int64", "type": [ "integer", "null" ] }, "source_urls": { "description": "Web pages the description draws on, in the order its superscript markers number them (¹ is the first); [] when it cites none.", "items": { "type": "string" }, "type": "array" } }, "required": [ "is_category", "source_urls", "post_count" ], "type": "object" }, "InstagramTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "InstagramTrending_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 40), Instagram's reels feed order (a fresh selection on each first page).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "InstagramUsernameResponse": { "properties": { "data": { "$ref": "#/components/schemas/Username" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KickCategory": { "properties": { "banner_url": { "description": "The category's banner image.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "Kick's category ID.", "type": [ "string", "null" ] }, "name": { "description": "Its name (Just Chatting).", "type": [ "string", "null" ] }, "parent_slug": { "description": "The parent category it is filed under (irl, games).", "type": [ "string", "null" ] }, "slug": { "description": "Its name in links (kick.com/category/just-chatting).", "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "parent_slug", "banner_url" ], "type": "object" }, "KickPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KickPostSpecific": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/KickCategory" }, { "type": "null" } ], "description": "What the channel was streaming when the clip was made." }, "clipped_by": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account that made the clip, which may be a bot taking chat commands; author is the channel it was clipped from. Its id is null: see clipped_by_user_id." }, "clipped_by_user_id": { "description": "Kick's user number of clipped_by, which is not its channel's ID.", "type": [ "string", "null" ] }, "livestream_id": { "description": "Kick's ID of the broadcast the clip was cut from.", "type": [ "string", "null" ] }, "started_at": { "description": "The moment of the broadcast the clip starts at, RFC 3339 UTC; published_at is when it was made.", "format": "date-time", "type": [ "string", "null" ] }, "vod": { "anyOf": [ { "$ref": "#/components/schemas/KickVOD" }, { "type": "null" } ], "description": "The saved broadcast the clip comes from; null when Kick keeps none (the broadcast's video was deleted or never saved) or the answer came from a source that can't link to it." } }, "required": [ "started_at", "livestream_id", "category", "vod", "clipped_by", "clipped_by_user_id" ], "type": "object" }, "KickTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KickVOD": { "properties": { "id": { "description": "The video's ID, as in its link.", "type": [ "string", "null" ] }, "offset_ms": { "description": "Where in the video the clip starts, in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The video's title.", "type": [ "string", "null" ] }, "url": { "description": "The video's page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "offset_ms" ], "type": "object" }, "KomiItemLink": { "properties": { "type": { "description": "Komi's name for the service, lowercase: spotify, apple_music, youtube_music, deezer, apple_podcast, … New values may be added.", "type": "string" }, "url": { "description": "The release or the episode on that service.", "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "KomiPageItem": { "properties": { "coupon_code": { "description": "The discount code a link's own page on Komi shows anyone who follows it; null when it has none.", "type": [ "string", "null" ] }, "currency": { "description": "ISO 4217 currency of price; null when the item has no price or Komi does not say.", "type": [ "string", "null" ] }, "description": { "description": "The text of a text module, a gallery image's caption, or a product's description.", "type": [ "string", "null" ] }, "group": { "description": "The name of the group the item sits in on the page; null when it is in none.", "type": [ "string", "null" ] }, "id": { "description": "Komi's ID of the item; null for items Komi reads from another service (a shop's or Bandsintown's).", "type": [ "string", "null" ] }, "is_sold_out": { "description": "Whether an event is sold out; null for anything but an event.", "type": [ "boolean", "null" ] }, "links": { "description": "For music and podcasts, the same release on each service, in the page's order; [] for everything else.", "items": { "$ref": "#/components/schemas/KomiItemLink" }, "type": "array" }, "location": { "description": "An event's place as the page shows it; null otherwise.", "type": [ "string", "null" ] }, "price": { "description": "A product's price as the page shows it, in major units of currency; 0 is a free digital download; null when the item has no price or the page shows none.", "format": "double", "type": [ "number", "null" ] }, "section": { "description": "The title the page shows above the item's module; null when it shows none.", "type": [ "string", "null" ] }, "starts_at": { "description": "When an event starts, RFC 3339 UTC; null otherwise. A Bandsintown or Seated time has no zone and is read as UTC (listed in approximate_fields).", "format": "date-time", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "The item's image; null when it has none.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The item's label: a link's text, a product's name, a video's or a release's title.", "type": [ "string", "null" ] }, "type": { "description": "Komi's name for the kind of module, lowercase: link, product, digital_product, youtube_video, youtube_short, tiktok_video, instagram_reel, music, podcast, events, bandsintown, seated, text, media_gallery, shop_my_shelf, mail_link, data_capture_signup, form_data, … New values may be added: treat an unknown one as a generic item.", "type": "string" }, "url": { "description": "Where the item leads: the link's target (a mailto: link for a mail_link), the product's page, the video, the release's or the digital product's page on Komi, an event's tickets. Null for a form or a text.", "format": "uri", "type": [ "string", "null" ] }, "venue": { "description": "An event's venue; null otherwise.", "type": [ "string", "null" ] } }, "required": [ "id", "type", "group", "section", "title", "url", "thumbnail_url", "description", "price", "currency", "coupon_code", "links", "starts_at", "venue", "location", "is_sold_out" ], "type": "object" }, "KomiPageResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KomiProfileSpecific": { "properties": { "display_name_image_url": { "description": "The artwork the page shows as its name, when it has one; null otherwise.", "format": "uri", "type": [ "string", "null" ] }, "first_name": { "description": "The owner's first name as entered on Komi; null when empty.", "type": [ "string", "null" ] }, "items": { "description": "What the page shows, flattened in the page's order: links, products, videos, music, podcasts, events, text and galleries. Modules the owner has hidden are not returned; [] when the page shows nothing (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/KomiPageItem" }, "type": "array" }, "last_name": { "description": "The owner's last name as entered on Komi; null when empty.", "type": [ "string", "null" ] }, "social_links": { "description": "The page's row of social and music profiles and contact links, in the page's order; [] when it has none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/KomiSocialLink" }, "type": "array" } }, "required": [ "first_name", "last_name", "display_name_image_url", "social_links", "items" ], "type": "object" }, "KomiSocialLink": { "properties": { "type": { "description": "Komi's name for the service, lowercase: instagram, tiktok, youtube, twitter, facebook, snapchat, spotify, apple_music, website, email, whatsapp, … New values may be added.", "type": "string" }, "url": { "description": "The link, as the owner entered it (https:// added when it had no scheme); an email address as a mailto: link.", "format": "uri", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "KwaiDuetSource": { "properties": { "display_name": { "description": "The source author's display name, as the duet shows it.", "type": [ "string", "null" ] }, "post_id": { "description": "The source post's ID; null when the source does not state it exactly.", "type": [ "string", "null" ] }, "user_id": { "description": "The source author's numeric user ID, accepted as a handle.", "type": [ "string", "null" ] } }, "required": [ "post_id", "user_id", "display_name" ], "type": "object" }, "KwaiMusic": { "properties": { "author_name": { "description": "Who Kwai credits for the sound.", "type": [ "string", "null" ] }, "cover_url": { "description": "Sound cover image URL.", "format": "uri", "type": [ "string", "null" ] }, "duration_ms": { "description": "Sound length in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Sound ID.", "type": [ "string", "null" ] }, "is_original": { "description": "An original sound a creator uploaded (false: a catalogue track).", "type": [ "boolean", "null" ] }, "play_url": { "description": "Audio file URL.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Sound title; null on most original sounds, which Kwai leaves untitled.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "author_name", "is_original", "duration_ms", "cover_url", "play_url" ], "type": "object" }, "KwaiPlace": { "properties": { "address": { "description": "Address line.", "type": [ "string", "null" ] }, "id": { "description": "Place ID.", "type": [ "string", "null" ] }, "latitude": { "description": "Latitude in degrees.", "format": "double", "type": [ "number", "null" ] }, "longitude": { "description": "Longitude in degrees.", "format": "double", "type": [ "number", "null" ] }, "name": { "description": "Place name.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "address", "latitude", "longitude" ], "type": "object" }, "KwaiPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KwaiPostSpecific": { "properties": { "author_user_id": { "description": "The author's numeric user ID, also accepted as a handle; null when the source does not state it (author.id, the account's encrypted ID, is always the same account).", "type": [ "string", "null" ] }, "author_verified_description": { "description": "What the author's verification badge says (Conta Oficial); null when the account has none.", "type": [ "string", "null" ] }, "category": { "description": "The topic Kwai files the post under (Dance, Comedy&Funny), in English; null when it files it under none.", "type": [ "string", "null" ] }, "duet_source": { "anyOf": [ { "$ref": "#/components/schemas/KwaiDuetSource" }, { "type": "null" } ], "description": "The post this one duets; null when it is no duet." }, "is_ai_generated": { "description": "Kwai labels the post as AI-generated; null when the source does not state it.", "type": [ "boolean", "null" ] }, "music": { "anyOf": [ { "$ref": "#/components/schemas/KwaiMusic" }, { "type": "null" } ], "description": "The post's sound; null when Kwai names none." }, "place": { "anyOf": [ { "$ref": "#/components/schemas/KwaiPlace" }, { "type": "null" } ], "description": "The place tagged on the post; null when none." }, "subcategory": { "description": "The narrower topic within category (Fashion dance); null when none.", "type": [ "string", "null" ] }, "tagged_accounts": { "description": "The accounts the caption tags, in order; [] when none. mentions holds the names written in the caption by hand.", "items": { "$ref": "#/components/schemas/KwaiTaggedAccount" }, "type": "array" } }, "required": [ "music", "author_user_id", "author_verified_description", "category", "subcategory", "is_ai_generated", "tagged_accounts", "place", "duet_source" ], "type": "object" }, "KwaiPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "KwaiProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "KwaiProfileSpecific": { "properties": { "gender": { "description": "The gender the account states: M or F. Null when it states none.", "type": [ "string", "null" ] }, "is_banned": { "description": "True when Kwai writes the account as banned, and it gives no reason. Kwai then blanks the account's name, picture, bio and badge, so is_verified is null, and lists no posts whatever metrics.post_count says.", "type": [ "boolean", "null" ] }, "likes_given_count": { "description": "Likes the account has given. Null when it hides them.", "format": "int64", "type": [ "integer", "null" ] }, "playlist_count": { "description": "Playlists the account has. Null when Kwai states none, which is also how it writes an account without any, and on an answer from Kwai's API.", "format": "int64", "type": [ "integer", "null" ] }, "private_post_count": { "description": "Posts the account keeps to itself, as Kwai counts them.", "format": "int64", "type": [ "integer", "null" ] }, "user_id": { "description": "The account's numeric ID, as a string. Accepted as input like id.", "type": [ "string", "null" ] }, "verified_description": { "description": "The label Kwai gives the account's badge, in the account's language (Criador(a) de Comédia, Conta Oficial). Null without a badge.", "type": [ "string", "null" ] }, "verified_type": { "description": "Kwai's number for the kind of badge: 2 on creators and 3 on the official account in the accounts checked. Null without a badge.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "user_id", "gender", "verified_description", "verified_type", "private_post_count", "likes_given_count", "playlist_count", "is_banned" ], "type": "object" }, "KwaiTaggedAccount": { "properties": { "label": { "description": "The name the caption shows for it: its display name or username.", "type": [ "string", "null" ] }, "user_id": { "description": "The account's numeric user ID, accepted as a handle.", "type": [ "string", "null" ] } }, "required": [ "user_id", "label" ], "type": "object" }, "Link": { "properties": { "title": { "description": "Link label shown by the platform.", "type": [ "string", "null" ] }, "url": { "description": "Link target, absolute (https:// is added where the platform stores the link without a scheme).", "format": "uri", "type": "string" } }, "required": [ "url", "title" ], "type": "object" }, "LinkbioProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinkbioProfileSpecific": { "properties": { "custom_domain_url": { "description": "The account's own domain for this page, when it has one (https://7ad.sa for lnk.bio/7adsa). Null when it has none.", "format": "uri", "type": [ "string", "null" ] }, "emails": { "description": "Email addresses the page lists as contact icons, links, contact cards or in its bio; [] if none.", "items": { "type": "string" }, "type": "array" }, "link_count": { "description": "How many links the page's link list holds, icons not included: what was read when that is all of it, else Lnk.Bio's own count, which can include embedded players. Null when neither is known.", "format": "int64", "type": [ "integer", "null" ] }, "linked_username": { "description": "The @name the page shows under its picture, without the @: usually the account's Instagram username, which can differ from the page's own name (username). Null when the page shows none.", "type": [ "string", "null" ] }, "phones": { "description": "Phone numbers the page lists as contact icons, links or contact cards, as written; [] if none.", "items": { "type": "string" }, "type": "array" }, "social_links": { "description": "The page's row of social and contact icons, in order; [] if none.", "items": { "$ref": "#/components/schemas/LinkbioSocialLink" }, "type": "array" } }, "required": [ "linked_username", "emails", "phones", "social_links", "link_count", "custom_domain_url" ], "type": "object" }, "LinkbioSocialLink": { "properties": { "platform": { "description": "The icon's name as Lnk.Bio labels it (Instagram, TikTok, Website, WhatsApp, Spotify, …).", "type": "string" }, "url": { "description": "Where the icon links to.", "format": "uri", "type": "string" } }, "required": [ "platform", "url" ], "type": "object" }, "LinkedInAdCompany": { "properties": { "location": { "description": "Where the company is, as the card writes it; null when not shown.", "type": [ "string", "null" ] }, "size": { "description": "The company's size as the card writes it (10,001+ employees); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "size", "location" ], "type": "object" }, "LinkedInAdCountry": { "properties": { "country": { "description": "The country's name, as the library writes it.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country code; null when the name is none the library's country list has.", "type": [ "string", "null" ] }, "is_under_one_percent": { "description": "The library writes the share as less than one percent.", "type": [ "boolean", "null" ] }, "share_percent": { "description": "Share of the ad's impressions, a whole percent as the library rounds it; null when under one percent.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "country", "country_code", "share_percent", "is_under_one_percent" ], "type": "object" }, "LinkedInAdCriterion": { "properties": { "is_excluded": { "description": "The advertiser excluded by this criterion.", "type": [ "boolean", "null" ] }, "is_targeted": { "description": "The advertiser targeted by this criterion.", "type": [ "boolean", "null" ] } }, "required": [ "is_targeted", "is_excluded" ], "type": "object" }, "LinkedInAdDocument": { "properties": { "page_count": { "description": "How many pages it has; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The document's title; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "title", "page_count" ], "type": "object" }, "LinkedInAdEvent": { "properties": { "ends_at": { "description": "When it ends, RFC 3339 UTC; null when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "location": { "description": "Where it happens, as written (Online); null when not shown.", "type": [ "string", "null" ] }, "organizer": { "description": "Who hosts the event; null when not shown.", "type": [ "string", "null" ] }, "starts_at": { "description": "When it starts, RFC 3339 UTC; null when not shown.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "organizer", "location", "starts_at", "ends_at" ], "type": "object" }, "LinkedInAdJob": { "properties": { "company": { "description": "The company the job is at; null when not shown.", "type": [ "string", "null" ] }, "location": { "description": "The job's location, as written; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "company", "location" ], "type": "object" }, "LinkedInAdMessage": { "properties": { "buttons": { "description": "The message's buttons, in order; [] when none.", "items": { "type": "string" }, "type": "array" }, "sender_avatar_url": { "description": "The sender's picture; null when not shown.", "format": "uri", "type": [ "string", "null" ] }, "sender_name": { "description": "The person the message is sent as; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "sender_name", "sender_avatar_url", "buttons" ], "type": "object" }, "LinkedInAdSegments": { "properties": { "excluded": { "description": "Excluded; [] when none are listed.", "items": { "type": "string" }, "type": "array" }, "included": { "description": "Targeted; [] when none are listed.", "items": { "type": "string" }, "type": "array" } }, "required": [ "included", "excluded" ], "type": "object" }, "LinkedInAdSpecific": { "properties": { "company": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCompany" }, { "type": "null" } ], "description": "The company a company discovery ad presents; null on every other format." }, "creative_type": { "description": "LinkedIn's code for the ad's format (SPONSORED_STATUS_UPDATE, SPONSORED_VIDEO, SPONSORED_INMAILS, JOBS_V2, …), finer than type; null when the library shows none.", "type": [ "string", "null" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdDocument" }, { "type": "null" } ], "description": "The document a document ad shows; null on every other format." }, "event": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdEvent" }, { "type": "null" } ], "description": "The event an event ad promotes; null on every other format." }, "format": { "description": "The ad's format as the library labels it (Single Image Ad, Message Ad, Company Discovery Ad, …); null when not shown.", "type": [ "string", "null" ] }, "impressions_by_country": { "description": "Each country's share of the ad's impressions, as the library lists them; [] when not shown (in unknown_fields).", "items": { "$ref": "#/components/schemas/LinkedInAdCountry" }, "type": "array" }, "is_deleted": { "description": "The library says the ad was deleted; false when it shows no such notice.", "type": [ "boolean", "null" ] }, "job": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdJob" }, { "type": "null" } ], "description": "The job a job ad promotes; null on every other format." }, "message": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdMessage" }, { "type": "null" } ], "description": "A message ad's sender and buttons; null on every other format." }, "newsletter": { "description": "The newsletter an article ad's article belongs to; null when none.", "type": [ "string", "null" ] }, "poster": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account the ad appears from: the advertiser, or a member whose post it promotes; null when the preview names none." }, "poster_title": { "description": "The line under the poster's name (a member's headline); null when none.", "type": [ "string", "null" ] }, "targeting": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdTargeting" }, { "type": "null" } ], "description": "Whom the advertiser selected; null when not disclosed." } }, "required": [ "creative_type", "format", "is_deleted", "poster", "poster_title", "impressions_by_country", "targeting", "message", "job", "event", "document", "newsletter", "company" ], "type": "object" }, "LinkedInAdTargeting": { "properties": { "audience": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Audience criteria; null when not shown." }, "company": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Company criteria; null when not shown." }, "demographic": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Demographic criteria; null when not shown." }, "education": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Education criteria; null when not shown." }, "job": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Job criteria; null when not shown." }, "languages": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdSegments" }, { "type": "null" } ], "description": "The profile languages targeted or excluded; null when not shown." }, "locations": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdSegments" }, { "type": "null" } ], "description": "The locations targeted or excluded, in the language of the advertiser's account; null when not shown." }, "member_interests": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAdCriterion" }, { "type": "null" } ], "description": "Member interests and traits criteria; null when not shown." } }, "required": [ "languages", "locations", "audience", "demographic", "company", "education", "job", "member_interests" ], "type": "object" }, "LinkedInAddress": { "properties": { "city": { "description": "City; null when not shown.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country code; null when not shown.", "type": [ "string", "null" ] }, "postal_code": { "description": "Postal code; null when not shown.", "type": [ "string", "null" ] }, "region": { "description": "State, province or region, as written; null when not shown.", "type": [ "string", "null" ] }, "street": { "description": "Street address; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "street", "city", "region", "postal_code", "country_code" ], "type": "object" }, "LinkedInArticleCard": { "properties": { "comment_count": { "description": "Its comments.", "format": "int64", "type": [ "integer", "null" ] }, "description": { "description": "Its first lines.", "type": [ "string", "null" ] }, "like_count": { "description": "Its reactions.", "format": "int64", "type": [ "integer", "null" ] }, "published_on": { "description": "The day it was published, as a date (YYYY-MM-DD).", "type": [ "string", "null" ] }, "title": { "description": "The article's title.", "type": [ "string", "null" ] }, "url": { "description": "Its link.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "title", "url", "description", "published_on", "like_count", "comment_count" ], "type": "object" }, "LinkedInCertification": { "properties": { "credential_id": { "description": "The credential's ID, as the member wrote it; null when not shown.", "type": [ "string", "null" ] }, "expires_on": { "description": "When it expires, a year or a month; null when it does not or when not shown.", "type": [ "string", "null" ] }, "issued_on": { "description": "When it was issued, a year or a month; null when not shown.", "type": [ "string", "null" ] }, "issuer": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The issuing organization, with its Page's link when it has one; null when not shown." }, "name": { "description": "The license or certification.", "type": "string" }, "url": { "description": "Its credential link; null when it has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "name", "url", "issuer", "issued_on", "expires_on", "credential_id" ], "type": "object" }, "LinkedInCourse": { "properties": { "name": { "description": "The course.", "type": "string" }, "number": { "description": "Its course number, as written (BUS M 520); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "name", "number" ], "type": "object" }, "LinkedInDocument": { "properties": { "manifest_url": { "description": "The manifest LinkedIn's document viewer reads the pages from; the document's own download needs a login.", "format": "uri", "type": [ "string", "null" ] }, "page_count": { "description": "How many pages the document has (media has the first ones).", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The document's title.", "type": [ "string", "null" ] } }, "required": [ "title", "page_count", "manifest_url" ], "type": "object" }, "LinkedInEducation": { "properties": { "degree": { "description": "The degree and field of study, as written; null when not shown.", "type": [ "string", "null" ] }, "ended_on": { "description": "When it ended, a year or a month; null when not shown.", "type": [ "string", "null" ] }, "school": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The school, with its Page's link when it has one; null when not shown." }, "started_on": { "description": "When it started, a year or a month; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "school", "degree", "started_on", "ended_on" ], "type": "object" }, "LinkedInHonor": { "properties": { "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "issued_on": { "description": "When it was issued, a year or a month; null when not shown.", "type": [ "string", "null" ] }, "issuer": { "description": "Who issued it, as written; null when not shown.", "type": [ "string", "null" ] }, "title": { "description": "The honor or award.", "type": "string" } }, "required": [ "title", "issuer", "issued_on", "description" ], "type": "object" }, "LinkedInLanguage": { "properties": { "name": { "description": "The language, as written.", "type": "string" }, "proficiency": { "description": "The proficiency the member states (Native or bilingual proficiency, Elementary proficiency); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "name", "proficiency" ], "type": "object" }, "LinkedInLink": { "properties": { "image_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "source": { "description": "The card's second line: the publisher or its domain.", "type": [ "string", "null" ] }, "title": { "description": "The card's title.", "type": [ "string", "null" ] }, "url": { "description": "The linked page (LinkedIn's redirect and tracking removed).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "title", "source", "image_url" ], "type": "object" }, "LinkedInLocation": { "properties": { "address": { "description": "The address as the Page shows it, its lines joined with commas.", "type": "string" }, "is_primary": { "description": "True for the location the Page marks Primary.", "type": "boolean" } }, "required": [ "address", "is_primary" ], "type": "object" }, "LinkedInMemberRef": { "properties": { "avatar_url": { "description": "Profile picture URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "display_name": { "description": "Display name shown on the profile.", "type": [ "string", "null" ] }, "headline": { "description": "The member's headline or current organization, as the card shows it; null when not shown.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native account ID; null when only the handle is known.", "type": [ "string", "null" ] }, "is_verified": { "description": "Platform verification badge; null where the platform has no badge.", "type": [ "boolean", "null" ] }, "location": { "description": "The member's location, as the card shows it; null when not shown.", "type": [ "string", "null" ] }, "url": { "description": "Canonical profile URL.", "format": "uri", "type": [ "string", "null" ] }, "username": { "description": "Handle without the @; null when the account has none.", "type": [ "string", "null" ] } }, "required": [ "headline", "location", "id", "username", "display_name", "url", "avatar_url", "is_verified" ], "type": "object" }, "LinkedInOrganization": { "properties": { "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "ended_on": { "description": "When it ended, a year or a month; null while current (is_current) or when not shown.", "type": [ "string", "null" ] }, "is_current": { "description": "True for a membership LinkedIn shows as ongoing (to Present); false otherwise, including when no dates are shown.", "type": "boolean" }, "name": { "description": "The organization.", "type": "string" }, "position": { "description": "The member's position in it, as written; null when not shown.", "type": [ "string", "null" ] }, "started_on": { "description": "When it started, a year or a month; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "name", "position", "started_on", "ended_on", "is_current", "description" ], "type": "object" }, "LinkedInPageRef": { "properties": { "avatar_url": { "description": "Profile picture URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "category": { "description": "The Page's industry, as the card shows it; null when not shown.", "type": [ "string", "null" ] }, "display_name": { "description": "Display name shown on the profile.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native account ID; null when only the handle is known.", "type": [ "string", "null" ] }, "is_verified": { "description": "Platform verification badge; null where the platform has no badge.", "type": [ "boolean", "null" ] }, "location": { "description": "The Page's headquarters city and region, as the card shows it; null when not shown.", "type": [ "string", "null" ] }, "url": { "description": "Canonical profile URL.", "format": "uri", "type": [ "string", "null" ] }, "username": { "description": "Handle without the @; null when the account has none.", "type": [ "string", "null" ] } }, "required": [ "category", "location", "id", "username", "display_name", "url", "avatar_url", "is_verified" ], "type": "object" }, "LinkedInPatent": { "properties": { "description": { "description": "Its description; null when none.", "type": [ "string", "null" ] }, "inventors": { "description": "The other members LinkedIn lists as its inventors; [] when it lists none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "issued_on": { "description": "When it was issued: a day (2015-01-20), a month or a year; null when not shown.", "type": [ "string", "null" ] }, "number": { "description": "Its number, as written (US 8,938,217); null when not shown.", "type": [ "string", "null" ] }, "title": { "description": "The patent's title.", "type": "string" } }, "required": [ "title", "number", "issued_on", "description", "inventors" ], "type": "object" }, "LinkedInPosition": { "properties": { "company": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The organization, with its Page's link when it has one; null when not shown." }, "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "ended_on": { "description": "When it ended, a year or a month; null while current (is_current) or when not shown.", "type": [ "string", "null" ] }, "is_current": { "description": "True for a position LinkedIn shows as ongoing (to Present); false otherwise, including when no dates are shown.", "type": "boolean" }, "location": { "description": "Where it is, as written; null when not shown.", "type": [ "string", "null" ] }, "started_on": { "description": "When the position started, as LinkedIn shows it: a year (2015) or a month (2015-03); null when not shown.", "type": [ "string", "null" ] }, "title": { "description": "The position's title; null when not shown.", "type": [ "string", "null" ] } }, "required": [ "title", "company", "started_on", "ended_on", "is_current", "location", "description" ], "type": "object" }, "LinkedInPostComment": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The commenter." }, "id": { "description": "The comment's ID.", "type": [ "string", "null" ] }, "like_count": { "description": "Its reactions.", "format": "int64", "type": [ "integer", "null" ] }, "published_at": { "description": "When it was written, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "The comment's text.", "type": [ "string", "null" ] } }, "required": [ "id", "author", "text", "published_at", "like_count" ], "type": "object" }, "LinkedInPostSpecific": { "properties": { "author_follower_count": { "description": "The author's exact follower count.", "format": "int64", "type": [ "integer", "null" ] }, "author_headline": { "description": "The headline LinkedIn shows under the author's name on the post; null for a Page, whose line is its follower count.", "type": [ "string", "null" ] }, "content_urn": { "description": "The URN of the post's content (urn:li:share: or urn:li:ugcPost:): another number for the same post, which links and LinkedIn's own APIs can name it by. On an article, the article's feed post.", "type": [ "string", "null" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInDocument" }, { "type": "null" } ], "description": "The document the post attaches (a PDF or slides shown as pages), whose first pages are in media; null when none." }, "hidden_image_count": { "description": "How many more images the post has beyond those in media (LinkedIn shows the rest only to signed-in members); null when it shows them all.", "format": "int64", "type": [ "integer", "null" ] }, "is_author_influencer": { "description": "LinkedIn shows its Influencer badge beside the author's name.", "type": [ "boolean", "null" ] }, "is_edited": { "description": "LinkedIn marks the post as edited; null on an article.", "type": [ "boolean", "null" ] }, "link": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInLink" }, { "type": "null" } ], "description": "The link card the post shares (an article, an external video, a live event); null when none." }, "modified_at": { "description": "When an article was last edited, RFC 3339 UTC; null on a post.", "format": "date-time", "type": [ "string", "null" ] }, "more_articles": { "description": "An article's More articles by its author, in LinkedIn's order; [] on a post.", "items": { "$ref": "#/components/schemas/LinkedInArticleCard" }, "type": "array" }, "repost_activity_id": { "description": "The activity the link named when it was a repost without commentary: the page shows the original post, which is what this answer describes (id, author, text, published_at are the original's). Null otherwise.", "type": [ "string", "null" ] }, "reshared_post": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInResharedPost" }, { "type": "null" } ], "description": "The post this one reshares with commentary; null when it reshares none." }, "top_comments": { "description": "The comments LinkedIn shows on the post's page logged out (about ten at most), in its order; [] when none.", "items": { "$ref": "#/components/schemas/LinkedInPostComment" }, "type": "array" } }, "required": [ "content_urn", "author_headline", "author_follower_count", "is_author_influencer", "is_edited", "repost_activity_id", "link", "document", "hidden_image_count", "reshared_post", "top_comments", "modified_at", "more_articles" ], "type": "object" }, "LinkedInProfileSpecific": { "properties": { "affiliated_pages": { "description": "Pages LinkedIn shows as affiliated with this one (its showcase pages, its parent or subsidiaries); [] when it shows none.", "items": { "$ref": "#/components/schemas/LinkedInPageRef" }, "type": "array" }, "certifications": { "description": "The member's licenses and certifications, as their public profile lists them; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInCertification" }, "type": "array" }, "company_size": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "The Page's company size, the bucket of employees it declares (10,001+ is a lower bound with no upper bound); null when not shown." }, "connection_count": { "description": "The member's connections; LinkedIn shows any count above 500 as 500+, which is 500 here and listed in approximate_fields. Null when not shown, and for a Page.", "format": "int64", "type": [ "integer", "null" ] }, "courses": { "description": "The courses the member lists; [] when they list none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInCourse" }, "type": "array" }, "education": { "description": "The member's education, as their public profile lists it. Where LinkedIn hides the list from logged-out visitors, the school it still names, with degree null; [] when it names none.", "items": { "$ref": "#/components/schemas/LinkedInEducation" }, "type": "array" }, "employee_count": { "description": "Members who list the organization as their employer, exact as LinkedIn counts them; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "employees": { "description": "Members LinkedIn shows as working at the organization (the few its Page names logged out); [] when it names none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "experience": { "description": "The member's positions, as their public profile lists them (current first, then past). Where LinkedIn hides the list from logged-out visitors, the current organization it still names, with title null; [] when it names none.", "items": { "$ref": "#/components/schemas/LinkedInPosition" }, "type": "array" }, "founded_year": { "description": "The year the organization was founded, as its Page states it; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "headline": { "description": "The member's headline, the line under their name; null when they have none, and for a Page.", "type": [ "string", "null" ] }, "headquarters": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInAddress" }, { "type": "null" } ], "description": "The Page's headquarters address; null when not shown. location is its city and region as one line." }, "honors": { "description": "The member's honors and awards, as their public profile lists them; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInHonor" }, "type": "array" }, "is_creator": { "description": "True when LinkedIn marks the member as a creator (creator mode); null for a Page.", "type": [ "boolean", "null" ] }, "is_hiring": { "description": "True when the member shows LinkedIn's Hiring frame, false when they don't; null when unknown (as is_open_to_work) and for a Page.", "type": [ "boolean", "null" ] }, "is_influencer": { "description": "True when LinkedIn marks the member as an influencer (its Top Voice badge beside the name); null for a Page.", "type": [ "boolean", "null" ] }, "is_open_to_work": { "description": "True when the member shows LinkedIn's Open to Work frame, false when they don't; null when unknown (LinkedIn's logged-out page doesn't show it, a data partner's copy does: meta.source vendor) and for a Page.", "type": [ "boolean", "null" ] }, "kind": { "description": "What the account is on LinkedIn: a company's Page (linkedin.com/company/…), a school's (/school/…), a showcase page, a company's page for one brand or product (/showcase/…), or a member, a person (/in/…). New values may be added; treat unknown values as other.", "enum": [ "company", "school", "showcase", "member", null ], "type": [ "string", "null" ] }, "languages": { "description": "The languages the member lists, with the proficiency they state; [] when they list none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInLanguage" }, "type": "array" }, "locations": { "description": "The organization's locations as its Page lists them, the primary one first; [] when it lists none.", "items": { "$ref": "#/components/schemas/LinkedInLocation" }, "type": "array" }, "organization_type": { "description": "The Page's organization type as LinkedIn shows it (Public Company, Privately Held, Nonprofit, Educational, Government Agency, Self-Employed, Partnership); null when not shown.", "type": [ "string", "null" ] }, "organizations": { "description": "The organizations the member lists (associations and memberships, not employers); [] when they list none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInOrganization" }, "type": "array" }, "patents": { "description": "The member's patents, as their public profile lists them; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInPatent" }, "type": "array" }, "projects": { "description": "The member's projects, as their public profile lists them; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInProject" }, "type": "array" }, "publications": { "description": "The member's publications, as their public profile lists them; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInPublication" }, "type": "array" }, "recommendation_count": { "description": "How many people have recommended the member, as LinkedIn counts them; null when not shown, and for a Page.", "format": "int64", "type": [ "integer", "null" ] }, "recommendations": { "description": "Recommendations the member received, the ones LinkedIn shows logged out (a few of recommendation_count); [] when it shows none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInRecommendation" }, "type": "array" }, "similar_pages": { "description": "Pages LinkedIn shows as similar to this one; [] when it shows none.", "items": { "$ref": "#/components/schemas/LinkedInPageRef" }, "type": "array" }, "similar_profiles": { "description": "Members LinkedIn shows as similar to this one (its People also viewed); [] when it shows none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInMemberRef" }, "type": "array" }, "skills": { "description": "The skills the member lists, in their order; [] when they list none, and for a Page.", "items": { "type": "string" }, "type": "array" }, "specialties": { "description": "The Page's specialties, in its order; [] when it lists none.", "items": { "type": "string" }, "type": "array" }, "tagline": { "description": "The Page's tagline, the line under its name; null when it has none, and for a member.", "type": [ "string", "null" ] }, "volunteering": { "description": "The member's volunteer experience, as their public profile lists it; [] when it lists none, and for a Page.", "items": { "$ref": "#/components/schemas/LinkedInVolunteering" }, "type": "array" } }, "required": [ "kind", "tagline", "organization_type", "company_size", "employee_count", "founded_year", "specialties", "headquarters", "locations", "affiliated_pages", "similar_pages", "employees", "headline", "connection_count", "is_influencer", "experience", "education", "is_creator", "is_open_to_work", "is_hiring", "volunteering", "projects", "publications", "honors", "certifications", "patents", "courses", "organizations", "languages", "skills", "recommendations", "recommendation_count", "similar_profiles" ], "type": "object" }, "LinkedInProject": { "properties": { "contributors": { "description": "The other members LinkedIn lists as its creators; [] when it lists none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "ended_on": { "description": "When it ended, a year or a month; null while ongoing or when not shown.", "type": [ "string", "null" ] }, "started_on": { "description": "When it started, a year or a month; null when not shown.", "type": [ "string", "null" ] }, "title": { "description": "The project's name.", "type": "string" }, "url": { "description": "The project's link; null when it has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "title", "url", "started_on", "ended_on", "description", "contributors" ], "type": "object" }, "LinkedInPublication": { "properties": { "authors": { "description": "The other members LinkedIn lists as its authors; [] when it lists none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "published_on": { "description": "When it was published: a day (2025-01-28), a month or a year; null when not shown.", "type": [ "string", "null" ] }, "publisher": { "description": "The publisher, as written; null when not shown.", "type": [ "string", "null" ] }, "title": { "description": "The publication's title.", "type": "string" }, "url": { "description": "The publication's link; null when it has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "title", "url", "publisher", "published_on", "description", "authors" ], "type": "object" }, "LinkedInRecommendation": { "properties": { "recommender": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The member who wrote it; null when LinkedIn does not name them." }, "text": { "description": "The recommendation's text, as shown.", "type": "string" } }, "required": [ "recommender", "text" ], "type": "object" }, "LinkedInResharedPost": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "id": { "description": "Its activity ID.", "type": [ "string", "null" ] }, "media": { "description": "Its attachments; [] for a text post.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "published_at": { "description": "When it went public, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Its text.", "type": [ "string", "null" ] }, "url": { "description": "Its canonical link.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "author", "text", "published_at", "media" ], "type": "object" }, "LinkedInVolunteering": { "properties": { "cause": { "description": "The cause, as LinkedIn names it (Economic Empowerment, Health, Education); null when not shown.", "type": [ "string", "null" ] }, "description": { "description": "The member's description of it; null when none.", "type": [ "string", "null" ] }, "ended_on": { "description": "When it ended, a year or a month; null while current (is_current) or when not shown.", "type": [ "string", "null" ] }, "is_current": { "description": "True for a role LinkedIn shows as ongoing (to Present); false otherwise, including when no dates are shown.", "type": "boolean" }, "organization": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The organization, with its Page's link when it has one; null when not shown." }, "role": { "description": "The member's role; null when not shown.", "type": [ "string", "null" ] }, "started_on": { "description": "When it started, a year (2015) or a month (2015-03); null when not shown.", "type": [ "string", "null" ] } }, "required": [ "role", "organization", "cause", "started_on", "ended_on", "is_current", "description" ], "type": "object" }, "LinkedInWebResultSpecific": { "properties": { "company": { "description": "A member's current employer, as the index's snippet says it; null when it does not, and for a Page.", "type": [ "string", "null" ] }, "connection_count": { "description": "A member's connections as the index's snippet states them (LinkedIn shows any count above 500 as 500+, which is 500 here); null when it does not, and for a Page.", "format": "int64", "type": [ "integer", "null" ] }, "headline": { "description": "What the index's title says of a member after their name: their headline, or where LinkedIn hides it their current employer, school or place (often cut short); null when it says none, and for a Page.", "type": [ "string", "null" ] }, "kind": { "description": "What the account is on LinkedIn, as its link says: a company's Page, a school's, a showcase page, or a member. Null when unknown. New values may be added; treat unknown values as unknown.", "enum": [ "company", "school", "showcase", "member", null ], "type": [ "string", "null" ] }, "location": { "description": "Where a member is, as the index's snippet or title says it; null when it does not, and for a Page.", "type": [ "string", "null" ] }, "school": { "description": "The school a member's profile shows first, as the index's snippet says it; null when it does not, and for a Page.", "type": [ "string", "null" ] }, "tagline": { "description": "A Page's tagline as the index's snippet quotes it; null when it quotes none, and for a member.", "type": [ "string", "null" ] } }, "required": [ "kind", "tagline", "headline", "location", "company", "school", "connection_count" ], "type": "object" }, "LinkedinAdResponse": { "properties": { "data": { "$ref": "#/components/schemas/Ad" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinkedinPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinkedinProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinkedinSearch_adsResponse": { "properties": { "data": { "description": "Up to limit items (page size 24), most recently started first with sort=newest, earliest started first with sort=oldest.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "LinkedinSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "LinkedinSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "LinkmeFeaturedLink": { "properties": { "description": { "description": "The text under the label; a music link's artist; null if none.", "type": [ "string", "null" ] }, "group": { "description": "The title of the carousel the card belongs to; null outside a carousel or for one without a title.", "type": [ "string", "null" ] }, "id": { "description": "The link's ID on Linkme.", "type": "string" }, "image_url": { "description": "The link's thumbnail; null if none.", "format": "uri", "type": [ "string", "null" ] }, "is_adult": { "description": "True when Linkme marks the link as adult content and shows a notice before opening it.", "type": [ "boolean", "null" ] }, "platform": { "description": "The site Linkme recognizes the link as (instagram, spotify, opentable, …); link for any other.", "type": [ "string", "null" ] }, "platforms": { "description": "The destinations a music link offers in its menu; [] for any other link.", "items": { "$ref": "#/components/schemas/LinkmeLinkPlatform" }, "type": "array" }, "section": { "description": "The heading the link sits under on the page; null if none.", "type": [ "string", "null" ] }, "title": { "description": "The link's label.", "type": [ "string", "null" ] }, "url": { "description": "Where the link goes; null only for an adult link whose target could not be read (the list is then in approximate_fields) or a music link, which has platforms instead.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "title", "description", "url", "image_url", "platform", "section", "group", "is_adult", "platforms" ], "type": "object" }, "LinkmeLinkPlatform": { "properties": { "name": { "description": "The destination's label (Spotify, Apple Music, …).", "type": "string" }, "url": { "description": "The release on that destination.", "format": "uri", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "LinkmeProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Linkme's words: `metrics.follower_count` is total followers." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinkmeProfileSpecific": { "properties": { "emails": { "description": "Email addresses the page publishes in its contact block; [] if none.", "items": { "type": "string" }, "type": "array" }, "featured_links": { "description": "The page's list of link buttons and cards, in page order, with a carousel's cards in place of the carousel and without section headings, which each entry names instead; [] if none.", "items": { "$ref": "#/components/schemas/LinkmeFeaturedLink" }, "type": "array" }, "is_adult": { "description": "True when the page opens behind an age gate: a notice to continue past, or a birth date to type.", "type": [ "boolean", "null" ] }, "link_count": { "description": "How many entries Linkme counts in the page's link list, section headings and carousels each counting as one.", "format": "int64", "type": [ "integer", "null" ] }, "linkme_connection_count": { "description": "The part of metrics.follower_count Linkme counts itself, which the page's followers sheet lists as Links on the account's own Linkme row; not the links on the page (link_count is). Null when the account hid its total, or on a private page.", "format": "int64", "type": [ "integer", "null" ] }, "locations": { "description": "Street addresses or places the page publishes in its contact block, as written; [] if none.", "items": { "type": "string" }, "type": "array" }, "logo_url": { "description": "The brand logo the page uploaded; null if none.", "format": "uri", "type": [ "string", "null" ] }, "network_follower_count": { "description": "The part of metrics.follower_count that comes from the networks the account connected to Linkme. Null when it has none (no network connected), when the account hid its total, or on a private page.", "format": "int64", "type": [ "integer", "null" ] }, "phones": { "description": "Phone numbers the page publishes in its contact block, as written; [] if none.", "items": { "type": "string" }, "type": "array" }, "profile_visit_count": { "description": "How many visits Linkme counts for the page, as Linkme rounds it from a thousand up: then listed in approximate_fields.", "format": "int64", "type": [ "integer", "null" ] }, "social_links": { "description": "The page's row of social icons, in order; [] if none.", "items": { "$ref": "#/components/schemas/LinkmeSocialLink" }, "type": "array" }, "updated_at": { "description": "When the account last changed, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "emails", "phones", "locations", "social_links", "featured_links", "link_count", "profile_visit_count", "network_follower_count", "linkme_connection_count", "is_adult", "logo_url", "updated_at" ], "type": "object" }, "LinkmeSocialLink": { "properties": { "follower_count": { "description": "The account's followers on that platform, as Linkme last read them; null for a link the account did not connect.", "format": "int64", "type": [ "integer", "null" ] }, "handle": { "description": "The name or ID Linkme stores for the icon, usually the account's username on that platform.", "type": [ "string", "null" ] }, "is_adult": { "description": "True when Linkme marks the link as adult content and shows a notice before opening it.", "type": [ "boolean", "null" ] }, "platform": { "description": "The icon's name as Linkme labels it (Instagram, Tiktok, Youtube, OF, Customlink, …).", "type": "string" }, "url": { "description": "Where the icon links to; null when it holds no link, only a name to copy (an Xbox gamertag, a Zelle name), which handle then gives.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "platform", "url", "handle", "follower_count", "is_adult" ], "type": "object" }, "LinktreeLink": { "properties": { "gates": { "description": "What a visitor passes before following it: sensitive_content and age are click-throughs, anything else (passcode, password, nft, subscribed, wall) is a lock. [] when it opens directly.", "items": { "type": "string" }, "type": "array" }, "group_id": { "description": "The ID of the GROUP block it sits in; null at the top level of the page.", "type": [ "string", "null" ] }, "id": { "description": "Linktree's ID of the link.", "type": "string" }, "position": { "description": "Its order within its group, or on the page when it has no group: lower comes first, and gaps are normal (links lists blocks in page order already).", "format": "int64", "type": [ "integer", "null" ] }, "thumbnail_url": { "description": "The block's image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The label shown on the page.", "type": [ "string", "null" ] }, "type": { "description": "Linktree's type of the block (CLASSIC, GROUP, HEADER, YOUTUBE_VIDEO, SPOTIFY_ALBUM, COMMERCE_PRODUCT, …). New values appear as Linktree adds them.", "type": [ "string", "null" ] }, "url": { "description": "Destination; null for a block with no http(s) one (GROUP, HEADER, an EMAIL block's mailto:) and for a link behind a lock.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "url", "thumbnail_url", "position", "group_id", "gates" ], "type": "object" }, "LinktreeProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "LinktreeProfileSpecific": { "properties": { "badges": { "description": "The badges on the page, as Linktree names them (VERIFICATION_TICK, VERIFIED_AND_NOTABLE_TICK).", "items": { "type": "string" }, "type": "array" }, "content_warning": { "description": "The warning a visitor accepts before the page shows, as Linktree names it (generic, eighteenPlus, twentyOnePlus, twentyFivePlus, moderated); null when there is none.", "type": [ "string", "null" ] }, "email": { "description": "The email address the page lists, on its email icon or an email link.", "type": [ "string", "null" ] }, "is_sensitive": { "description": "True when Linktree marks the page as having sensitive content.", "type": [ "boolean", "null" ] }, "link_platforms": { "description": "The platforms Linktree lists the account as being on, as it names them (TikTok, Instagram, X, …).", "items": { "type": "string" }, "type": "array" }, "links": { "description": "Every block on the page in page order, with its type and group, including headers and groups that have no URL. external_links holds the same destinations without the structure.", "items": { "$ref": "#/components/schemas/LinktreeLink" }, "type": "array" }, "social_links": { "description": "The page's social icons.", "items": { "$ref": "#/components/schemas/LinktreeSocialLink" }, "type": "array" }, "timezone": { "description": "The account's IANA time zone (America/New_York).", "type": [ "string", "null" ] }, "updated_at": { "description": "When the page was last changed, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "verticals": { "description": "The industries Linktree files the account under, as its slugs (music, fashion-beauty, …).", "items": { "type": "string" }, "type": "array" } }, "required": [ "links", "social_links", "email", "timezone", "updated_at", "verticals", "link_platforms", "badges", "is_sensitive", "content_warning" ], "type": "object" }, "LinktreeSocialLink": { "properties": { "platform": { "description": "Which icon, as Linktree's type in lower case (instagram, tiktok, x, email_address, …). New values appear as Linktree adds them.", "type": "string" }, "url": { "description": "Destination: usually an https link, mailto: for an email icon.", "type": "string" } }, "required": [ "platform", "url" ], "type": "object" }, "Live": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text. A list path means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "category": { "description": "The topic or game the broadcast is filed under, as the platform names it.", "type": [ "string", "null" ] }, "ended_at": { "description": "When it went off air, RFC 3339 UTC; null while live or scheduled, and when the platform does not say.", "format": "date-time", "type": [ "string", "null" ] }, "host": { "$ref": "#/components/schemas/ProfileRef", "description": "The broadcasting account." }, "id": { "description": "Platform-native ID of the broadcast (string; TikTok room ID, YouTube video ID).", "type": "string" }, "metrics": { "$ref": "#/components/schemas/LiveMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (tiktok, youtube, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/LivePlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "post_id": { "description": "ID of the post the platform keeps the broadcast as (equals post.id: a YouTube or Rumble video); null when it keeps none (TikTok LIVE) or none yet.", "type": [ "string", "null" ] }, "scheduled_start_at": { "description": "When a scheduled broadcast is due to start, RFC 3339 UTC; null when none was announced.", "format": "date-time", "type": [ "string", "null" ] }, "started_at": { "description": "When the broadcast went on air, RFC 3339 UTC; null while scheduled or when not shown.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "live: on air now; scheduled: announced, not started; ended: over. New values may be added; treat an unknown value as not live.", "enum": [ "live", "scheduled", "ended" ], "type": "string" }, "streams": { "description": "Playback links of the broadcast while live, one per rendition and format, best first; [] when not live or when the platform's links only work from SocialTap's network (YouTube).", "items": { "$ref": "#/components/schemas/LiveStream" }, "type": "array" }, "text": { "description": "Description as plain text; null where the platform has none.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Cover or preview image URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The broadcast's title as the host set it.", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Public page of the broadcast (TikTok: the host's LIVE page, tiktok.com/@/live).", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "status", "title", "text", "category", "host", "started_at", "ended_at", "scheduled_start_at", "thumbnail_url", "post_id", "streams", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "LiveMetrics": { "properties": { "concurrent_viewer_count": { "description": "People watching now; null when not live or not shown.", "format": "int64", "type": [ "integer", "null" ] }, "like_count": { "description": "Likes or hearts; null when hidden or not exposed.", "format": "int64", "type": [ "integer", "null" ] }, "view_count": { "description": "Cumulative views since the broadcast began (TikTok counts entries into the room).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "concurrent_viewer_count", "view_count", "like_count" ], "type": "object" }, "LivePlatformSpecific": { "properties": { "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokLiveSpecific" }, { "type": "null" } ], "description": "A TikTok LIVE room's own fields." }, "twitch": { "anyOf": [ { "$ref": "#/components/schemas/TwitchLiveSpecific" }, { "type": "null" } ], "description": "A Twitch broadcast's own fields." } }, "type": "object" }, "LiveStream": { "properties": { "bitrate_kbps": { "description": "Target bitrate in kbit/s, when the platform states it.", "format": "int64", "type": [ "integer", "null" ] }, "expires_at": { "description": "When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown.", "format": "date-time", "type": [ "string", "null" ] }, "format": { "description": "Delivery format of url: hls (an .m3u8 playlist), dash (an .mpd manifest, TikTok's CMAF) or flv (HTTP-FLV). New values may be added; treat unknown values as other.", "enum": [ "hls", "dash", "flv" ], "type": "string" }, "height": { "description": "Height in pixels; null for audio-only or when not stated.", "format": "int64", "type": [ "integer", "null" ] }, "is_audio_only": { "description": "The rendition carries sound only.", "type": [ "boolean", "null" ] }, "quality": { "description": "The platform's label for the rendition (Original, 1080p60, 720p, …).", "type": [ "string", "null" ] }, "url": { "description": "Playback URL, signed and expiring: see expires_at.", "format": "uri", "type": "string" }, "video_codec": { "description": "Video codec, lowercase (h264, h265); null for audio-only or when not stated.", "type": [ "string", "null" ] }, "width": { "description": "Width in pixels; null for audio-only or when not stated.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "quality", "format", "url", "expires_at", "width", "height", "video_codec", "bitrate_kbps", "is_audio_only" ], "type": "object" }, "Media": { "properties": { "alt_text": { "description": "Accessibility text provided by the author or platform.", "type": [ "string", "null" ] }, "duration_ms": { "description": "Duration in milliseconds (video and audio only).", "format": "int64", "type": [ "integer", "null" ] }, "expires_at": { "description": "When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "height": { "description": "Height in pixels.", "format": "int64", "type": [ "integer", "null" ] }, "thumbnail_url": { "description": "Poster or preview image URL.", "format": "uri", "type": [ "string", "null" ] }, "type": { "description": "Kind of file. New values may be added; treat unknown values as other.", "enum": [ "image", "video", "audio", "gif" ], "type": "string" }, "url": { "description": "Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.", "format": "uri", "type": [ "string", "null" ] }, "width": { "description": "Width in pixels.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "type", "url", "expires_at", "thumbnail_url", "width", "height", "duration_ms", "alt_text" ], "type": "object" }, "MoneyRange": { "properties": { "currency": { "description": "ISO 4217 currency code, uppercase (USD).", "type": "string" }, "lower_bound": { "description": "Inclusive lower bound, in whole units of currency.", "format": "int64", "type": "integer" }, "upper_bound": { "description": "Inclusive upper bound in whole units of currency; null when open-ended.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "lower_bound", "upper_bound", "currency" ], "type": "object" }, "Offer": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (a seller rating in half stars, a date-only delivery estimate). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "availability": { "description": "in_stock: can be bought now; out_of_stock: sold out for now; pre_order: ships later. Null when the platform does not say. New values may be added; treat unknown values as null.", "enum": [ "in_stock", "out_of_stock", "pre_order", null ], "type": [ "string", "null" ] }, "condition": { "description": "Item condition, coarse: new, used (any grade) or refurbished; null when the platform does not say. The platform's own grade is condition_label. New values may be added; treat unknown values as used.", "enum": [ "new", "used", "refurbished", null ], "type": [ "string", "null" ] }, "condition_label": { "description": "The condition as the platform labels it (Used - Like New, Pre-Owned: Good, Renewed).", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 market the offer is in; its prices, availability and delivery are that market's.", "type": [ "string", "null" ] }, "currency": { "description": "ISO 4217 code of every amount of this offer (USD); null when no amount is shown.", "type": [ "string", "null" ] }, "id": { "description": "The offer's ID: the platform's own where it is stable across fetches, else derived from the product, the seller and the condition (B0FQFB8FMG:ALAQLAKJ574UN:new), with ~2, ~3 for a seller's further offers in one condition, counted across the list's pages in the platform's order. A derived ID is stable while the seller's offers in that condition keep their order; two of them can swap IDs when their order changes.", "type": "string" }, "is_featured": { "description": "The offer the product page shows by default (the buy box); at most one offer of a product is. Null where the platform features none.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/OfferMetrics", "description": "Counts at fetch time; null = not shown, 0 = zero." }, "original_price": { "description": "Price before the discount (the struck-through list or earlier price), in major units of currency; null when the offer shows none.", "format": "double", "type": [ "number", "null" ] }, "platform": { "description": "Platform ID (amazon, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/OfferPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "price": { "description": "The offer's price in major units of currency (58.47), discounts applied; shipping and tax excluded. 0 = free; null when not shown.", "format": "double", "type": [ "number", "null" ] }, "product_id": { "description": "ID of the product offered (equals product.id of the platform's product endpoints).", "type": "string" }, "seller": { "$ref": "#/components/schemas/ProfileRef", "description": "The seller (a shop on the platform, or a merchant's site on a comparison platform); fields null when not shown." }, "seller_rating": { "description": "The seller's average rating out of 5 (metrics.seller_rating_count ratings behind it), as the platform shows it (rounded ones in approximate_fields); null when the seller is unrated or the platform does not show it.", "format": "double", "type": [ "number", "null" ] }, "shipping": { "$ref": "#/components/schemas/OfferShipping", "description": "Delivery terms of this offer; each null when not shown." }, "title": { "description": "The seller's own title for the product, where offers carry one (an eBay listing's, a shop's on Google Shopping); null where every offer shares the product's title.", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none; null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The offer's own page (the merchant's page, the listing, or the product page with this seller selected); null when the platform has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "product_id", "url", "title", "seller", "price", "original_price", "currency", "condition", "condition_label", "availability", "is_featured", "seller_rating", "shipping", "country_code", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "OfferMetrics": { "properties": { "seller_rating_count": { "description": "Ratings behind seller_rating, as the platform counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "seller_rating_count" ], "type": "object" }, "OfferPlatformSpecific": { "properties": { "amazon": { "anyOf": [ { "$ref": "#/components/schemas/AmazonOfferSpecific" }, { "type": "null" } ], "description": "An Amazon offer's own fields." } }, "type": "object" }, "OfferShipping": { "properties": { "earliest_delivery_at": { "description": "First day of the standard delivery estimate, as that date at 00:00:00Z (date-only: approximate_fields); equal to latest_delivery_at for a one-day estimate; null when the platform gives no start.", "format": "date-time", "type": [ "string", "null" ] }, "fee": { "description": "Standard shipping fee of this item alone, in major units of the offer's currency; 0 = free shipping; null when it depends on the order (free over a threshold) or is not shown.", "format": "double", "type": [ "number", "null" ] }, "is_offered": { "description": "The seller ships this offer (false: local pickup only); null when not shown.", "type": [ "boolean", "null" ] }, "latest_delivery_at": { "description": "Last day of the standard delivery estimate, as that date at 00:00:00Z (date-only: approximate_fields); null when the platform gives no estimate.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "is_offered", "fee", "earliest_delivery_at", "latest_delivery_at" ], "type": "object" }, "PageInfo": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages", null ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" }, "PillarChannel": { "properties": { "channel_name": { "description": "The account's name or ID on that service, as Pillar stores it.", "type": "string" }, "follower_count": { "description": "Its followers or subscribers, as Pillar last read them.", "format": "int64", "type": [ "integer", "null" ] }, "platform": { "description": "The service, in lowercase (instagram, tiktok, youtube, twitter, facebook, twitch, snapchat).", "type": "string" } }, "required": [ "platform", "channel_name", "follower_count" ], "type": "object" }, "PillarLink": { "properties": { "click_count": { "description": "How many times the link was clicked, as Pillar counts it.", "format": "int64", "type": [ "integer", "null" ] }, "description": { "description": "The line under the title.", "type": [ "string", "null" ] }, "id": { "description": "Pillar's ID of the link.", "type": "string" }, "title": { "description": "The link's title, as shown.", "type": [ "string", "null" ] }, "url": { "description": "Where the link goes.", "format": "uri", "type": "string" } }, "required": [ "id", "title", "description", "url", "click_count" ], "type": "object" }, "PillarPageResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Pillar's words: `metrics.follower_count` is audience." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "PillarProduct": { "properties": { "currency": { "description": "The price's ISO 4217 currency.", "type": [ "string", "null" ] }, "description": { "description": "The item's short description.", "type": [ "string", "null" ] }, "id": { "description": "Pillar's ID of the item.", "type": "string" }, "image_url": { "description": "The item's image.", "format": "uri", "type": [ "string", "null" ] }, "price": { "description": "The price, in currency; null when the page does not show one.", "format": "double", "type": [ "number", "null" ] }, "title": { "description": "The item's name.", "type": [ "string", "null" ] }, "type": { "description": "product links to another store; digital_product, course, experience and fan_request are sold on Pillar itself. New values may be added.", "enum": [ "product", "digital_product", "course", "experience", "fan_request" ], "type": "string" }, "url": { "description": "Where to buy it: the store's link for a product, the Pillar checkout otherwise.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "type", "title", "description", "url", "image_url", "price", "currency" ], "type": "object" }, "PillarProfileSpecific": { "properties": { "audience": { "description": "The connected accounts the page shows follower counts for: [] if it shows none.", "items": { "$ref": "#/components/schemas/PillarChannel" }, "type": "array" }, "contact_email": { "description": "The contact email address on the creator's Pillar account; null when the page hides its email icon.", "type": [ "string", "null" ] }, "email": { "description": "The email address the page shows among its social icons: the icon's own, else the contact email; null when it has none or hides it.", "type": [ "string", "null" ] }, "first_name": { "description": "The first name on the Pillar account.", "type": [ "string", "null" ] }, "full_name": { "description": "The full name on the Pillar account, which can differ from display_name.", "type": [ "string", "null" ] }, "is_claimed": { "description": "False for a page Pillar set up that its creator has not claimed yet.", "type": [ "boolean", "null" ] }, "last_name": { "description": "The last name on the Pillar account: the full name after the first name; null when it does not start with it.", "type": [ "string", "null" ] }, "links": { "description": "The links the page shows, in page order, with their click counts: [] if none.", "items": { "$ref": "#/components/schemas/PillarLink" }, "type": "array" }, "products": { "description": "What the page sells or recommends, in page order: [] if nothing.", "items": { "$ref": "#/components/schemas/PillarProduct" }, "type": "array" }, "socials": { "description": "The social accounts the page shows as icons: [] if none.", "items": { "$ref": "#/components/schemas/PillarSocial" }, "type": "array" }, "videos": { "description": "The videos the page features, in page order: [] if none.", "items": { "$ref": "#/components/schemas/PillarVideo" }, "type": "array" } }, "required": [ "first_name", "last_name", "full_name", "email", "contact_email", "is_claimed", "socials", "links", "products", "videos", "audience" ], "type": "object" }, "PillarSocial": { "properties": { "platform": { "description": "The service, in lowercase, as Pillar names it (instagram, tiktok, spotify, apple_app_store, …).", "type": "string" }, "url": { "description": "The link behind the icon.", "format": "uri", "type": "string" } }, "required": [ "platform", "url" ], "type": "object" }, "PillarVideo": { "properties": { "description": { "description": "The video's description on the page.", "type": [ "string", "null" ] }, "id": { "description": "Pillar's ID of the video.", "type": "string" }, "title": { "description": "The video's title on the page.", "type": [ "string", "null" ] }, "url": { "description": "The video's link.", "format": "uri", "type": "string" } }, "required": [ "id", "title", "description", "url" ], "type": "object" }, "PinterestBoardRef": { "properties": { "id": { "description": "The board's ID.", "type": [ "string", "null" ] }, "title": { "description": "The board's name.", "type": [ "string", "null" ] }, "url": { "description": "The board's link.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "title", "url" ], "type": "object" }, "PinterestBoardResponse": { "properties": { "data": { "$ref": "#/components/schemas/Playlist" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "PinterestBoard_pinsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Pinterest's order for logged-out visitors: mostly the latest saved first, with a few pins it picks moved to the top. In Pinterest's words: `metrics.like_count` is reactions, `metrics.save_count` is saves.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "PinterestBoardsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the order the account's profile shows its boards in: its own arrangement (A to Z, or one it set by hand), else the boards saved to most recently first.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "PinterestPinResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post", "description": "In Pinterest's words: `metrics.like_count` is reactions, `metrics.save_count` is saves." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "PinterestPinsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), newest first. In Pinterest's words: `metrics.like_count` is reactions, `metrics.save_count` is saves.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "PinterestPlaylistSpecific": { "properties": { "board": { "anyOf": [ { "$ref": "#/components/schemas/PinterestBoardRef" }, { "type": "null" } ], "description": "For a section, the board it is part of; null on a board." }, "collaborator_count": { "description": "Accounts other than its owner that can save pins to the board, exact; 0 on a board only its owner saves to.", "format": "int64", "type": [ "integer", "null" ] }, "collaborators": { "description": "The accounts other than its owner that can save pins to the board, as Pinterest lists them; [] when none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "created_at": { "description": "When the board was created, RFC 3339 UTC; null on a section and when the source does not state it.", "format": "date-time", "type": [ "string", "null" ] }, "follower_count": { "description": "Accounts following the board, exact; null on a section, which has no followers of its own.", "format": "int64", "type": [ "integer", "null" ] }, "interests": { "description": "The interests Pinterest relates the board to, each an ideas page of its own, in its order; [] when none.", "items": { "type": "string" }, "type": "array" }, "privacy": { "description": "public, or protected: a board Pinterest keeps off its owner's profile and out of search engines but shows anyone with its link (a shop's catalog of products). New values may be added.", "type": [ "string", "null" ] }, "section_count": { "description": "Sections the board is divided into; 0 when none, null on a section.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "follower_count", "created_at", "privacy", "collaborator_count", "collaborators", "section_count", "interests", "board" ], "type": "object" }, "PinterestPostSpecific": { "properties": { "author_follower_count": { "description": "The pinner's exact follower count; null when the source does not state it.", "format": "int64", "type": [ "integer", "null" ] }, "board": { "anyOf": [ { "$ref": "#/components/schemas/PinterestBoardRef" }, { "type": "null" } ], "description": "The board the pin is saved to." }, "caption_languages": { "description": "The languages of the captions Pinterest has for the pin's video (en-us, …), as BCP-47 tags; [] when none.", "items": { "type": "string" }, "type": "array" }, "domain": { "description": "The linked site's domain as Pinterest shows it (tastemade.com); null for a pin that links nowhere.", "type": [ "string", "null" ] }, "dominant_color": { "description": "The picture's dominant color, as #rrggbb.", "type": [ "string", "null" ] }, "interests": { "description": "The interests Pinterest files the pin under, each an ideas page of its own, in its order; [] when none.", "items": { "type": "string" }, "type": "array" }, "is_ad": { "description": "The pin runs as an ad (a Promoted pin).", "type": [ "boolean", "null" ] }, "is_author_verified_merchant": { "description": "Whether the pinner is a Pinterest verified merchant (a shop Pinterest checked); null when the source does not state it.", "type": [ "boolean", "null" ] }, "is_repin": { "description": "The pin is a save (repin) of another account's pin.", "type": [ "boolean", "null" ] }, "link_url": { "description": "The page the pin links to (its destination); null for a pin saved without one.", "format": "uri", "type": [ "string", "null" ] }, "original_pinner": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account that first saved this picture or video to Pinterest (its uploader, for a pin made on Pinterest); null when Pinterest names none. author is the account whose pin this is, which for a repin is another." }, "repin_count": { "description": "Saves of this pin itself; metrics.save_count counts the saves of every pin of the same picture or video.", "format": "int64", "type": [ "integer", "null" ] }, "rich_type": { "description": "The kind of page a rich pin shows details of (recipe, article, product, …); null for a pin that is no rich pin.", "type": [ "string", "null" ] } }, "required": [ "link_url", "domain", "board", "original_pinner", "author_follower_count", "is_author_verified_merchant", "is_repin", "repin_count", "dominant_color", "rich_type", "interests", "caption_languages", "is_ad" ], "type": "object" }, "PinterestProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Pinterest's words: `metrics.post_count` is pins." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "PinterestProfileSpecific": { "properties": { "all_following_count": { "description": "Everything the account follows, as Pinterest counts it: accounts, boards and interests. metrics.following_count counts the accounts alone. Its page's \"N following\" is this minus interest_following_count (accounts and boards), so it can be more than metrics.following_count.", "format": "int64", "type": [ "integer", "null" ] }, "interest_following_count": { "description": "The interests (topics) the account follows, as Pinterest counts them: part of all_following_count, and the part its page's following count leaves out.", "format": "int64", "type": [ "integer", "null" ] }, "is_business_account": { "description": "A Pinterest business account, which brands and creators alike can have.", "type": [ "boolean", "null" ] }, "is_verified_merchant": { "description": "Pinterest's verified merchant badge: a shop whose products Pinterest checked.", "type": [ "boolean", "null" ] }, "is_website_verified": { "description": "True when the account proved it owns the website in external_links (Pinterest's claimed website).", "type": [ "boolean", "null" ] }, "last_post_at": { "description": "When the account last saved a pin to one of its boards, its own or another account's, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "monthly_view_count": { "description": "The account's monthly views, as Pinterest counts them: how often its pins were seen over the last month. Above ten million Pinterest writes only that it is more, and this is 10000000, listed in approximate_fields; null when the account hides it.", "format": "int64", "type": [ "integer", "null" ] }, "playlist_count": { "description": "Boards, as Pinterest counts them for the account. Its public list of boards can hold fewer.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "playlist_count", "monthly_view_count", "all_following_count", "interest_following_count", "is_business_account", "is_verified_merchant", "is_website_verified", "last_post_at" ], "type": "object" }, "PinterestRefinement": { "properties": { "id": { "description": "The narrower topic's ID.", "type": "string" }, "label": { "description": "The button's text (Blue for Blue Star Nail Designs).", "type": [ "string", "null" ] }, "name": { "description": "The narrower topic's full name.", "type": [ "string", "null" ] }, "url": { "description": "The narrower topic's ideas page.", "format": "uri", "type": "string" } }, "required": [ "label", "id", "name", "url" ], "type": "object" }, "PinterestSearch_pinsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), Pinterest's own relevance order for the query. In Pinterest's words: `metrics.like_count` is reactions, `metrics.save_count` is saves.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "PinterestTop_trendsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Pinterest Trends' rank for the board (1 = top).", "items": { "$ref": "#/components/schemas/Trend" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "PinterestTopicRef": { "properties": { "id": { "description": "The topic's ID.", "type": "string" }, "name": { "description": "The topic's name as the page shows it.", "type": [ "string", "null" ] }, "url": { "description": "The topic's ideas page.", "format": "uri", "type": "string" } }, "required": [ "id", "name", "url" ], "type": "object" }, "PinterestTopicResponse": { "properties": { "data": { "$ref": "#/components/schemas/Topic" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "PinterestTopicSpecific": { "properties": { "cover_image_url": { "description": "The picture Pinterest shows for the topic when its page is shared (one of its pins' pictures, so it changes over time); null when the page has none.", "format": "uri", "type": [ "string", "null" ] }, "follower_count": { "description": "Accounts following the topic on Pinterest; null for a topic that is no interest accounts can follow (is_interest false).", "format": "int64", "type": [ "integer", "null" ] }, "is_category": { "description": "The topic is one of Pinterest's top categories (Travel, Beauty, …), as its ideas page lists them.", "type": [ "boolean", "null" ] }, "is_interest": { "description": "The topic is one of Pinterest's interests, which pins are filed under and accounts can follow; false for a page made for a search phrase.", "type": [ "boolean", "null" ] }, "parent_topics": { "description": "The broader topics this one sits under, broadest first, as the page's breadcrumbs show them; [] for a top category.", "items": { "$ref": "#/components/schemas/PinterestTopicRef" }, "type": "array" }, "refinements": { "description": "The narrower topics the page offers as buttons above its pins, in its order; [] when none.", "items": { "$ref": "#/components/schemas/PinterestRefinement" }, "type": "array" }, "related_boards": { "description": "Boards Pinterest shows on the topic's page, in its order; [] when none.", "items": { "$ref": "#/components/schemas/PinterestBoardRef" }, "type": "array" }, "related_topics": { "description": "Related topics the page links to, in its order; [] when none.", "items": { "$ref": "#/components/schemas/PinterestTopicRef" }, "type": "array" }, "search_count": { "description": "How many searches Pinterest counts for the topic's words, as its ideas page data states it (Pinterest doesn't say over which period); null when the source does not state it.", "format": "int64", "type": [ "integer", "null" ] }, "trending_searches": { "description": "Searches Pinterest shows as trending for the topic, in its order; [] when none.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "description": "When Pinterest last updated the topic's page data (its counts and related topics).", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "search_count", "follower_count", "is_category", "is_interest", "updated_at", "parent_topics", "refinements", "related_topics", "trending_searches", "related_boards", "cover_image_url" ], "type": "object" }, "PinterestTrendSpecific": { "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country whose searches the figures count (Pinterest counts some countries together: the endpoint's notes say which).", "type": [ "string", "null" ] }, "history": { "description": "How much the term was searched each week, oldest first, relative to the series' peak (1); [] on a board that does not request the series (listed in unknown_fields).", "items": { "$ref": "#/components/schemas/TrendPoint" }, "type": "array" }, "market_country_codes": { "description": "Every country whose searches the figures count together, as ISO 3166-1 alpha-2 codes: [\"US\"] for a country Pinterest publishes a board for on its own, its group's ([\"GB\", \"IE\"] for IE) for one Pinterest counts with others. [] when unknown.", "items": { "type": "string" }, "type": "array" }, "monthly_change": { "description": "Change over the past month, a fraction like weekly_change, rounded by Pinterest the same way (always listed in approximate_fields); capped at 100, a lower bound then.", "format": "double", "maximum": 100, "minimum": -1, "type": [ "number", "null" ] }, "period_end_at": { "description": "End of the period Pinterest's figures count, exclusive (midnight UTC after its weekly data's last day), RFC 3339 UTC: Pinterest publishes weekly, a few days behind.", "format": "date-time", "type": [ "string", "null" ] }, "search_index": { "description": "How much the term is searched in the table's period, relative to the table's most searched term (100).", "format": "int64", "maximum": 100, "minimum": 0, "type": [ "integer", "null" ] }, "seasonality": { "description": "How seasonal the term is, 0 to 1 (1 = searched at the same time every year), as Pinterest scores it.", "format": "double", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] }, "weekly_change": { "description": "Change in the term's searches over the past week, a fraction (0.3 = +30 %, -0.5 = -50 %), rounded by Pinterest to one or two significant digits (always listed in approximate_fields); capped at 100 (+10,000 %), a lower bound then.", "format": "double", "maximum": 100, "minimum": -1, "type": [ "number", "null" ] }, "yearly_change": { "description": "Change against the same time last year, a fraction like weekly_change, rounded by Pinterest the same way (always listed in approximate_fields); capped at 100, a lower bound then.", "format": "double", "maximum": 100, "minimum": -1, "type": [ "number", "null" ] } }, "required": [ "country_code", "market_country_codes", "search_index", "weekly_change", "monthly_change", "yearly_change", "seasonality", "period_end_at", "history" ], "type": "object" }, "PinterestWeb_pageResponse": { "properties": { "data": { "$ref": "#/components/schemas/WebPage", "description": "In Pinterest's words: `metrics.share_count` is saves." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "Place": { "properties": { "account": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The platform account that represents the place (its business account or Page); null when none is linked." }, "address": { "description": "Address as the platform shows it: a street line on some platforms, the whole postal address or only the enclosing region on others; not normalized.", "type": [ "string", "null" ] }, "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "category": { "description": "The platform's category label (Cafe, City, Pizza Fast Food), as shown; not normalized across platforms.", "type": [ "string", "null" ] }, "city": { "description": "City or locality, as shown.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country of the place.", "type": [ "string", "null" ] }, "description": { "description": "The place's description or about text; null when none is shown.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native place ID (TikTok POI ID, Instagram location ID, Facebook Page ID).", "type": "string" }, "images": { "description": "Pictures of the place the platform shows, in its order; each of type image. [] when none (listed in unknown_fields when the source cannot see them). Platform CDN URLs can expire within hours: see expires_at.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "latitude": { "description": "WGS 84 latitude in degrees; null when the platform does not show coordinates (set together with longitude).", "format": "double", "type": [ "number", "null" ] }, "longitude": { "description": "WGS 84 longitude in degrees; null when the platform does not show coordinates (set together with latitude).", "format": "double", "type": [ "number", "null" ] }, "metrics": { "$ref": "#/components/schemas/PlaceMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "name": { "description": "Place name as the platform shows it.", "type": "string" }, "phone": { "description": "The business's public phone number, as shown; null when none is shown.", "type": [ "string", "null" ] }, "platform": { "description": "Platform ID (tiktok, instagram, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/PlacePlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "postal_code": { "description": "Postal or ZIP code.", "type": [ "string", "null" ] }, "price_range": { "description": "The business's price range, 1 (inexpensive, $) to 4 (expensive, $$$$); null when the platform shows none.", "format": "int64", "type": [ "integer", "null" ] }, "type": { "description": "Coarse kind: venue for one spot (a business, landmark or address), area for a region (a neighborhood, city, state or country); unknown when the platform does not say. New values may be added; treat unknown values as unknown.", "enum": [ "venue", "area", "unknown" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical place page URL.", "format": "uri", "type": "string" }, "website_url": { "description": "The place's own website.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "name", "url", "type", "category", "description", "address", "city", "postal_code", "country_code", "latitude", "longitude", "phone", "website_url", "price_range", "images", "account", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "PlaceMetrics": { "properties": { "image_count": { "description": "Pictures the platform has of the place; more than the length of images when the source returns only the first ones.", "format": "int64", "type": [ "integer", "null" ] }, "post_count": { "description": "Public posts tagged with the place, as the platform counts them.", "format": "int64", "type": [ "integer", "null" ] }, "review_count": { "description": "Public reviews or recommendations of the place, as the platform counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "post_count", "review_count", "image_count" ], "type": "object" }, "PlacePlatformSpecific": { "properties": { "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPlaceSpecific" }, { "type": "null" } ], "description": "A Facebook place's own fields." }, "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramPlaceSpecific" }, { "type": "null" } ], "description": "An Instagram location's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPlaceSpecific" }, { "type": "null" } ], "description": "A TikTok POI's own fields." } }, "type": "object" }, "PlaceRef": { "properties": { "address": { "description": "Address as the platform shows it (one line, not normalized).", "type": [ "string", "null" ] }, "city": { "description": "City or locality, as shown.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country of the place.", "type": [ "string", "null" ] }, "id": { "description": "The place's ID as the platform's place endpoints key it (place.id); null for a venue given as free text.", "type": [ "string", "null" ] }, "latitude": { "description": "WGS 84 latitude in degrees; null when the platform shows no coordinates (set together with longitude).", "format": "double", "type": [ "number", "null" ] }, "longitude": { "description": "WGS 84 longitude in degrees; null when the platform shows no coordinates (set together with latitude).", "format": "double", "type": [ "number", "null" ] }, "name": { "description": "The place's name as shown (a venue's name, or the text its host typed).", "type": [ "string", "null" ] }, "url": { "description": "The place's page URL; null for a venue given as free text.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "address", "city", "country_code", "latitude", "longitude" ], "type": "object" }, "PlaceSummary": { "properties": { "address": { "description": "Address as the index's text shows it; null when it does not.", "type": [ "string", "null" ] }, "category": { "description": "The platform's category label, as the index's text shows it; null when it does not.", "type": [ "string", "null" ] }, "city": { "description": "City or locality, as the index's text shows it.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country of the place.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native place ID; null until the result is filled.", "type": [ "string", "null" ] }, "latitude": { "description": "WGS 84 latitude in degrees; null unless the index's text states coordinates, until the result is filled (set together with longitude).", "format": "double", "type": [ "number", "null" ] }, "longitude": { "description": "WGS 84 longitude in degrees; null unless the index's text states coordinates, until the result is filled (set together with latitude).", "format": "double", "type": [ "number", "null" ] }, "metrics": { "$ref": "#/components/schemas/PlaceMetrics", "description": "Counts as the index's text states them (\"12K posts\"; rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "name": { "description": "Place name as the index's title shows it; null when it shows none.", "type": [ "string", "null" ] }, "url": { "description": "Canonical place page URL (equals the result's url).", "format": "uri", "type": "string" } }, "required": [ "id", "name", "url", "category", "address", "city", "country_code", "latitude", "longitude", "metrics" ], "type": "object" }, "Playlist": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform, date-only or parsed from display text. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Description as plain text; null when it has none or the platform shows none (TikTok).", "type": [ "string", "null" ] }, "id": { "description": "Platform-native playlist ID (string): TikTok's playlist (mix) or collection ID, YouTube's list ID (PL…), Facebook's video list ID.", "type": "string" }, "is_collaborative": { "description": "Whether people its owner invites can add to it as well (a collaborative playlist, a group board); null where the platform doesn't say.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/PlaylistMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "owner": { "$ref": "#/components/schemas/ProfileRef", "description": "The account that curates it (for a collection, the account that saved the posts, not their authors). Where a platform's curators are not accounts (Apple Music), what it states of them: a name, perhaps a page and a picture, with id and username null, and every field null when it names no one." }, "platform": { "description": "Platform ID (tiktok, youtube, facebook, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/PlaylistPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "platform_type": { "description": "The platform's own label, lowercase (mix, collection, playlist, series, podcast, …).", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Cover image URL (the owner's chosen cover, else the platform's pick, often the first post's). Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Name its owner gave it.", "type": [ "string", "null" ] }, "type": { "description": "playlist: a list its owner curates and orders (TikTok playlists, YouTube playlists, Facebook playlists and series); collection: posts an account saved from any creator into a named public folder (TikTok collections). New values may be added; treat unknown values as playlist.", "enum": [ "playlist", "collection" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical playlist URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "type", "platform_type", "title", "description", "owner", "thumbnail_url", "is_collaborative", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "PlaylistMetrics": { "properties": { "post_count": { "description": "Posts in it as the platform counts them (it may count posts that are no longer public, so a walk of its posts can return fewer).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "post_count" ], "type": "object" }, "PlaylistPlatformSpecific": { "properties": { "amazon": { "anyOf": [ { "$ref": "#/components/schemas/AmazonPlaylistSpecific" }, { "type": "null" } ], "description": "An Amazon influencer's idea list's own fields." }, "applemusic": { "anyOf": [ { "$ref": "#/components/schemas/ApplemusicPlaylistSpecific" }, { "type": "null" } ], "description": "An Apple Music playlist's or station's own fields." }, "pinterest": { "anyOf": [ { "$ref": "#/components/schemas/PinterestPlaylistSpecific" }, { "type": "null" } ], "description": "A Pinterest board's or board section's own fields." }, "spotify": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyPlaylistSpecific" }, { "type": "null" } ], "description": "A Spotify playlist's own fields." }, "youtube": { "anyOf": [ { "$ref": "#/components/schemas/YouTubePlaylistSpecific" }, { "type": "null" } ], "description": "A YouTube playlist's own fields." } }, "type": "object" }, "Podcast": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform, date-only or parsed from display text (rating at one decimal, metrics.rating_count from \"2.6K\"). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "categories": { "description": "Categories or topics the platform files it under, as shown (not normalized), the main one first; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "cover_url": { "description": "Cover art URL at the largest size the platform serves; null when it has none. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "description": { "description": "About the show, as plain text; null when it has none or the platform shows none.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native show ID (string), the one in its page's URL.", "type": "string" }, "is_explicit": { "description": "Marked as holding explicit content by the platform; null when it does not say.", "type": [ "boolean", "null" ] }, "latest_episode_at": { "description": "When its newest episode came out, RFC 3339 UTC; listed in approximate_fields when read from display text or a date alone. Null when the source does not show it.", "format": "date-time", "type": [ "string", "null" ] }, "media_type": { "description": "What its episodes are: audio, video or mixed (both); null when the platform does not say. New values may be added.", "enum": [ "audio", "video", "mixed", null ], "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/PodcastMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (spotify, youtube, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/PodcastPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "publisher": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The platform account of the publisher; null when the platform names them without an account (always on Spotify)." }, "publisher_name": { "description": "Who publishes the show, as the platform names them; null when it does not.", "type": [ "string", "null" ] }, "rating": { "description": "Listeners' average rating, 1 to 5 stars (metrics.rating_count ratings behind it; listed in approximate_fields when the platform rounds it); null when unrated or the platform shows none.", "format": "double", "type": [ "number", "null" ] }, "show_type": { "description": "episodic: its episodes stand alone, newest first; serial: they are heard in order, from the first. Null when the platform does not say. New values may be added.", "enum": [ "episodic", "serial", null ], "type": [ "string", "null" ] }, "title": { "description": "The show's name as the platform lists it.", "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical show page URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "title", "description", "publisher_name", "publisher", "cover_url", "media_type", "show_type", "categories", "is_explicit", "rating", "latest_episode_at", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "PodcastMetrics": { "properties": { "episode_count": { "description": "Episodes the platform counts (it may count ones no longer public, so a walk of the episodes can return fewer); null when it does not state one.", "format": "int64", "type": [ "integer", "null" ] }, "rating_count": { "description": "Listeners who rated the show, 0 when none has; null when the platform shows no count.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "episode_count", "rating_count" ], "type": "object" }, "PodcastPlatformSpecific": { "type": "object" }, "Post": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The posting account. An account the platform no longer names (a deleted account) has a null id and username and the platform's label as display_name (Reddit: [deleted]). A post credited to what is no account of the platform's (an Apple Music radio episode's show) has a null id and username, and every other field null too when the platform doesn't name it." }, "coauthors": { "description": "Other accounts credited as co-authors of the post (Instagram and Facebook collabs, YouTube collaborations), in the platform's order, author excluded; [] if none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "duration_ms": { "description": "Length of the primary video or audio in milliseconds; null for other posts.", "format": "int64", "type": [ "integer", "null" ] }, "hashtags": { "description": "Hashtags without #, case kept; [] if none.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Platform-native post ID (string; Instagram shortcode, Reddit with its t3_ prefix).", "type": "string" }, "is_nsfw": { "description": "Marked adult or sensitive by the platform.", "type": [ "boolean", "null" ] }, "is_pinned": { "description": "Pinned to the author's profile.", "type": [ "boolean", "null" ] }, "is_sponsored": { "description": "Labeled as a paid partnership or branded content.", "type": [ "boolean", "null" ] }, "language": { "description": "BCP-47 language of text, when the platform states it.", "type": [ "string", "null" ] }, "media": { "description": "Attachments in display order (carousel items); [] for text posts.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "mentions": { "description": "Mentioned or tagged usernames without @; [] if none.", "items": { "type": "string" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/PostMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (tiktok, youtube, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/PostPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "platform_type": { "description": "The platform's own product label, lowercase (reel, short, story, live, tweet, …).", "type": [ "string", "null" ] }, "published_at": { "description": "When the post went public, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Caption, description or body as plain text.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Cover or poster image URL.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Headline (YouTube title, Reddit title); null on caption-only platforms.", "type": [ "string", "null" ] }, "type": { "description": "Normalized content shape. New values may be added; treat unknown values as other.", "enum": [ "video", "image", "carousel", "text", "link", "audio" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical post URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "type", "platform_type", "title", "text", "language", "published_at", "author", "coauthors", "duration_ms", "thumbnail_url", "media", "hashtags", "mentions", "is_pinned", "is_sponsored", "is_nsfw", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "PostMetrics": { "properties": { "comment_count": { "description": "Comments and replies.", "format": "int64", "type": [ "integer", "null" ] }, "like_count": { "description": "Likes, hearts, total reactions or upvotes; never negative. Null when hidden by the owner.", "format": "int64", "type": [ "integer", "null" ] }, "quote_count": { "description": "Quote posts.", "format": "int64", "type": [ "integer", "null" ] }, "repost_count": { "description": "Reposts, retweets or reshares.", "format": "int64", "type": [ "integer", "null" ] }, "save_count": { "description": "Saves, bookmarks or favorites.", "format": "int64", "type": [ "integer", "null" ] }, "share_count": { "description": "Shares or sends (not reposts).", "format": "int64", "type": [ "integer", "null" ] }, "view_count": { "description": "Views or plays.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "view_count", "like_count", "comment_count", "share_count", "repost_count", "quote_count", "save_count" ], "type": "object" }, "PostPlatformSpecific": { "properties": { "amazon": { "anyOf": [ { "$ref": "#/components/schemas/AmazonPostSpecific" }, { "type": "null" } ], "description": "An Amazon influencer's storefront photo's or video's own fields." }, "applemusic": { "anyOf": [ { "$ref": "#/components/schemas/ApplemusicPostSpecific" }, { "type": "null" } ], "description": "An Apple Music track's, music video's or radio episode's own fields." }, "bluesky": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyPostSpecific" }, { "type": "null" } ], "description": "A Bluesky post's own fields." }, "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookPostSpecific" }, { "type": "null" } ], "description": "A Facebook post's own fields." }, "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramPostSpecific" }, { "type": "null" } ], "description": "An Instagram post's own fields." }, "kick": { "anyOf": [ { "$ref": "#/components/schemas/KickPostSpecific" }, { "type": "null" } ], "description": "A Kick post's own fields." }, "kwai": { "anyOf": [ { "$ref": "#/components/schemas/KwaiPostSpecific" }, { "type": "null" } ], "description": "A Kwai post's own fields." }, "linkedin": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInPostSpecific" }, { "type": "null" } ], "description": "A LinkedIn post's own fields." }, "pinterest": { "anyOf": [ { "$ref": "#/components/schemas/PinterestPostSpecific" }, { "type": "null" } ], "description": "A pin's own fields." }, "reddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditPostSpecific" }, { "type": "null" } ], "description": "A Reddit post's own fields." }, "rumble": { "anyOf": [ { "$ref": "#/components/schemas/RumblePostSpecific" }, { "type": "null" } ], "description": "A Rumble video's own fields." }, "snapchat": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatPostSpecific" }, { "type": "null" } ], "description": "A Spotlight's own fields." }, "soundcloud": { "anyOf": [ { "$ref": "#/components/schemas/SoundcloudPostSpecific" }, { "type": "null" } ], "description": "A SoundCloud track's own fields." }, "spotify": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyPostSpecific" }, { "type": "null" } ], "description": "A Spotify track's or episode's own fields." }, "telegram": { "anyOf": [ { "$ref": "#/components/schemas/TelegramPostSpecific" }, { "type": "null" } ], "description": "A Telegram post's own fields." }, "threads": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsPostSpecific" }, { "type": "null" } ], "description": "A Threads post's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPostSpecific" }, { "type": "null" } ], "description": "A TikTok post's own fields." }, "truthsocial": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialPostSpecific" }, { "type": "null" } ], "description": "A Truth Social post's own fields." }, "twitch": { "anyOf": [ { "$ref": "#/components/schemas/TwitchPostSpecific" }, { "type": "null" } ], "description": "A Twitch video's or clip's own fields." }, "x": { "anyOf": [ { "$ref": "#/components/schemas/XPostSpecific" }, { "type": "null" } ], "description": "An X (formerly Twitter) post's own fields." }, "youtube": { "anyOf": [ { "$ref": "#/components/schemas/YouTubePostSpecific" }, { "type": "null" } ], "description": "A YouTube video's own fields." } }, "type": "object" }, "PostSummary": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The posting account as the link and the index's text name it (a /@/video/ link's username, the title's display name); its id, avatar_url and is_verified null until the result is filled." }, "id": { "description": "Platform-native post ID: the one in the link where the platform's links name it (an X post's /status/), else null until the result is filled.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/PostMetrics", "description": "Counts as the index's snippet states them (\"1,234 likes, 56 comments\"; rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "published_at": { "description": "When the post went public, as the index's text dates it (often to the day: see approximate_fields); null when it does not.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Caption or body as the index's snippet quotes it (often cut short: see approximate_fields); null when it quotes none.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Cover or poster image URL; null until the result is filled (an index's thumbnails are its own copies).", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Headline, on platforms whose posts have one (a YouTube or Reddit title), as the index's title shows it; null on caption-only platforms (the page's title is the result's title).", "type": [ "string", "null" ] }, "url": { "description": "Canonical post URL (equals the result's url).", "format": "uri", "type": "string" } }, "required": [ "id", "url", "title", "text", "published_at", "author", "thumbnail_url", "metrics" ], "type": "object" }, "Product": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (\"10K+ sold\"), and of Facebook's coarse listing coordinates. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "attributes": { "description": "The product's specifications as name/value pairs, in the platform's order; [] when none.", "items": { "$ref": "#/components/schemas/ProductAttribute" }, "type": "array" }, "availability": { "description": "in_stock: can be bought now; out_of_stock: sold out for now (a product can be restocked); pre_order: ships later; pending: a listing with a sale pending; sold: a listing marked sold. Null when the platform does not say. New values may be added; treat unknown values as null.", "enum": [ "in_stock", "out_of_stock", "pre_order", "pending", "sold", null ], "type": [ "string", "null" ] }, "category": { "description": "The platform's most specific category label (Bicycles, Vitamins & Supplements), as shown; not normalized across platforms.", "type": [ "string", "null" ] }, "category_id": { "description": "The platform's ID of that category (what its category browsing and filters take).", "type": [ "string", "null" ] }, "condition": { "description": "Item condition, coarse: new, used (any grade) or refurbished; null when the platform does not say. The platform's own grade is condition_label. New values may be added; treat unknown values as used.", "enum": [ "new", "used", "refurbished", null ], "type": [ "string", "null" ] }, "condition_label": { "description": "The condition as the platform labels it (Used - Like New, Used - Good, Pre-owned).", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 market the product is offered in; prices, stock and shipping are that market's.", "type": [ "string", "null" ] }, "currency": { "description": "ISO 4217 code of every amount of this product (USD); null when no amount is shown.", "type": [ "string", "null" ] }, "description": { "description": "Description as plain text (paragraphs separated by blank lines); null when it has none or the source does not show it (lists and search results).", "type": [ "string", "null" ] }, "id": { "description": "Platform-native product or listing ID (string).", "type": "string" }, "max_price": { "description": "Highest current variant price, in major units of currency; equal to price when every variant costs the same; null when unknown (a source that shows one price).", "format": "double", "type": [ "number", "null" ] }, "media": { "description": "Product images in the platform's order (main image first), then any product video; [] when none.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "original_price": { "description": "Price before the discount (the struck-through list price), in major units of currency; null when the platform shows no earlier price (not discounted, or not shown).", "format": "double", "type": [ "number", "null" ] }, "platform": { "description": "Platform ID (tiktokshop, facebook, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/ProductPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.): TikTok Shop's brand, rating, variants, stock and units sold; Marketplace's location and listing date. Each null when unknown." }, "price": { "description": "Current price in major units of currency (58.47), discounts applied; for a product whose variants cost different amounts, the lowest (the platform's \"from\" price). Coupons and shipping excluded. 0 = free; null when not shown.", "format": "double", "type": [ "number", "null" ] }, "seller": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The shop or account selling it; null only when the source does not show it." }, "shipping": { "$ref": "#/components/schemas/ProductShipping", "description": "Delivery terms as shown to a buyer in the product's market; each null when not shown." }, "thumbnail_url": { "description": "Main product image URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Product name or listing title, as the seller wrote it.", "type": "string" }, "type": { "description": "product: a catalog product a shop sells in many units, often in variants (TikTok Shop, Instagram and YouTube shopping); listing: a single item a person or business lists for sale (Facebook Marketplace). New values may be added; treat unknown values as product.", "enum": [ "product", "listing" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a list or search result that does not show attributes or variants); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical product page URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "type", "title", "description", "category", "category_id", "seller", "price", "max_price", "original_price", "currency", "availability", "condition", "condition_label", "thumbnail_url", "media", "attributes", "shipping", "country_code", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "ProductAttribute": { "properties": { "name": { "description": "Specification name, as shown (Brand, Material, Condition).", "type": "string" }, "value": { "description": "Its value, as shown.", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "ProductPlatformSpecific": { "properties": { "amazon": { "anyOf": [ { "$ref": "#/components/schemas/AmazonProductSpecific" }, { "type": "null" } ], "description": "An Amazon product's own fields." }, "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookProductSpecific" }, { "type": "null" } ], "description": "A Facebook Marketplace listing's own fields." }, "tiktokshop": { "anyOf": [ { "$ref": "#/components/schemas/TikTokShopProductSpecific" }, { "type": "null" } ], "description": "A TikTok Shop product's own fields." } }, "type": "object" }, "ProductShipping": { "properties": { "fee": { "description": "Standard shipping fee in major units of the product's currency; 0 = free shipping.", "format": "double", "type": [ "number", "null" ] }, "is_offered": { "description": "The seller ships it (false: local pickup only).", "type": [ "boolean", "null" ] } }, "required": [ "is_offered", "fee" ], "type": "object" }, "ProductVariant": { "properties": { "availability": { "description": "Whether this variant can be bought now; null when not shown. New values may be added; treat unknown values as null.", "enum": [ "in_stock", "out_of_stock", "pre_order", null ], "type": [ "string", "null" ] }, "id": { "description": "Platform-native variant (SKU) ID; review.variant_id names it.", "type": "string" }, "image_url": { "description": "Image of this variant (its color swatch or photo). Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "options": { "description": "The option values that make this variant (Color: Black); [] for a product's only variant.", "items": { "$ref": "#/components/schemas/ProductVariantOption" }, "type": "array" }, "original_price": { "description": "This variant's price before the discount; null when no earlier price is shown.", "format": "double", "type": [ "number", "null" ] }, "price": { "description": "Current price of this variant, in major units of the product's currency.", "format": "double", "type": [ "number", "null" ] }, "stock_count": { "description": "Units in stock as the platform reports them (platforms may cap the number they show); null when hidden.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "Variant name as shown, else its options joined (Color: Black, Size: M).", "type": [ "string", "null" ] } }, "required": [ "id", "title", "options", "price", "original_price", "availability", "stock_count", "image_url" ], "type": "object" }, "ProductVariantOption": { "properties": { "name": { "description": "Option name, as shown (Color, Size).", "type": "string" }, "value": { "description": "The variant's value of it (Black, M).", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "Profile": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.follower_count). A list path (external_links) means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "avatar_url": { "description": "Profile picture URL (largest available). Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "banner_url": { "description": "Header or cover image URL.", "format": "uri", "type": [ "string", "null" ] }, "bio": { "description": "Profile bio, channel description or page about text; null when empty or not exposed.", "type": [ "string", "null" ] }, "category": { "description": "Platform category label (e.g. Musician, Media & Entertainment), as shown; not normalized. Often set only for business or creator accounts.", "type": [ "string", "null" ] }, "country_code": { "description": "ISO 3166-1 alpha-2 country the platform states for the account.", "type": [ "string", "null" ] }, "created_at": { "description": "Account creation or join date, RFC 3339 UTC (some platforms give only the day: see approximate_fields).", "format": "date-time", "type": [ "string", "null" ] }, "display_name": { "description": "Display name, channel title or page name; null when empty or not exposed.", "type": [ "string", "null" ] }, "external_links": { "description": "Links in the bio or channel links; [] if none or not exposed.", "items": { "$ref": "#/components/schemas/Link" }, "type": "array" }, "id": { "description": "Platform-native account ID (string; YouTube UC…, Reddit t2_…).", "type": "string" }, "is_private": { "description": "True when the account's posts are not public.", "type": [ "boolean", "null" ] }, "is_verified": { "description": "Platform verification badge; null where the platform has no badge.", "type": [ "boolean", "null" ] }, "location": { "description": "Self-declared location text.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/ProfileMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (tiktok, youtube, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/ProfilePlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "type": { "description": "Coarse account kind, as the platform labels it; unknown when it does not (TikTok labels organizations only). New values may be added; treat unknown values as unknown.", "enum": [ "person", "organization", "community", "unknown" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical profile URL.", "format": "uri", "type": "string" }, "username": { "description": "Handle without the @; null when the account has none.", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "username", "display_name", "url", "type", "bio", "avatar_url", "banner_url", "is_verified", "is_private", "category", "external_links", "location", "country_code", "created_at", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "ProfileMetrics": { "properties": { "follower_count": { "description": "Followers or subscribers.", "format": "int64", "type": [ "integer", "null" ] }, "following_count": { "description": "Accounts this profile follows.", "format": "int64", "type": [ "integer", "null" ] }, "post_count": { "description": "Posts or videos as the platform counts them on the profile (for a private account, posts the caller cannot see).", "format": "int64", "type": [ "integer", "null" ] }, "total_like_count": { "description": "Likes received across all of the profile's posts (not likes given).", "format": "int64", "type": [ "integer", "null" ] }, "total_view_count": { "description": "Lifetime views across all of the profile's posts.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "follower_count", "following_count", "post_count", "total_like_count", "total_view_count" ], "type": "object" }, "ProfilePlatformSpecific": { "properties": { "amazon": { "anyOf": [ { "$ref": "#/components/schemas/AmazonProfileSpecific" }, { "type": "null" } ], "description": "An Amazon seller's or storefront's own fields." }, "applemusic": { "anyOf": [ { "$ref": "#/components/schemas/ApplemusicProfileSpecific" }, { "type": "null" } ], "description": "An Apple Music artist's own fields." }, "bluesky": { "anyOf": [ { "$ref": "#/components/schemas/BlueskyProfileSpecific" }, { "type": "null" } ], "description": "A Bluesky account's own fields." }, "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookProfileSpecific" }, { "type": "null" } ], "description": "A Facebook Page's or person's own fields." }, "google": { "anyOf": [ { "$ref": "#/components/schemas/GoogleProfileSpecific" }, { "type": "null" } ], "description": "A Google advertiser's own fields." }, "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramProfileSpecific" }, { "type": "null" } ], "description": "An Instagram account's own fields." }, "komi": { "anyOf": [ { "$ref": "#/components/schemas/KomiProfileSpecific" }, { "type": "null" } ], "description": "A Komi page's own fields." }, "kwai": { "anyOf": [ { "$ref": "#/components/schemas/KwaiProfileSpecific" }, { "type": "null" } ], "description": "A Kwai account's own fields." }, "linkbio": { "anyOf": [ { "$ref": "#/components/schemas/LinkbioProfileSpecific" }, { "type": "null" } ], "description": "A Lnk.Bio page's own fields." }, "linkedin": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInProfileSpecific" }, { "type": "null" } ], "description": "A LinkedIn Page's or member's own fields." }, "linkme": { "anyOf": [ { "$ref": "#/components/schemas/LinkmeProfileSpecific" }, { "type": "null" } ], "description": "A Linkme page's own fields." }, "linktree": { "anyOf": [ { "$ref": "#/components/schemas/LinktreeProfileSpecific" }, { "type": "null" } ], "description": "A Linktree page's own fields." }, "pillar": { "anyOf": [ { "$ref": "#/components/schemas/PillarProfileSpecific" }, { "type": "null" } ], "description": "A Pillar page's own fields." }, "pinterest": { "anyOf": [ { "$ref": "#/components/schemas/PinterestProfileSpecific" }, { "type": "null" } ], "description": "A Pinterest account's own fields." }, "reddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditProfileSpecific" }, { "type": "null" } ], "description": "A Reddit account's own fields." }, "rumble": { "anyOf": [ { "$ref": "#/components/schemas/RumbleProfileSpecific" }, { "type": "null" } ], "description": "A Rumble channel's or user's own fields." }, "snapchat": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatProfileSpecific" }, { "type": "null" } ], "description": "A Snapchat account's own fields." }, "soundcloud": { "anyOf": [ { "$ref": "#/components/schemas/SoundcloudProfileSpecific" }, { "type": "null" } ], "description": "A SoundCloud account's own fields." }, "spotify": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyProfileSpecific" }, { "type": "null" } ], "description": "A Spotify artist's own fields." }, "telegram": { "anyOf": [ { "$ref": "#/components/schemas/TelegramProfileSpecific" }, { "type": "null" } ], "description": "A Telegram channel's, group's, user's or bot's own fields." }, "threads": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsProfileSpecific" }, { "type": "null" } ], "description": "A Threads account's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokProfileSpecific" }, { "type": "null" } ], "description": "A TikTok account's own fields." }, "truthsocial": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialProfileSpecific" }, { "type": "null" } ], "description": "A Truth Social account's own fields." }, "twitch": { "anyOf": [ { "$ref": "#/components/schemas/TwitchProfileSpecific" }, { "type": "null" } ], "description": "A Twitch channel's own fields." }, "x": { "anyOf": [ { "$ref": "#/components/schemas/XProfileSpecific" }, { "type": "null" } ], "description": "An X (formerly Twitter) account's own fields." }, "youtube": { "anyOf": [ { "$ref": "#/components/schemas/YouTubeProfileSpecific" }, { "type": "null" } ], "description": "A YouTube channel's own fields." } }, "type": "object" }, "ProfileRef": { "properties": { "avatar_url": { "description": "Profile picture URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "display_name": { "description": "Display name shown on the profile.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native account ID; null when only the handle is known.", "type": [ "string", "null" ] }, "is_verified": { "description": "Platform verification badge; null where the platform has no badge.", "type": [ "boolean", "null" ] }, "url": { "description": "Canonical profile URL.", "format": "uri", "type": [ "string", "null" ] }, "username": { "description": "Handle without the @; null when the account has none.", "type": [ "string", "null" ] } }, "required": [ "id", "username", "display_name", "url", "avatar_url", "is_verified" ], "type": "object" }, "ProfileSummary": { "properties": { "avatar_url": { "description": "Profile picture URL; null until the result is filled (an index's thumbnails are its own copies). Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "bio": { "description": "Profile bio as the index's snippet quotes it (often cut short: see approximate_fields); null when it quotes none.", "type": [ "string", "null" ] }, "display_name": { "description": "Display name, as the index's title shows it; null when it shows none.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native account ID; null until the result is filled (the index shows only the handle).", "type": [ "string", "null" ] }, "is_verified": { "description": "Platform verification badge; null until the result is filled, or where the platform has no badge.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/ProfileMetrics", "description": "Counts as the index's snippet states them (rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "url": { "description": "Canonical profile URL (equals the result's url).", "format": "uri", "type": "string" }, "username": { "description": "Handle without the @, as the matched link names it; null when the link names the account only by its number.", "type": [ "string", "null" ] } }, "required": [ "id", "username", "display_name", "url", "bio", "avatar_url", "is_verified", "metrics" ], "type": "object" }, "Range": { "properties": { "lower_bound": { "description": "Inclusive lower bound.", "format": "int64", "type": "integer" }, "upper_bound": { "description": "Inclusive upper bound; null when open-ended (e.g. \">1M\"). Equal to lower_bound when exact.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "lower_bound", "upper_bound" ], "type": "object" }, "RatingDistribution": { "properties": { "five_star_count": { "description": "Reviews rating 5 stars.", "format": "int64", "type": [ "integer", "null" ] }, "four_star_count": { "description": "Reviews rating 4 stars.", "format": "int64", "type": [ "integer", "null" ] }, "one_star_count": { "description": "Reviews rating 1 star.", "format": "int64", "type": [ "integer", "null" ] }, "three_star_count": { "description": "Reviews rating 3 stars.", "format": "int64", "type": [ "integer", "null" ] }, "two_star_count": { "description": "Reviews rating 2 stars.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "one_star_count", "two_star_count", "three_star_count", "four_star_count", "five_star_count" ], "type": "object" }, "RedditCommentPost": { "properties": { "comment_count": { "description": "Comments on the post.", "format": "int64", "type": [ "integer", "null" ] }, "is_nsfw": { "description": "The post is marked NSFW (18+).", "type": [ "boolean", "null" ] }, "is_spoiler": { "description": "The post is marked as a spoiler.", "type": [ "boolean", "null" ] }, "published_at": { "description": "When the post was submitted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "score": { "description": "The post's net score as Reddit shows it (floored at 0 on display).", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The post's title.", "type": [ "string", "null" ] }, "url": { "description": "The post's permalink.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "title", "url", "score", "comment_count", "published_at", "is_nsfw", "is_spoiler" ], "type": "object" }, "RedditCommentSpecific": { "properties": { "award_count": { "description": "Awards the comment received.", "format": "int64", "type": [ "integer", "null" ] }, "depth": { "description": "How deep in the post's thread the comment is: 0 for a comment on the post, 1 for a reply to one, and so on.", "format": "int64", "type": [ "integer", "null" ] }, "distinguished": { "description": "The role the author spoke in, when they marked the comment with it: moderator or admin; null for an ordinary comment.", "type": [ "string", "null" ] }, "is_collapsed": { "description": "Reddit shows the comment collapsed (a low score, a moderator's or crowd-control setting, or a subreddit's rule).", "type": [ "boolean", "null" ] }, "is_deleted": { "description": "The comment's body was deleted by its author or removed by a moderator or Reddit; text is then empty. Reddit keeps such a comment in the thread when it has replies.", "type": [ "boolean", "null" ] }, "more_replies_count": { "description": "Replies under this comment (with their own replies) that the page leaves out, as Reddit counts them in its \"N more replies\" link: request the comment's url to page through them. 0 when every reply Reddit has is included.", "format": "int64", "type": [ "integer", "null" ] }, "post": { "anyOf": [ { "$ref": "#/components/schemas/RedditCommentPost" }, { "type": "null" } ], "description": "The post the comment is on, as Reddit shows it beside the comment (search results); null where the endpoint does not show it." }, "reply_to_author": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The author of the comment this one replies to, where the list names them (a user's comments: Reddit's \"replied to u/…\"); null where Reddit does not name them (a comment on the post, a deleted parent account) and where parent_id places the comment in its thread." }, "score": { "description": "Net score as Reddit shows it: upvotes minus downvotes, fuzzed by Reddit; negative for a comment most votes are against. Null when Reddit hides it (a subreddit that hides recent comments' scores, a deleted comment).", "format": "int64", "type": [ "integer", "null" ] }, "subreddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditSubredditRef" }, { "type": "null" } ], "description": "The subreddit of the post the comment is on; for a post on a user's profile, the profile's own subreddit (u_)." } }, "required": [ "subreddit", "score", "depth", "award_count", "distinguished", "is_collapsed", "is_deleted", "more_replies_count", "reply_to_author", "post" ], "type": "object" }, "RedditCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 200), Reddit's Controversial order of comments (most evenly divided votes first), each followed by the replies Reddit shows with sort=controversial, Reddit's New order of comments (newest first), each followed by the replies Reddit shows with sort=newest, Reddit's Old order of comments (oldest first), each followed by the replies Reddit shows with sort=oldest, Reddit's Top order of comments (highest score first), each followed by the replies Reddit shows with sort=popular, Reddit's Q&A order (the comments the post's author answered first), each followed by the replies Reddit shows with sort=qa, Reddit's own order for the post (Best, or the order its moderators suggest), each comment followed by the replies Reddit shows with sort=relevance. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditCommunitySpecific": { "properties": { "is_quarantined": { "description": "True when Reddit has quarantined it (shown only after a warning).", "type": [ "boolean", "null" ] }, "member_nickname": { "description": "What the subreddit calls its members (gophers on r/golang); null when it has no nickname.", "type": [ "string", "null" ] }, "weekly_contribution_count": { "description": "Posts and comments in the last week, as the subreddit's page shows them.", "format": "int64", "type": [ "integer", "null" ] }, "weekly_visitor_count": { "description": "Unique visitors in the last week, as the subreddit's page shows them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "weekly_visitor_count", "weekly_contribution_count", "member_nickname", "is_quarantined" ], "type": "object" }, "RedditEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement", "description": "In Reddit's words: `metrics.comment_to_like_ratio` is comment-to-upvote ratio, `metrics.likes_per_post` is upvotes (score) per post, `posts[].post.metrics.like_count` is upvotes (score)." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RedditPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post", "description": "In Reddit's words: `metrics.like_count` is upvotes (score)." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RedditPostSpecific": { "properties": { "award_count": { "description": "Awards the post received.", "format": "int64", "type": [ "integer", "null" ] }, "crosspost_of": { "description": "The post this one is a crosspost of; null when it is not a crosspost.", "format": "uri", "type": [ "string", "null" ] }, "domain": { "description": "The linked site's domain (youtu.be, i.redd.it, v.redd.it), or self. for a text post.", "type": [ "string", "null" ] }, "flair": { "description": "The post's flair text; null when it has none.", "type": [ "string", "null" ] }, "is_archived": { "description": "Archived: too old for new votes or comments.", "type": [ "boolean", "null" ] }, "is_locked": { "description": "Locked by the moderators: no new comments.", "type": [ "boolean", "null" ] }, "is_spoiler": { "description": "Marked as a spoiler.", "type": [ "boolean", "null" ] }, "link_url": { "description": "The page a link post points to; null for other posts.", "format": "uri", "type": [ "string", "null" ] }, "score": { "description": "Net score as Reddit shows it: upvotes minus downvotes, fuzzed by Reddit. Reddit floors a post's shown score at 0, so this is null when it shows 0 for a post most votes are against (upvote_ratio below 0.5): its true score is negative and unknown.", "format": "int64", "type": [ "integer", "null" ] }, "subreddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditSubredditRef" }, { "type": "null" } ], "description": "The subreddit the post was submitted to; for a post on a user's profile, the profile's own subreddit (u_)." }, "upvote_ratio": { "description": "Share of votes that are upvotes, from 0 to 1.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "subreddit", "score", "upvote_ratio", "award_count", "flair", "domain", "link_url", "is_spoiler", "is_locked", "is_archived", "crosspost_of" ], "type": "object" }, "RedditPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), Reddit's Controversial order (most evenly divided votes first), of all time or of the time filter that covers since with sort=controversial, newest first with sort=newest, Reddit's Top order (highest score first), of all time or of the time filter that covers since with sort=popular, Reddit's Hot order (recent posts ranked by their votes) with sort=relevance. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RedditProfileSpecific": { "properties": { "comment_karma": { "description": "Karma from the account's comments.", "format": "int64", "type": [ "integer", "null" ] }, "contribution_count": { "description": "Posts and comments the account has made, as its profile counts them (Reddit updates the count daily).", "format": "int64", "type": [ "integer", "null" ] }, "is_admin": { "description": "True for a Reddit employee's account (the Reddit Admin badge).", "type": [ "boolean", "null" ] }, "is_nsfw": { "description": "True when the profile is marked NSFW (18+): Reddit shows its posts to logged-out visitors only behind an age prompt.", "type": [ "boolean", "null" ] }, "is_premium": { "description": "True when the account has Reddit Premium (the badge beside its name).", "type": [ "boolean", "null" ] }, "karma": { "description": "Total karma, as the profile shows it: post karma plus comment karma. Reddit's own score of the upvotes the account's posts and comments received, fuzzed and not a count of votes.", "format": "int64", "type": [ "integer", "null" ] }, "moderated_subreddits": { "description": "Subreddits the account moderates, as its profile lists them; Reddit lists the first few only (the list is then in approximate_fields). [] when it moderates none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/RedditSubredditRef" }, "type": "array" }, "post_karma": { "description": "Karma from the account's posts.", "format": "int64", "type": [ "integer", "null" ] }, "trophies": { "description": "The account's Trophy Case, in Reddit's order; [] when it has none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/RedditTrophy" }, "type": "array" } }, "required": [ "karma", "post_karma", "comment_karma", "contribution_count", "is_admin", "is_premium", "is_nsfw", "moderated_subreddits", "trophies" ], "type": "object" }, "RedditProfile_commentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), Reddit's Controversial order (most evenly divided votes first), of all time or of the time filter that covers since with sort=controversial, newest first with sort=newest, Reddit's Top order (highest score first), of all time or of the time filter that covers since with sort=popular, Reddit's Hot order (recent comments ranked by their votes) with sort=relevance. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditSearch_commentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), newest first with sort=newest, Reddit's Top: highest score first with sort=popular, Reddit's search ranking (best match) with sort=relevance. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 7), Reddit's Comments order (most comments first) with sort=most_comments, newest first with sort=newest, Reddit's Top order (highest score first) with sort=popular, Reddit's relevance order (its search ranking) with sort=relevance. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 7), Reddit's relevance order.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditSearch_subredditsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), Reddit's relevance order. In Reddit's words: `metrics.member_count` is subscribers.", "items": { "$ref": "#/components/schemas/Community" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditSubredditRef": { "properties": { "id": { "description": "Reddit's subreddit ID (t5_…).", "type": [ "string", "null" ] }, "name": { "description": "The subreddit's name without r/.", "type": [ "string", "null" ] }, "url": { "description": "The subreddit's URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "name", "url" ], "type": "object" }, "RedditSubredditResponse": { "properties": { "data": { "$ref": "#/components/schemas/Community", "description": "In Reddit's words: `metrics.member_count` is subscribers." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RedditSubreddit_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), Reddit's Best order (its default ranking of a subreddit's posts) with sort=best, Reddit's Controversial order (most evenly divided votes first, within the time filter since picks) with sort=controversial, Reddit's Hot order (recent posts gaining votes fast first) with sort=hot, newest first with sort=newest, Reddit's Top order (highest score first, within the time filter since picks) with sort=popular, Reddit's Rising order (new posts gaining votes fastest first) with sort=rising. In Reddit's words: `metrics.like_count` is upvotes (score).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RedditTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RedditTranscriptSpecific": { "properties": { "caption_url": { "description": "The WebVTT file of Reddit's caption track used (public, unsigned); null for speech-to-text.", "format": "uri", "type": [ "string", "null" ] }, "video_id": { "description": "The video's ID on Reddit's video host (v.redd.it/); null when unknown.", "type": [ "string", "null" ] } }, "required": [ "video_id", "caption_url" ], "type": "object" }, "RedditTrophy": { "properties": { "description": { "description": "What it was awarded for, as Reddit describes it; null when it shows none.", "type": [ "string", "null" ] }, "granted_at": { "description": "The day it was awarded, RFC 3339 UTC at midnight (Reddit shows the day only), for the trophies Reddit dates; null otherwise.", "format": "date-time", "type": [ "string", "null" ] }, "image_url": { "description": "The trophy's image.", "format": "uri", "type": [ "string", "null" ] }, "name": { "description": "The trophy's name (Verified Email, 10-Year Club, Best Comment).", "type": [ "string", "null" ] }, "url": { "description": "What it links to (the awarded comment or post, an event page); null when it links nowhere.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "name", "description", "granted_at", "image_url", "url" ], "type": "object" }, "ResponseMeta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Credits charged for this request (0 for errors and cache hits).", "format": "int64", "type": "integer" }, "credits_remaining": { "description": "Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.", "format": "int64", "type": [ "integer", "null" ] }, "fetched_at": { "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).", "format": "date-time", "type": "string" }, "input": { "anyOf": [ { "$ref": "#/components/schemas/InputRef" }, { "type": "null" } ], "description": "What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches." }, "is_cached": { "description": "True when served from the cache (free); see max_age.", "type": "boolean" }, "latency_ms": { "description": "Time SocialTap spent on the request, in milliseconds.", "format": "int64", "type": "integer" }, "platform": { "description": "Platform ID of the endpoint (youtube, tiktok, …).", "examples": [ "youtube" ], "type": "string" }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "source": { "description": "Which upstream strategy produced the data.", "examples": [ "captions" ], "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request: a deprecated endpoint, partial data, items a list's walk leaves out. [] when none.", "items": { "$ref": "#/components/schemas/Warning" }, "type": "array" } }, "required": [ "request_id", "platform", "source", "is_cached", "credits_charged", "latency_ms", "fetched_at", "input", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "Review": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (a date-only time). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "author": { "$ref": "#/components/schemas/ProfileRef", "description": "The reviewing account, as the platform shows it (some platforms mask the name, e.g. G**a, and show no handle); every field null for an anonymous review." }, "country_code": { "description": "ISO 3166-1 alpha-2 country the review was written in, as the platform states it.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native review ID (string).", "type": "string" }, "is_incentivized": { "description": "The platform marks the review as written in exchange for a free product or reward.", "type": [ "boolean", "null" ] }, "is_verified_purchase": { "description": "The platform marks the reviewer as having bought the product through it.", "type": [ "boolean", "null" ] }, "language": { "description": "BCP-47 language of text, when the platform states it.", "type": [ "string", "null" ] }, "media": { "description": "Photos and videos attached to the review; [] when none.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/ReviewMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (tiktokshop, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/ReviewPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "product_id": { "description": "ID of the product reviewed (equals product.id); null only for a review of something other than a product.", "type": [ "string", "null" ] }, "published_at": { "description": "When the review was posted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "rating": { "description": "Star rating, 1 to 5; null when the review gives none.", "format": "int64", "type": [ "integer", "null" ] }, "text": { "description": "Review body as plain text; null for a rating without text.", "type": [ "string", "null" ] }, "title": { "description": "The review's headline; null when it has none.", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see a review's photos); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Permalink, when the platform has one (TikTok Shop reviews have none).", "format": "uri", "type": [ "string", "null" ] }, "variant_id": { "description": "ID of the variant bought: one of the product's variants (TikTok Shop: product.platform_specific.tiktokshop.variants[].id).", "type": [ "string", "null" ] }, "variant_title": { "description": "The variant bought, as the platform labels it (Color: Black).", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "product_id", "url", "rating", "title", "text", "language", "author", "variant_id", "variant_title", "media", "country_code", "is_verified_purchase", "is_incentivized", "published_at", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "ReviewMetrics": { "properties": { "helpful_count": { "description": "Readers who marked the review helpful; null when the platform shows no such count.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "helpful_count" ], "type": "object" }, "ReviewPlatformSpecific": { "type": "object" }, "RumbleCaptionTrack": { "properties": { "is_auto_generated": { "description": "Generated by Rumble's speech recognition.", "type": [ "boolean", "null" ] }, "label": { "description": "Rumble's label (\"English (auto)\").", "type": [ "string", "null" ] }, "language": { "description": "Language code (en, es, …).", "type": [ "string", "null" ] }, "url": { "description": "WebVTT file URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "language", "label", "url", "is_auto_generated" ], "type": "object" }, "RumbleCommentSpecific": { "properties": { "author_badges": { "description": "The badges Rumble shows beside the commenter's name, by their label as Rumble writes it (seen: Verified, Admin, Moderator, Supporter, Supporter+, Supporter++, Sub, Locals Supporter; new labels may appear). [] when none.", "items": { "type": "string" }, "type": "array" }, "dislike_count": { "description": "Thumbs-down votes on the comment. Exact below 1,000; from 1,000 Rumble shows a label such as \"1.31K\", taken to be cut to three significant digits as Rumble's other counts are (not checked against an exact count), and listed in approximate_fields.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "dislike_count", "author_badges" ], "type": "object" }, "RumbleCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 500), newest first with sort=newest, Rumble's Sort by likes order of comments, each followed by its replies with sort=popular.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RumbleEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RumbleFile": { "properties": { "bitrate_kbps": { "description": "Bitrate in kbit/s.", "format": "int64", "type": [ "integer", "null" ] }, "format": { "description": "mp4 or webm file, hls playlist (all qualities), tar (one HLS quality packed in one file; url is its playlist) or aac audio. New values may be added.", "enum": [ "mp4", "webm", "hls", "tar", "aac", null ], "type": [ "string", "null" ] }, "height": { "description": "Height in pixels; null for audio and playlists.", "format": "int64", "type": [ "integer", "null" ] }, "kind": { "description": "video (picture and sound), audio (sound only) or preview (the seek bar's low-resolution video, no sound). New values may be added.", "enum": [ "video", "audio", "preview", null ], "type": [ "string", "null" ] }, "size_bytes": { "description": "File size in bytes; null when Rumble does not state it.", "format": "int64", "type": [ "integer", "null" ] }, "url": { "description": "File or playlist URL.", "format": "uri", "type": [ "string", "null" ] }, "width": { "description": "Width in pixels; null for audio and playlists.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "kind", "format", "url", "width", "height", "bitrate_kbps", "size_bytes" ], "type": "object" }, "RumblePostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RumblePostSpecific": { "properties": { "author_follower_count": { "description": "The channel's or user's follower count. Exact in Rumble's JSON (shorts, lists); a video's page cuts it to three significant digits (in approximate_fields).", "format": "int64", "type": [ "integer", "null" ] }, "caption_tracks": { "description": "Caption tracks (WebVTT); [] when none.", "items": { "$ref": "#/components/schemas/RumbleCaptionTrack" }, "type": "array" }, "category": { "description": "Rumble's primary category (News, Podcasts, …).", "type": [ "string", "null" ] }, "concurrent_viewer_count": { "description": "Viewers watching a live stream now; null when not live.", "format": "int64", "type": [ "integer", "null" ] }, "dislike_count": { "description": "Thumbs-down votes. Exact in Rumble's JSON (shorts, grid lists); a video's page and the older HTML cards cut it to three significant digits from 1,000 (in approximate_fields).", "format": "int64", "type": [ "integer", "null" ] }, "embed_id": { "description": "The video's embed player ID (rumble.com/embed//): its own namespace, not id.", "type": [ "string", "null" ] }, "embed_url": { "description": "The embeddable player URL.", "format": "uri", "type": [ "string", "null" ] }, "files": { "description": "Every file and stream Rumble's player offers, largest video first; [] when none.", "items": { "$ref": "#/components/schemas/RumbleFile" }, "type": "array" }, "is_age_restricted": { "description": "Viewers must confirm their age to watch; null when the source does not show it.", "type": [ "boolean", "null" ] }, "is_live_now": { "description": "A live stream on air now.", "type": [ "boolean", "null" ] }, "keywords": { "description": "The uploader's tags; [] when none.", "items": { "type": "string" }, "type": "array" }, "live_started_at": { "description": "When a live stream went on air; null if never live.", "format": "date-time", "type": [ "string", "null" ] }, "numeric_id": { "description": "Rumble's numeric video ID, which its own services use.", "type": [ "string", "null" ] }, "scheduled_start_at": { "description": "When a scheduled live stream is due to start; null otherwise.", "format": "date-time", "type": [ "string", "null" ] }, "secondary_category": { "description": "Rumble's secondary category; null when none.", "type": [ "string", "null" ] } }, "required": [ "embed_id", "embed_url", "numeric_id", "dislike_count", "category", "secondary_category", "keywords", "caption_tracks", "files", "is_live_now", "live_started_at", "scheduled_start_at", "concurrent_viewer_count", "is_age_restricted", "author_follower_count" ], "type": "object" }, "RumblePostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), Rumble's upload order (newest uploads first, not strictly by published_at) with sort=newest, Rumble's View count order (most viewed first) with sort=popular.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RumbleProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RumbleProfileSpecific": { "properties": { "account_type": { "description": "channel for a Rumble channel (rumble.com/c/), user for a Rumble user (rumble.com/user/: the account that uploads, which can own channels). Null when unknown. New values may be added; treat unknown values as unknown.", "enum": [ "channel", "user", null ], "type": [ "string", "null" ] }, "numeric_id": { "description": "Rumble's numeric ID of the channel or the user, in decimal (the channel's is the number in its rumble.com/c/c- link). Channels and users are numbered separately, so the same number can name a channel and a user: id is the unambiguous reference. Null when unknown.", "type": [ "string", "null" ] }, "user_id": { "description": "The id of the Rumble user that owns the channel (_u…, the id this endpoint answers for that user); for a user, its own id. Channels of one owner share it. Null when the page does not show it.", "type": [ "string", "null" ] } }, "required": [ "account_type", "numeric_id", "user_id" ], "type": "object" }, "RumbleSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 36), newest first with sort=newest, Rumble's View count order (most viewed first) with sort=popular, Rumble's relevance order with sort=relevance.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "RumbleTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "RumbleTranscriptSpecific": { "properties": { "caption_tracks": { "description": "Every caption track Rumble offers for the video (WebVTT); [] when none.", "items": { "$ref": "#/components/schemas/RumbleCaptionTrack" }, "type": "array" }, "caption_url": { "description": "The WebVTT file of the caption track used; null for speech-to-text.", "format": "uri", "type": [ "string", "null" ] }, "track_label": { "description": "Rumble's label of the caption track used (\"English (auto)\"); null for speech-to-text.", "type": [ "string", "null" ] } }, "required": [ "track_label", "caption_url", "caption_tracks" ], "type": "object" }, "ScheduledEvent": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (\"7.3K interested\": platform_specific.facebook.metrics.interested_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "categories": { "description": "Categories the platform files it under, as shown (not normalized), the main one first; [] when none.", "items": { "type": "string" }, "type": "array" }, "community_id": { "description": "ID of the community it belongs to (the Facebook group it was created in; community.id); null when none.", "type": [ "string", "null" ] }, "cover_url": { "description": "The event's cover image (a video cover's poster frame); null when it has none. Platform CDN URLs can expire within days.", "format": "uri", "type": [ "string", "null" ] }, "description": { "description": "Its description as plain text; null when it has none.", "type": [ "string", "null" ] }, "end_at": { "description": "When it ends, RFC 3339 UTC; null when its hosts set no end or the platform does not show it.", "format": "date-time", "type": [ "string", "null" ] }, "hosts": { "description": "The accounts hosting it (pages and people), the main organizer first; [] when none are shown (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "id": { "description": "Platform-native event ID (string; Facebook's numeric event ID).", "type": "string" }, "is_online": { "description": "Held online (a stream or video call) rather than at a venue.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/EventMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "name": { "description": "The event's name as its page shows it.", "type": "string" }, "parent_id": { "description": "ID of the event series this date belongs to (a recurring event's parent event); null for a single event or the series itself.", "type": [ "string", "null" ] }, "place": { "anyOf": [ { "$ref": "#/components/schemas/PlaceRef" }, { "type": "null" } ], "description": "Where it is held; null for an online event with no venue or when not shown." }, "platform": { "description": "Platform ID (facebook, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/EventPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "start_at": { "description": "When it starts, RFC 3339 UTC; null only when the platform shows no start.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "At fetch time: scheduled (not started), ongoing (started, not over), ended (over), canceled (called off by its hosts); unknown when the source that answered does not show it (a fallback whose results hold only a name and a picture). New values may be added; treat any other value as unknown.", "enum": [ "scheduled", "ongoing", "ended", "canceled", "unknown" ], "type": "string" }, "ticket_url": { "description": "Where to buy tickets or register, as the platform links it; null when none is linked.", "format": "uri", "type": [ "string", "null" ] }, "time_zone": { "description": "The event's IANA time zone (America/New_York) when the platform states one; null otherwise (utc_offset_minutes still gives its local time).", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical event page URL (https://www.facebook.com/events//).", "format": "uri", "type": "string" }, "utc_offset_minutes": { "description": "The event's offset from UTC at its start, in minutes (-240 for 5:00 PM EDT): its local start time is start_at plus this offset; null when unknown.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "platform", "id", "url", "name", "description", "status", "start_at", "end_at", "time_zone", "utc_offset_minutes", "is_online", "place", "hosts", "cover_url", "categories", "ticket_url", "parent_id", "community_id", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "Segment": { "properties": { "end_ms": { "description": "End time in milliseconds from the beginning of the media.", "format": "int64", "type": "integer" }, "start_ms": { "description": "Start time in milliseconds from the beginning of the media.", "format": "int64", "type": "integer" }, "text": { "description": "Cue text, whitespace-normalized.", "type": "string" } }, "required": [ "start_ms", "end_ms", "text" ], "type": "object" }, "SnapchatCommentSpecific": { "properties": { "author_user_id": { "description": "The commenter's user ID, the same as platform_specific.snapchat.user_id of their snapchat.profile. It stays when they replace their public profile, which changes author.id; null when Snapchat names no account for the comment.", "type": [ "string", "null" ] } }, "required": [ "author_user_id" ], "type": "object" }, "SnapchatCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 26), Snapchat's own ranking of the Spotlight's comments; a comment's replies oldest first.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SnapchatHighlight": { "properties": { "id": { "description": "The saved Story's ID.", "type": "string" }, "snaps": { "description": "Its Snaps, in the order it plays them.", "items": { "$ref": "#/components/schemas/SnapchatSnap" }, "type": "array" }, "thumbnail_url": { "description": "Its cover image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The title the account gave it; null when none.", "type": [ "string", "null" ] }, "url": { "description": "The saved Story's link.", "format": "uri", "type": "string" } }, "required": [ "id", "title", "thumbnail_url", "url", "snaps" ], "type": "object" }, "SnapchatLensCredit": { "properties": { "id": { "description": "The Lens's ID.", "type": [ "string", "null" ] }, "name": { "description": "The Lens's name.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "The Lens's icon.", "format": "uri", "type": [ "string", "null" ] }, "url": { "description": "The Lens's page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "thumbnail_url" ], "type": "object" }, "SnapchatPlaceCredit": { "properties": { "category": { "description": "Its category as Snapchat words it (Bars, Amusement Park).", "type": [ "string", "null" ] }, "id": { "description": "The place's ID.", "type": [ "string", "null" ] }, "name": { "description": "The place's name.", "type": [ "string", "null" ] }, "url": { "description": "The place's page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "name", "category", "url" ], "type": "object" }, "SnapchatPostSpecific": { "properties": { "embedded_text": { "description": "Text written on the Snap itself, where the poster's caption (text) is separate; null when none.", "type": [ "string", "null" ] }, "generated_description": { "description": "A description Snapchat's own language model wrote for search, not the poster: it can be wrong about what the Snap shows. Null when Snapchat has none.", "type": [ "string", "null" ] }, "generated_title": { "description": "A title Snapchat's own language model wrote for search, not the poster: it can be wrong about what the Snap shows. Null when Snapchat has none.", "type": [ "string", "null" ] }, "is_attributed": { "description": "Snapchat names the account that posted it. False: it shows no account, so author holds only the label Snapchat shows instead.", "type": [ "boolean", "null" ] }, "keywords": { "description": "Search keywords Snapchat derived from the Snap, not the poster's hashtags; [] if none.", "items": { "type": "string" }, "type": "array" }, "lens": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatLensCredit" }, { "type": "null" } ], "description": "The Lens it was made with; null when it credits none." }, "place": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatPlaceCredit" }, { "type": "null" } ], "description": "The place it was tagged at; null when it names none." }, "recommend_count": { "description": "How many people recommended it.", "format": "int64", "type": [ "integer", "null" ] }, "sound": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatSound" }, { "type": "null" } ], "description": "The sound it uses; null when it credits none." }, "transcript": { "description": "What is said in the Snap, as Snapchat transcribed it, as plain text; null when it holds no speech or Snapchat has no transcript.", "type": [ "string", "null" ] }, "transcript_url": { "description": "Snapchat's timed transcript of the Snap, a WebVTT file; null when it has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "recommend_count", "is_attributed", "embedded_text", "generated_title", "generated_description", "keywords", "transcript", "transcript_url", "sound", "lens", "place" ], "type": "object" }, "SnapchatProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Snapchat's words: `metrics.follower_count` is subscribers." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SnapchatProfileSpecific": { "properties": { "category_id": { "description": "The category the account chose, as the platform identifies it (public-profile-category-v3-people).", "type": [ "string", "null" ] }, "highlights": { "description": "The Stories the account saved to its profile, with their Snaps: the first page of them, as the profile page holds it; [] if none.", "items": { "$ref": "#/components/schemas/SnapchatHighlight" }, "type": "array" }, "is_highlights_shown": { "description": "True when the profile shows saved Stories (story highlights), false when it shows none; null when unknown (no public profile).", "type": [ "boolean", "null" ] }, "is_spotlights_public": { "description": "The page says the account has public Spotlights.", "type": [ "boolean", "null" ] }, "is_story_live": { "description": "True when the Story the profile page plays holds a Snap under 24 hours old, false when it plays none or only older ones; null when unknown (no public profile, or Snaps that state no time).", "type": [ "boolean", "null" ] }, "last_updated_at": { "description": "When the public profile last changed, as its page says, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "related_accounts": { "description": "Accounts the page recommends beside this one; [] if none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "snapcode_url": { "description": "Image of the account's Snapcode, the scannable code that adds it.", "format": "uri", "type": [ "string", "null" ] }, "spotlights": { "description": "The Spotlights the profile page shows, as it orders them: a sample, not the whole list; [] if none.", "items": { "$ref": "#/components/schemas/SnapchatSpotlightSummary" }, "type": "array" }, "story": { "anyOf": [ { "$ref": "#/components/schemas/SnapchatStory" }, { "type": "null" } ], "description": "The Story the profile page plays, its recent public Snaps, which can be days old (see is_story_live); null when it plays none." }, "subcategory_id": { "description": "The subcategory the account chose, as the platform identifies it (public-profile-subcategory-v3-creator).", "type": [ "string", "null" ] }, "user_id": { "description": "The account's user ID, in the form comments name their authors with no public profile; id is its public profile's.", "type": [ "string", "null" ] } }, "required": [ "user_id", "snapcode_url", "category_id", "subcategory_id", "is_story_live", "is_spotlights_public", "is_highlights_shown", "last_updated_at", "story", "highlights", "spotlights", "related_accounts" ], "type": "object" }, "SnapchatSnap": { "properties": { "id": { "description": "The Snap's ID; null on a saved Story's Snaps, where the platform names none.", "type": [ "string", "null" ] }, "media_url": { "description": "The Snap's image or video file.", "format": "uri", "type": [ "string", "null" ] }, "posted_at": { "description": "When it was posted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "preview_url": { "description": "A preview image of the Snap.", "format": "uri", "type": [ "string", "null" ] }, "type": { "description": "image or video; null when the platform names another kind. New values may be added.", "enum": [ "image", "video", null ], "type": [ "string", "null" ] } }, "required": [ "id", "type", "media_url", "preview_url", "posted_at" ], "type": "object" }, "SnapchatSound": { "properties": { "id": { "description": "Snapchat's ID of the sound.", "type": [ "string", "null" ] }, "subtitle": { "description": "Who or what the sound credits: the artist of a track, the username of the account that made an original sound, or the track an original sound contains. Null when it names no account.", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "The sound's cover image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The sound's title (Original Sound for a poster's own).", "type": [ "string", "null" ] } }, "required": [ "id", "title", "subtitle", "thumbnail_url" ], "type": "object" }, "SnapchatSpotlightMetrics": { "properties": { "comment_count": { "description": "Comments.", "format": "int64", "type": [ "integer", "null" ] }, "like_count": { "description": "Likes (boosts, in the platform's data).", "format": "int64", "type": [ "integer", "null" ] }, "recommend_count": { "description": "How many people recommended it.", "format": "int64", "type": [ "integer", "null" ] }, "share_count": { "description": "Shares.", "format": "int64", "type": [ "integer", "null" ] }, "view_count": { "description": "Views.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "view_count", "like_count", "comment_count", "share_count", "recommend_count" ], "type": "object" }, "SnapchatSpotlightResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SnapchatSpotlightSummary": { "properties": { "caption": { "description": "The caption its poster wrote; null when none.", "type": [ "string", "null" ] }, "duration_ms": { "description": "Its length in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "height": { "description": "Height in pixels.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "The Spotlight's ID: what the Spotlight and comments endpoints take.", "type": "string" }, "media_url": { "description": "Its video or image file.", "format": "uri", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/SnapchatSpotlightMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "published_at": { "description": "When it was posted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "thumbnail_url": { "description": "Its cover image.", "format": "uri", "type": [ "string", "null" ] }, "type": { "description": "image or video; null when the platform names another kind. New values may be added.", "enum": [ "image", "video", null ], "type": [ "string", "null" ] }, "url": { "description": "The Spotlight's link.", "format": "uri", "type": "string" }, "width": { "description": "Width in pixels.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "url", "caption", "thumbnail_url", "type", "media_url", "published_at", "duration_ms", "width", "height", "metrics" ], "type": "object" }, "SnapchatStory": { "properties": { "snaps": { "description": "The Story's Snaps, in the order it plays them.", "items": { "$ref": "#/components/schemas/SnapchatSnap" }, "type": "array" }, "thumbnail_url": { "description": "The Story's cover image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The Story's title; null when it has none.", "type": [ "string", "null" ] } }, "required": [ "title", "thumbnail_url", "snaps" ], "type": "object" }, "Sound": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.post_count from \"80K reels\"). A list path means the list may be incomplete. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "author_name": { "description": "Who the platform credits for the sound: a track's artist(s) as one display string, or the creator's name for an original sound.", "type": [ "string", "null" ] }, "authors": { "description": "The platform accounts behind author_name (a track's artists, or the creator of an original sound), in the platform's order; [] when none is linked.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "cover_url": { "description": "Cover art or thumbnail image URL. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "duration_ms": { "description": "Length of the audio the platform serves for the sound, in milliseconds (TikTok: the usable clip, often shorter than the full song).", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Platform-native sound ID (string), the one in its page's URL; equals the ID a post's sound reference carries.", "type": "string" }, "is_original": { "description": "An original sound a creator uploaded or recorded (false: a catalogue or licensed track).", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/SoundMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "platform": { "description": "Platform ID (tiktok, instagram, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/SoundPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "play_url": { "description": "Audio file URL (a preview where the platform serves only one); signed links expire within hours; null when not exposed.", "format": "uri", "type": [ "string", "null" ] }, "streaming_links": { "description": "The same track on music streaming services, as the platform links it; [] when none (always for original sounds).", "items": { "$ref": "#/components/schemas/StreamingLink" }, "type": "array" }, "title": { "description": "Sound or track title as shown (an original sound's generated title, e.g. \"original sound - \", included).", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical page of the sound, listing the posts that use it; null where the platform has none (Facebook).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "platform", "id", "url", "title", "author_name", "authors", "is_original", "duration_ms", "cover_url", "play_url", "streaming_links", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "SoundMetrics": { "properties": { "post_count": { "description": "Posts using the sound (TikTok videos, Instagram and Facebook reels, YouTube Shorts), as the platform counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "post_count" ], "type": "object" }, "SoundPlatformSpecific": { "properties": { "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramSoundSpecific" }, { "type": "null" } ], "description": "An Instagram audio's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokSoundSpecific" }, { "type": "null" } ], "description": "A TikTok sound's own fields." } }, "type": "object" }, "SoundSummary": { "properties": { "author_name": { "description": "Who the platform credits for the sound (a track's artist, an original sound's creator), as the index's text names it; null when it does not.", "type": [ "string", "null" ] }, "cover_url": { "description": "Cover art URL; null until the result is filled. Platform CDN URLs can expire within hours.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "Platform-native sound ID; null until the result is filled.", "type": [ "string", "null" ] }, "is_original": { "description": "An original sound a creator uploaded, as the index's title says (\"original sound\"); null when the text does not say, until the result is filled.", "type": [ "boolean", "null" ] }, "metrics": { "$ref": "#/components/schemas/SoundMetrics", "description": "Counts as the index's text states them (\"80K reels\"; rounded, as old as the index's copy: see approximate_fields), or the platform's current ones once filled; null = not stated." }, "title": { "description": "Sound or track title as the index's text shows it, else the words of the sound page's link (see approximate_fields); null when neither names it.", "type": [ "string", "null" ] }, "url": { "description": "Canonical page of the sound (equals the result's url).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "author_name", "is_original", "cover_url", "metrics" ], "type": "object" }, "SoundcloudAlbumMetrics": { "properties": { "like_count": { "description": "Likes of the set (its tracks' likes are their own).", "format": "int64", "type": [ "integer", "null" ] }, "repost_count": { "description": "Reposts of the set.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "like_count", "repost_count" ], "type": "object" }, "SoundcloudAlbumSpecific": { "properties": { "embeddable_by": { "description": "Who may embed the player (all, me, none).", "type": [ "string", "null" ] }, "last_modified_at": { "description": "When the uploader last changed the set, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "license": { "description": "The license the set is published under (all-rights-reserved, cc-by, …).", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/SoundcloudAlbumMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "permalink": { "description": "The set's name in its link (soundcloud.com//sets/).", "type": [ "string", "null" ] }, "published_at": { "description": "When the set went public on SoundCloud, RFC 3339 UTC; null when SoundCloud does not say.", "format": "date-time", "type": [ "string", "null" ] }, "purchase_title": { "description": "The label of the buy link; null when SoundCloud's default is used.", "type": [ "string", "null" ] }, "purchase_url": { "description": "The buy link the uploader set; null when none.", "format": "uri", "type": [ "string", "null" ] }, "tags": { "description": "The uploader's tags, without the quotes SoundCloud keeps around a tag of several words; [] when none.", "items": { "type": "string" }, "type": "array" }, "uploaded_at": { "description": "When the set was created on SoundCloud, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "permalink", "tags", "license", "published_at", "uploaded_at", "last_modified_at", "embeddable_by", "purchase_url", "purchase_title", "metrics" ], "type": "object" }, "SoundcloudArtistResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In SoundCloud's words: `metrics.post_count` is tracks SoundCloud states (not its list)." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SoundcloudPostSpecific": { "properties": { "album_title": { "description": "The album in the release metadata; null when none.", "type": [ "string", "null" ] }, "artist_name": { "description": "The credited artist in the release metadata, who may not be the account that uploaded it; null when none.", "type": [ "string", "null" ] }, "author_follower_count": { "description": "The uploader's exact follower count.", "format": "int64", "type": [ "integer", "null" ] }, "c_line": { "description": "The composition copyright line (©); null when none.", "type": [ "string", "null" ] }, "caption": { "description": "The short line the uploader wrote beside the track; null when none.", "type": [ "string", "null" ] }, "download_count": { "description": "Downloads.", "format": "int64", "type": [ "integer", "null" ] }, "embeddable_by": { "description": "Who may embed the player (all, me, none).", "type": [ "string", "null" ] }, "genre": { "description": "The genre the uploader chose, as written; null when none.", "type": [ "string", "null" ] }, "is_commentable": { "description": "The uploader allows comments on the track.", "type": [ "boolean", "null" ] }, "is_downloadable": { "description": "The uploader allows downloads of the track.", "type": [ "boolean", "null" ] }, "is_explicit": { "description": "The release metadata marks the track explicit; null when it does not say.", "type": [ "boolean", "null" ] }, "is_music": { "description": "The release metadata says the track holds music (false: spoken word or a podcast); null when it does not say.", "type": [ "boolean", "null" ] }, "is_streamable": { "description": "SoundCloud lets the track be played.", "type": [ "boolean", "null" ] }, "isrc": { "description": "International Standard Recording Code; null when none.", "type": [ "string", "null" ] }, "label_name": { "description": "The record label the uploader credits; null when none.", "type": [ "string", "null" ] }, "last_modified_at": { "description": "When the uploader last changed the track, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "license": { "description": "The license the track is published under (all-rights-reserved, cc-by, …).", "type": [ "string", "null" ] }, "monetization_model": { "description": "How the track earns in the United States (AD_SUPPORTED, SUB_HIGH_TIER, BLACKBOX, NOT_APPLICABLE); SoundCloud answers each country its own way. New values may be added.", "type": [ "string", "null" ] }, "p_line": { "description": "The sound recording copyright line (℗); null when none.", "type": [ "string", "null" ] }, "permalink": { "description": "The track's name in its link (soundcloud.com//).", "type": [ "string", "null" ] }, "policy": { "description": "What SoundCloud lets a logged-out listener in the United States do: ALLOW and MONETIZE play the whole track, SNIP a preview of it (see transcodings), BLOCK nothing. SoundCloud answers each country its own way: this is the US answer. New values may be added.", "type": [ "string", "null" ] }, "publisher": { "description": "The music publisher in the release metadata; null when none.", "type": [ "string", "null" ] }, "purchase_title": { "description": "The label of the buy link; null when SoundCloud's default is used.", "type": [ "string", "null" ] }, "purchase_url": { "description": "The buy link the uploader set; null when none.", "format": "uri", "type": [ "string", "null" ] }, "release_title": { "description": "The release in the release metadata; null when none.", "type": [ "string", "null" ] }, "released_at": { "description": "The release date the uploader states, RFC 3339 UTC; it can be long before the track came to SoundCloud. Null when none.", "format": "date-time", "type": [ "string", "null" ] }, "tags": { "description": "The uploader's tags, without the quotes SoundCloud keeps around a tag of several words; [] when none.", "items": { "type": "string" }, "type": "array" }, "transcodings": { "description": "The encodings SoundCloud serves of the track to a logged-out listener in the United States, in its order; each country gets its own list. [] when none, as under policy BLOCK.", "items": { "$ref": "#/components/schemas/SoundcloudTranscoding" }, "type": "array" }, "upc": { "description": "The release's UPC or EAN barcode; null when none.", "type": [ "string", "null" ] }, "uploaded_at": { "description": "When the track was uploaded, RFC 3339 UTC; before published_at when its release was scheduled.", "format": "date-time", "type": [ "string", "null" ] }, "visual_url": { "description": "The banner image the uploader set for the track's page; null when none.", "format": "uri", "type": [ "string", "null" ] }, "waveform_url": { "description": "The JSON file of the track's waveform, which SoundCloud's player draws.", "format": "uri", "type": [ "string", "null" ] }, "writer_composer": { "description": "The writer or composer in the release metadata; null when none.", "type": [ "string", "null" ] } }, "required": [ "genre", "tags", "caption", "permalink", "license", "label_name", "artist_name", "album_title", "release_title", "released_at", "uploaded_at", "last_modified_at", "isrc", "upc", "publisher", "writer_composer", "p_line", "c_line", "is_explicit", "is_music", "download_count", "is_downloadable", "is_streamable", "is_commentable", "policy", "monetization_model", "embeddable_by", "purchase_url", "purchase_title", "waveform_url", "visual_url", "transcodings", "author_follower_count" ], "type": "object" }, "SoundcloudProfileSpecific": { "properties": { "first_name": { "description": "The first name the account gives; null when empty.", "type": [ "string", "null" ] }, "full_name": { "description": "The name the account gives besides its display name; null when empty.", "type": [ "string", "null" ] }, "is_creator_mid_tier": { "description": "SoundCloud's mid-tier creator badge.", "type": [ "boolean", "null" ] }, "is_pro": { "description": "SoundCloud's Pro badge.", "type": [ "boolean", "null" ] }, "is_pro_unlimited": { "description": "SoundCloud's Pro Unlimited badge.", "type": [ "boolean", "null" ] }, "last_modified_at": { "description": "When the account last changed its profile, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "last_name": { "description": "The last name the account gives; null when empty.", "type": [ "string", "null" ] }, "liked_playlist_count": { "description": "Playlists the account has liked (given, not received).", "format": "int64", "type": [ "integer", "null" ] }, "liked_track_count": { "description": "Tracks the account has liked (given, not received), as SoundCloud counts them. The public list can hold fewer.", "format": "int64", "type": [ "integer", "null" ] }, "plan": { "description": "The account's creator plan, as SoundCloud names it (free, creator-pro-unlimited, …). New values may be added.", "type": [ "string", "null" ] }, "playlist_count": { "description": "Playlists and albums, as SoundCloud counts them on the account's page. The public list can hold fewer.", "format": "int64", "type": [ "integer", "null" ] }, "repost_count": { "description": "Tracks and playlists the account has reposted, when SoundCloud says; it usually leaves this empty for a logged-out reader: null.", "format": "int64", "type": [ "integer", "null" ] }, "social_links": { "description": "The links the account lists on its profile, in its order, with SoundCloud's name for each and the email addresses among them; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/SoundcloudSocialLink" }, "type": "array" } }, "required": [ "full_name", "first_name", "last_name", "playlist_count", "liked_track_count", "liked_playlist_count", "repost_count", "is_pro", "is_pro_unlimited", "is_creator_mid_tier", "plan", "last_modified_at", "social_links" ], "type": "object" }, "SoundcloudSocialLink": { "properties": { "network": { "description": "SoundCloud's name for the service, lowercase: personal, instagram, facebook, twitter, youtube, soundcloud, spotify, email, support:patreon, other, … New values may be added.", "type": "string" }, "title": { "description": "The label the account gave the link; null when it gave none.", "type": [ "string", "null" ] }, "url": { "description": "The link as the account wrote it (https:// added when it had no scheme); an email address as a mailto: link.", "format": "uri", "type": "string" }, "username": { "description": "The account on that service, as SoundCloud reads it from the link; null when it has none.", "type": [ "string", "null" ] } }, "required": [ "network", "username", "title", "url" ], "type": "object" }, "SoundcloudTrackResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post", "description": "In SoundCloud's words: `metrics.view_count` is plays." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SoundcloudTracksResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), newest first. In SoundCloud's words: `metrics.view_count` is plays.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SoundcloudTranscoding": { "properties": { "duration_ms": { "description": "Length of this encoding in milliseconds: the preview's on a snipped one.", "format": "int64", "type": [ "integer", "null" ] }, "is_snipped": { "description": "Only a preview of the track, not all of it.", "type": [ "boolean", "null" ] }, "mime_type": { "description": "The audio's media type.", "type": [ "string", "null" ] }, "preset": { "description": "SoundCloud's name of the encoding (aac_160k, mp3_1_0, abr_sq, …).", "type": [ "string", "null" ] }, "protocol": { "description": "How it is delivered: hls, progressive (one file), or cbc-encrypted-hls and ctr-encrypted-hls. New values may be added.", "type": [ "string", "null" ] }, "quality": { "description": "SoundCloud's quality label: lq (lower), sq (standard) or hq (high). New values may be added.", "type": [ "string", "null" ] } }, "required": [ "preset", "protocol", "mime_type", "quality", "is_snipped", "duration_ms" ], "type": "object" }, "SpotifyAlbumResponse": { "properties": { "data": { "$ref": "#/components/schemas/Album", "description": "In Spotify's words: `tracks[].metrics.view_count` is plays." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SpotifyAlbumSpecific": { "properties": { "is_playable": { "description": "Spotify plays it in the country SocialTap asked from, which is not necessarily yours.", "type": [ "boolean", "null" ] }, "is_pre_release": { "description": "Announced and not out yet.", "type": [ "boolean", "null" ] }, "popularity": { "description": "Spotify's own score for this release, 0 to 100 and recent plays weighing most.", "format": "int64", "type": [ "integer", "null" ] }, "pre_release_ends_at": { "description": "When a pre-release comes out, RFC 3339 UTC; null on a release that is out.", "format": "date-time", "type": [ "string", "null" ] }, "release_date_precision": { "description": "How much of released_at Spotify states: day, month or year. New values may be added.", "enum": [ "day", "month", "year", null ], "type": [ "string", "null" ] } }, "required": [ "release_date_precision", "is_pre_release", "pre_release_ends_at", "is_playable", "popularity" ], "type": "object" }, "SpotifyArtistResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SpotifyArtistTrack": { "properties": { "album_id": { "description": "The ID of the release it is on, what spotify.album takes.", "type": [ "string", "null" ] }, "artist_name": { "description": "Who Spotify credits for the track, as one display string; null when the source names nobody.", "type": [ "string", "null" ] }, "artists": { "description": "The accounts of the track's credited artists, in Spotify's order; [] when the list names none (in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "cover_url": { "description": "The release's cover at its largest size.", "format": "uri", "type": [ "string", "null" ] }, "disc_number": { "description": "The disc of its release it is on; null where the list states none.", "format": "int64", "type": [ "integer", "null" ] }, "duration_ms": { "description": "Exact length in milliseconds; null where the list states none.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "The track's base62 ID, what spotify.track takes.", "type": "string" }, "is_explicit": { "description": "True when Spotify marks the track explicit.", "type": [ "boolean", "null" ] }, "play_count": { "description": "Plays, as Spotify counts them; null where the list states none or writes 0, which is no count.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The track's title.", "type": [ "string", "null" ] }, "url": { "description": "The track's page.", "format": "uri", "type": "string" } }, "required": [ "id", "url", "title", "duration_ms", "artist_name", "play_count", "is_explicit", "disc_number", "album_id", "cover_url", "artists" ], "type": "object" }, "SpotifyConcert": { "properties": { "city": { "description": "The venue's city.", "type": [ "string", "null" ] }, "id": { "description": "Spotify's ID of the concert.", "type": "string" }, "is_festival": { "description": "True for a festival.", "type": [ "boolean", "null" ] }, "starts_at": { "description": "When it starts, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "title": { "description": "The concert's title, as Spotify shows it.", "type": [ "string", "null" ] }, "url": { "description": "The concert's page.", "format": "uri", "type": "string" }, "venue": { "description": "The venue's name.", "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "venue", "city", "starts_at", "is_festival" ], "type": "object" }, "SpotifyCredit": { "properties": { "artist_id": { "description": "Their artist ID (spotify.artist takes it); null when they have no artist page.", "type": [ "string", "null" ] }, "group": { "description": "The heading Spotify lists it under (Composition & Lyrics, Production & Engineering, …).", "type": [ "string", "null" ] }, "name": { "description": "Who, as Spotify names them.", "type": "string" }, "role": { "description": "What they did, as Spotify says (Composer, Producer, Main Artist, …).", "type": [ "string", "null" ] } }, "required": [ "name", "role", "group", "artist_id" ], "type": "object" }, "SpotifyPinnedItem": { "properties": { "comment": { "description": "What the artist wrote with it; null when nothing.", "type": [ "string", "null" ] }, "image_url": { "description": "Its picture at its largest size.", "format": "uri", "type": [ "string", "null" ] }, "subtitle": { "description": "What the page writes under it, as shown.", "type": [ "string", "null" ] }, "title": { "description": "Its title.", "type": [ "string", "null" ] }, "type": { "description": "What is pinned, in Spotify's word, lowercase (album, playlist, concert, …). New values may be added.", "type": [ "string", "null" ] }, "uri": { "description": "Its Spotify URI (spotify:album:…), of any kind.", "type": [ "string", "null" ] } }, "required": [ "type", "uri", "title", "subtitle", "comment", "image_url" ], "type": "object" }, "SpotifyPlaylistRef": { "properties": { "description": { "description": "The playlist's description as plain text; null when empty.", "type": [ "string", "null" ] }, "id": { "description": "The playlist's base62 ID, what spotify.playlist takes.", "type": "string" }, "image_url": { "description": "The playlist's picture at its largest size.", "format": "uri", "type": [ "string", "null" ] }, "owner_name": { "description": "The name of the account that owns it, as Spotify shows it.", "type": [ "string", "null" ] }, "title": { "description": "The playlist's name.", "type": [ "string", "null" ] }, "url": { "description": "The playlist's page.", "format": "uri", "type": "string" } }, "required": [ "id", "url", "title", "description", "image_url", "owner_name" ], "type": "object" }, "SpotifyPlaylistResponse": { "properties": { "data": { "$ref": "#/components/schemas/Playlist" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SpotifyPlaylistSpecific": { "properties": { "created_at": { "description": "When it was created, RFC 3339 UTC; null on Spotify's own playlists, which don't state it.", "format": "date-time", "type": [ "string", "null" ] }, "follower_count": { "description": "Listeners who follow the playlist, exact.", "format": "int64", "type": [ "integer", "null" ] }, "is_algorithmic": { "description": "Whether Spotify marks it as assembled by its algorithm rather than by its editors; null where Spotify says neither, as on a listener's playlist or a chart.", "type": [ "boolean", "null" ] }, "is_collaborative": { "description": "Whether people its owner invites can add to it.", "type": [ "boolean", "null" ] }, "is_deleted_by_owner": { "description": "Whether its owner deleted it: Spotify goes on serving such a playlist to anyone with its link.", "type": [ "boolean", "null" ] }, "is_user_created": { "description": "True for a listener's playlist, false for one of Spotify's own.", "type": [ "boolean", "null" ] }, "updated_at": { "description": "When it last changed, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "follower_count", "is_collaborative", "is_algorithmic", "is_user_created", "is_deleted_by_owner", "created_at", "updated_at" ], "type": "object" }, "SpotifyPlaylist_tracksResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), the playlist's own order, as its owner or Spotify arranged it. In Spotify's words: `metrics.view_count` is plays.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifyPodcastResponse": { "properties": { "data": { "$ref": "#/components/schemas/Podcast", "description": "In Spotify's words: `categories` is topics." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "SpotifyPodcast_episodesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the show's own order: newest first, or from the first episode on a show meant to be heard in order. In Spotify's words: `metrics.view_count` is plays.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifyPostSpecific": { "properties": { "added_at": { "description": "When it was added to the playlist listed, RFC 3339 UTC; null outside a playlist's list.", "format": "date-time", "type": [ "string", "null" ] }, "added_by": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The listener who added it to the playlist listed: their username and page, and their name and picture when the source shows them; null outside a playlist's list and on Spotify's own lists, which name nobody." }, "album_id": { "description": "The ID of the release it is on (spotify.album takes it); null when the source does not show it, as on the embed page.", "type": [ "string", "null" ] }, "album_title": { "description": "The title of that release.", "type": [ "string", "null" ] }, "album_track_count": { "description": "How many tracks that release has.", "format": "int64", "type": [ "integer", "null" ] }, "album_type": { "description": "What kind of release that is, as Spotify says. New values may be added; treat unknown values as album.", "enum": [ "album", "single", "ep", "compilation", null ], "type": [ "string", "null" ] }, "album_url": { "description": "That release's page.", "format": "uri", "type": [ "string", "null" ] }, "bpm": { "description": "Its tempo in beats per minute, to two decimals, as Spotify measured it; null where the source does not show it, as everywhere but a playlist's list.", "format": "double", "type": [ "number", "null" ] }, "camelot_key": { "description": "Its key on the Camelot wheel DJs mix by (6A); null where the source does not show it, as everywhere but a playlist's list.", "type": [ "string", "null" ] }, "canonical_track_id": { "description": "The ID Spotify treats as this recording's main one, when that is another; null when this is it or the source does not show it.", "type": [ "string", "null" ] }, "copyrights": { "description": "The copyright lines of the release it is on; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/AlbumCopyright" }, "type": "array" }, "credits": { "description": "Who wrote, performed and produced it, as Spotify's Credits panel lists them; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/SpotifyCredit" }, "type": "array" }, "disc_number": { "description": "The disc of that release it is on, from 1.", "format": "int64", "type": [ "integer", "null" ] }, "is_explicit": { "description": "Spotify marks it explicit.", "type": [ "boolean", "null" ] }, "is_paywalled": { "description": "An episode only subscribers can hear in full; null on a track.", "type": [ "boolean", "null" ] }, "is_playable": { "description": "Spotify plays it in the country SocialTap asked from, which is not necessarily yours.", "type": [ "boolean", "null" ] }, "isrc": { "description": "International Standard Recording Code, 12 characters without hyphens; null when the source does not show it.", "type": [ "string", "null" ] }, "label": { "description": "The record label of the release it is on; null when the source does not show it.", "type": [ "string", "null" ] }, "languages": { "description": "The languages it is performed in, as Spotify's tags; [] when none is stated (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "music_video_count": { "description": "How many music videos Spotify links to it; null when the source does not show it.", "format": "int64", "type": [ "integer", "null" ] }, "musical_key": { "description": "Its key and mode as Spotify measured them (F# minor); null where the source does not show it, as everywhere but a playlist's list.", "type": [ "string", "null" ] }, "playability_reason": { "description": "Why, as Spotify says it (playable, country_restricted, …), for that country; null when the source does not say.", "type": [ "string", "null" ] }, "podcast_id": { "description": "An episode's show (spotify.podcast takes it); null on a track.", "type": [ "string", "null" ] }, "popularity": { "description": "Spotify's own score for this track ID, 0 to 100 and recent plays weighing most; two IDs of one recording score apart (canonical_track_id).", "format": "int64", "type": [ "integer", "null" ] }, "release_date_precision": { "description": "How much of published_at Spotify states: day, month or year. Null for an episode, whose time is exact, and when the source does not say. New values may be added.", "enum": [ "day", "month", "year", null ], "type": [ "string", "null" ] }, "track_number": { "description": "Its position on that disc, from 1.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "album_id", "album_title", "album_url", "album_type", "album_track_count", "release_date_precision", "disc_number", "track_number", "isrc", "label", "copyrights", "credits", "is_explicit", "is_playable", "playability_reason", "popularity", "languages", "music_video_count", "canonical_track_id", "added_at", "added_by", "bpm", "musical_key", "camelot_key", "podcast_id", "is_paywalled" ], "type": "object" }, "SpotifyProfileSpecific": { "properties": { "active_decades": { "description": "The decades Spotify lists the artist as active in, as their first year (1980), in its order; [] when it lists none.", "items": { "format": "int64", "type": "integer" }, "type": "array" }, "ai_persona": { "description": "Spotify's word when it labels the artist an AI persona (confirmed), lowercase; null when it says nothing, which is nearly always. New values may be added.", "type": [ "string", "null" ] }, "albums": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyReleases" }, { "type": "null" } ], "description": "The artist's albums, newest first." }, "appears_on": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyReleases" }, { "type": "null" } ], "description": "Other artists' releases the artist appears on." }, "biography_type": { "description": "Spotify's word for the kind of text bio is (autobiography, biography, …), lowercase. New values may be added.", "type": [ "string", "null" ] }, "compilations": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyReleases" }, { "type": "null" } ], "description": "The artist's compilations, newest first." }, "concert_count": { "description": "How many concerts Spotify counts for the artist, which concerts can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "concerts": { "description": "The artist's upcoming concerts Spotify lists, as many as the page shows, which can depend on the country SocialTap asked from; [] when it lists none.", "items": { "$ref": "#/components/schemas/SpotifyConcert" }, "type": "array" }, "discovered_on": { "description": "Playlists where listeners discovered the artist, as many as the page shows, which can be fewer than discovered_on_count says: Spotify answers some of them with an error, and they are left out. [] when none.", "items": { "$ref": "#/components/schemas/SpotifyPlaylistRef" }, "type": "array" }, "discovered_on_count": { "description": "How many playlists Spotify counts as where listeners discovered the artist, at most a hundred on the artists sampled.", "format": "int64", "type": [ "integer", "null" ] }, "featured_in": { "description": "Playlists Spotify lists as featuring the artist, as many as the page shows; [] when it lists none.", "items": { "$ref": "#/components/schemas/SpotifyPlaylistRef" }, "type": "array" }, "featured_in_count": { "description": "How many playlists Spotify counts as featuring the artist, which featured_in can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "gallery_urls": { "description": "The pictures in the artist's gallery, each at its largest size; [] when it has none.", "items": { "type": "string" }, "type": "array" }, "is_registered": { "description": "True when Spotify says the artist's profile is registered with it, which is_verified's badge need not be.", "type": [ "boolean", "null" ] }, "latest_release": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyRelease" }, { "type": "null" } ], "description": "The artist's latest release; null when it has none or Spotify does not name one." }, "monthly_listener_count": { "description": "People who played the artist in the last 28 days, exact, as Spotify counts them.", "format": "int64", "type": [ "integer", "null" ] }, "music_video_count": { "description": "How many music videos Spotify counts for the artist, which music_videos can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "music_videos": { "description": "The artist's music videos, as many as the page holds; [] when it holds none. Spotify states no length or plays for them here.", "items": { "$ref": "#/components/schemas/SpotifyArtistTrack" }, "type": "array" }, "pinned_item": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyPinnedItem" }, { "type": "null" } ], "description": "What the artist has pinned to the top of its page; null when nothing." }, "playlist_count": { "description": "How many playlists Spotify counts on the artist's page, which playlists can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "playlists": { "description": "The playlists the artist shows on its page; [] when it shows none.", "items": { "$ref": "#/components/schemas/SpotifyPlaylistRef" }, "type": "array" }, "popular_release_count": { "description": "How many popular releases Spotify counts, which popular_releases can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "popular_releases": { "description": "The artist's popular releases, as the page ranks them and as many as it shows; [] when it shows none.", "items": { "$ref": "#/components/schemas/SpotifyRelease" }, "type": "array" }, "popularity": { "description": "Spotify's popularity score of the artist, 0 to 100.", "format": "int64", "type": [ "integer", "null" ] }, "related_artist_count": { "description": "How many related artists Spotify counts, which related_artists can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] }, "related_artists": { "description": "Artists fans of this one also like, as many as the page shows; [] when it shows none.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "singles": { "anyOf": [ { "$ref": "#/components/schemas/SpotifyReleases" }, { "type": "null" } ], "description": "The artist's singles and EPs, newest first." }, "top_cities": { "description": "The cities with the most monthly listeners, most first, as many as Spotify shows; [] when it shows none.", "items": { "$ref": "#/components/schemas/SpotifyTopCity" }, "type": "array" }, "top_tracks": { "description": "The tracks the artist's page lists as popular, in its order; [] when it lists none. spotify.track answers each in full.", "items": { "$ref": "#/components/schemas/SpotifyArtistTrack" }, "type": "array" }, "world_rank": { "description": "The artist's place in Spotify's worldwide ranking by monthly listeners, 1 the top; null for an artist outside the ranking, where Spotify writes 0.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "monthly_listener_count", "world_rank", "popularity", "is_registered", "biography_type", "active_decades", "gallery_urls", "top_cities", "top_tracks", "music_videos", "music_video_count", "latest_release", "popular_releases", "popular_release_count", "albums", "singles", "compilations", "appears_on", "related_artists", "related_artist_count", "concerts", "concert_count", "playlists", "playlist_count", "featured_in", "featured_in_count", "discovered_on", "discovered_on_count", "pinned_item", "ai_persona" ], "type": "object" }, "SpotifyRelease": { "properties": { "artists": { "description": "The release's credited artists where the list names them (appears_on); [] elsewhere, where they are the artist's own.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "cover_url": { "description": "The cover at its largest size.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "The release's base62 ID, what spotify.album takes.", "type": "string" }, "label": { "description": "The record label, as Spotify writes it; null where the list does not say.", "type": [ "string", "null" ] }, "release_date_precision": { "description": "How much of released_at Spotify states: day, month or year. New values may be added.", "enum": [ "day", "month", "year", null ], "type": [ "string", "null" ] }, "released_at": { "description": "Its release date at midnight UTC: Spotify states no time, and release_date_precision says when it states only a month or a year (the first of it, then).", "format": "date-time", "type": [ "string", "null" ] }, "title": { "description": "The release's title, as Spotify shows it.", "type": [ "string", "null" ] }, "track_count": { "description": "How many tracks the release has; null where the list does not say.", "format": "int64", "type": [ "integer", "null" ] }, "type": { "description": "What kind of release it is, as Spotify says: album, single, ep or compilation. New values may be added.", "enum": [ "album", "single", "ep", "compilation", null ], "type": [ "string", "null" ] }, "url": { "description": "The release's page.", "format": "uri", "type": "string" } }, "required": [ "id", "url", "title", "type", "released_at", "release_date_precision", "cover_url", "track_count", "label", "artists" ], "type": "object" }, "SpotifyReleases": { "properties": { "ids": { "description": "Every release ID Spotify's metadata record lists for the section, those in items included, each what spotify.album takes. One release can have several, its editions for different countries, so this can list more than total_count. [] when it lists none, or when the record could not be read (then named in partial_data).", "items": { "type": "string" }, "type": "array" }, "items": { "description": "The releases the artist's page shows; [] when it shows none.", "items": { "$ref": "#/components/schemas/SpotifyRelease" }, "type": "array" }, "total_count": { "description": "How many releases Spotify counts in the section, which items can hold fewer of.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "total_count", "items", "ids" ], "type": "object" }, "SpotifySearch_albumsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Spotify's own ranking for the query. In Spotify's words: `tracks[].metrics.view_count` is plays.", "items": { "$ref": "#/components/schemas/Album" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifySearch_artistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Spotify's own ranking for the query.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifySearch_playlistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Spotify's own ranking for the query.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifySearch_podcastsResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Spotify's own ranking for the query. In Spotify's words: `categories` is topics.", "items": { "$ref": "#/components/schemas/Podcast" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifySearch_tracksResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Spotify's own ranking for the query. In Spotify's words: `metrics.view_count` is plays.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "SpotifyTopCity": { "properties": { "city": { "description": "The city's name, as Spotify writes it.", "type": [ "string", "null" ] }, "country_code": { "description": "The city's country, an ISO 3166-1 alpha-2 code.", "type": [ "string", "null" ] }, "listener_count": { "description": "Monthly listeners in the city, exact.", "format": "int64", "type": [ "integer", "null" ] }, "region": { "description": "The region of the country, as Spotify codes it (ENG, CMX).", "type": [ "string", "null" ] } }, "required": [ "city", "country_code", "region", "listener_count" ], "type": "object" }, "SpotifyTrackResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post", "description": "In Spotify's words: `metrics.view_count` is plays." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "StreamingLink": { "properties": { "service": { "description": "The streaming service. New values may be added; treat unknown values as other.", "enum": [ "spotify", "apple_music" ], "type": "string" }, "url": { "description": "The track's public page on the service.", "format": "uri", "type": "string" } }, "required": [ "service", "url" ], "type": "object" }, "Suggestion": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded or capped by the platform (hashtag.metrics.post_count at Instagram's ceiling). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "hashtag": { "anyOf": [ { "$ref": "#/components/schemas/HashtagRef" }, { "type": "null" } ], "description": "The hashtag a hashtag suggestion names, keyed as the platform's hashtag endpoints key it; null for every other type." }, "platform": { "description": "Platform whose search box offers the suggestion.", "examples": [ "tiktok" ], "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/SuggestionPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "position": { "description": "Zero-based rank of the suggestion in the list, counting every type: the platform's order (each endpoint's notes say how a list combining several of the platform's searches is ordered).", "format": "int64", "minimum": 0, "type": "integer" }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account a profile suggestion names; null for every other type." }, "text": { "description": "The suggestion as the platform shows it, whitespace-trimmed: the completed search for a query suggestion, the account's name for a profile one, the domain for a website one.", "examples": [ "dogs funny videos" ], "type": "string" }, "type": { "description": "query = a completed search to run; profile = an account (or community) the platform proposes, described in profile; hashtag = a hashtag, described in hashtag; website = a website the platform proposes: text is its domain (nike.com), as the platform's searches by website take it. New values may be added.", "enum": [ "query", "profile", "hashtag", "website" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none; [] when every list is known (a suggestion has none yet).", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Where the suggestion leads on the platform: the search results page for a query, the account's page for a profile, the hashtag's page for a hashtag, the platform's page for the website for a website.", "format": "uri", "type": "string" } }, "required": [ "platform", "text", "type", "position", "url", "profile", "hashtag", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "SuggestionPlatformSpecific": { "properties": { "google": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSuggestionSpecific" }, { "type": "null" } ], "description": "A Google Ads Transparency Center suggestion's own fields." }, "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramSuggestionSpecific" }, { "type": "null" } ], "description": "An Instagram suggestion's own fields." }, "tiktok": { "anyOf": [ { "$ref": "#/components/schemas/TikTokSuggestionSpecific" }, { "type": "null" } ], "description": "A TikTok suggestion's own fields." } }, "type": "object" }, "TelegramButton": { "properties": { "text": { "description": "The button's label.", "type": [ "string", "null" ] }, "url": { "description": "What it opens: a web link or a tg:// link.", "type": [ "string", "null" ] } }, "required": [ "text", "url" ], "type": "object" }, "TelegramChannelResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Telegram's words: `metrics.follower_count` is subscribers." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TelegramChannel_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), newest first. In Telegram's words: `metrics.like_count` is reactions.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TelegramDocument": { "properties": { "performer": { "description": "An audio file's performer as Telegram shows it; null for other files and an audio file without one.", "type": [ "string", "null" ] }, "size": { "description": "Its size as Telegram shows it (1.3 MB); null when it shows none, as on an audio file.", "type": [ "string", "null" ] }, "title": { "description": "The file's name, or an audio file's title.", "type": [ "string", "null" ] } }, "required": [ "title", "performer", "size" ], "type": "object" }, "TelegramForward": { "properties": { "author": { "description": "The admin who signed the original; null when unsigned.", "type": [ "string", "null" ] }, "name": { "description": "The name of the channel or person it was forwarded from; null when Telegram leaves it blank.", "type": [ "string", "null" ] }, "post_id": { "description": "The original post's id, when the link names one.", "type": [ "string", "null" ] }, "url": { "description": "The original's link (or the account's, for a person); null when the source hides itself.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "name", "url", "post_id", "author" ], "type": "object" }, "TelegramLinkPreview": { "properties": { "description": { "description": "The page's description, as the card shows it.", "type": [ "string", "null" ] }, "image_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "site_name": { "description": "The site's name.", "type": [ "string", "null" ] }, "title": { "description": "The page's title.", "type": [ "string", "null" ] }, "url": { "description": "The previewed link.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "site_name", "title", "description", "image_url" ], "type": "object" }, "TelegramPoll": { "properties": { "options": { "description": "The options, in the poll's order.", "items": { "$ref": "#/components/schemas/TelegramPollOption" }, "type": "array" }, "question": { "description": "The question.", "type": [ "string", "null" ] }, "type": { "description": "Telegram's label, lower case: anonymous poll, public poll, anonymous quiz, …", "type": [ "string", "null" ] }, "voter_count": { "description": "People who voted; rounded by Telegram from the thousands up (see approximate_fields).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "question", "type", "voter_count", "options" ], "type": "object" }, "TelegramPollOption": { "properties": { "percent": { "description": "Its share of the votes, in percent, as Telegram rounds it.", "format": "double", "type": [ "number", "null" ] }, "text": { "description": "The option's text.", "type": [ "string", "null" ] } }, "required": [ "text", "percent" ], "type": "object" }, "TelegramPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post", "description": "In Telegram's words: `metrics.like_count` is reactions." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TelegramPostSpecific": { "properties": { "buttons": { "description": "The buttons under the post that open a link; [] when none.", "items": { "$ref": "#/components/schemas/TelegramButton" }, "type": "array" }, "channel_id": { "description": "Telegram's numeric ID of the channel or group the message is in, which stays when its username changes.", "type": [ "string", "null" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/TelegramDocument" }, { "type": "null" } ], "description": "The file or audio file the post carries, which Telegram names but does not link logged out; null when none." }, "forwarded_from": { "anyOf": [ { "$ref": "#/components/schemas/TelegramForward" }, { "type": "null" } ], "description": "Where the post was forwarded from; null when it was not forwarded." }, "is_edited": { "description": "Whether the post shows as edited.", "type": [ "boolean", "null" ] }, "link_preview": { "anyOf": [ { "$ref": "#/components/schemas/TelegramLinkPreview" }, { "type": "null" } ], "description": "The link preview card the post shows; null when none." }, "links": { "description": "The link targets in the post's text, in order, those behind a word included; [] when none.", "items": { "type": "string" }, "type": "array" }, "message_id": { "description": "The message's number within its channel or group: the last part of its link.", "format": "int64", "type": [ "integer", "null" ] }, "poll": { "anyOf": [ { "$ref": "#/components/schemas/TelegramPoll" }, { "type": "null" } ], "description": "The poll the post carries; null when none." }, "reactions": { "description": "The reactions the post shows, each emoji with its count; [] when it shows none. Their sum is metrics.like_count.", "items": { "$ref": "#/components/schemas/TelegramReaction" }, "type": "array" }, "reply_to": { "anyOf": [ { "$ref": "#/components/schemas/TelegramReply" }, { "type": "null" } ], "description": "The message this post replies to, as its preview bar shows it; null when it is not a reply." }, "sender_name": { "description": "The name of the group member who sent the message, when they have no username: author is then the group. Null otherwise.", "type": [ "string", "null" ] }, "signature": { "description": "The name of the admin who signed the post, on a channel that signs its posts; null when unsigned.", "type": [ "string", "null" ] } }, "required": [ "message_id", "channel_id", "signature", "sender_name", "is_edited", "forwarded_from", "reply_to", "reactions", "link_preview", "poll", "document", "links", "buttons" ], "type": "object" }, "TelegramProfileSpecific": { "properties": { "account_type": { "description": "What Telegram's page shows the account to be: channel, group, user or bot. New values may be added.", "enum": [ "channel", "group", "user", "bot", null ], "type": [ "string", "null" ] }, "channel_id": { "description": "Telegram's numeric ID of the channel, which stays when its username changes. Null when the channel's preview shows none (its first message was deleted, or it serves no preview), and for a group, a user or a bot.", "type": [ "string", "null" ] }, "file_count": { "description": "Files the channel has posted, as its preview's panel shows it; null when it shows none.", "format": "int64", "type": [ "integer", "null" ] }, "is_preview_available": { "description": "Whether t.me served this channel's public preview (t.me/s/, where telegram.channel_posts reads its posts) from where this request left: it is off on some channels, and Telegram withholds some only in certain countries. False for a group, a user or a bot. Null when the request for the preview failed (a partial_data warning).", "type": [ "boolean", "null" ] }, "link_count": { "description": "Links the channel has posted, as its preview's panel shows it; null when it shows none.", "format": "int64", "type": [ "integer", "null" ] }, "monthly_user_count": { "description": "A bot's monthly users, as its page shows them; null otherwise.", "format": "int64", "type": [ "integer", "null" ] }, "online_count": { "description": "Members online now, on a group that shows it; null otherwise.", "format": "int64", "type": [ "integer", "null" ] }, "photo_count": { "description": "Photos the channel has posted, as its preview's panel shows it; null when it shows none.", "format": "int64", "type": [ "integer", "null" ] }, "video_count": { "description": "Videos the channel has posted, as its preview's panel shows it; null when it shows none.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "account_type", "channel_id", "is_preview_available", "online_count", "monthly_user_count", "photo_count", "video_count", "link_count", "file_count" ], "type": "object" }, "TelegramReaction": { "properties": { "count": { "description": "How many; rounded by Telegram from the thousands up (see approximate_fields).", "format": "int64", "type": [ "integer", "null" ] }, "custom_emoji_id": { "description": "The custom emoji's ID; null for a unicode one.", "type": [ "string", "null" ] }, "emoji": { "description": "The unicode emoji; null for a custom emoji or Telegram Stars.", "type": [ "string", "null" ] }, "is_paid": { "description": "Whether it is a paid reaction (Telegram Stars).", "type": [ "boolean", "null" ] } }, "required": [ "emoji", "custom_emoji_id", "is_paid", "count" ], "type": "object" }, "TelegramReply": { "properties": { "author": { "description": "The name the bar shows; null when it shows none.", "type": [ "string", "null" ] }, "post_id": { "description": "The replied-to post's id, when the link names one.", "type": [ "string", "null" ] }, "text": { "description": "The snippet the bar shows, often cut short.", "type": [ "string", "null" ] }, "url": { "description": "The replied-to message's link; null when the bar has none.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "post_id", "author", "text" ], "type": "object" }, "TelegramSearch_channelsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ThreadsCommentSpecific": { "properties": { "language": { "description": "The reply's language as Threads detected it, a BCP-47 tag (en, pt, zh-TW); null when Threads could not tell (an emoji, a link, media only) or does not say.", "type": [ "string", "null" ] }, "quote_count": { "description": "Times the reply was quoted in another post; never negative.", "format": "int64", "type": [ "integer", "null" ] }, "repost_count": { "description": "Times the reply was reposted; never negative.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "repost_count", "quote_count", "language" ], "type": "object" }, "ThreadsCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), newest first.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ThreadsHashtagSpecific": { "properties": { "is_community": { "description": "The tag is a Threads community (\"NBA Threads\"), not a plain tag.", "type": [ "boolean", "null" ] }, "recent_post_count": { "description": "Recent posts with the tag as Threads counts them (it does not state the window), rounded (in approximate_fields).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "is_community", "recent_post_count" ], "type": "object" }, "ThreadsLink": { "properties": { "image_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The card's headline.", "type": [ "string", "null" ] }, "url": { "description": "The linked page (Threads' l.threads.com redirect removed).", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "title", "image_url" ], "type": "object" }, "ThreadsPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "ThreadsPostSpecific": { "properties": { "is_edited": { "description": "The text was edited after posting.", "type": [ "boolean", "null" ] }, "is_reply": { "description": "The post is a reply to another post.", "type": [ "boolean", "null" ] }, "is_spoiler": { "description": "The author marked the media as a spoiler.", "type": [ "boolean", "null" ] }, "link": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsLink" }, { "type": "null" } ], "description": "The link preview card the post shows; null when none." }, "numeric_id": { "description": "Threads' numeric post ID, which the shortcode in id encodes.", "type": [ "string", "null" ] }, "quoted_post": { "anyOf": [ { "$ref": "#/components/schemas/ThreadsQuotedPost" }, { "type": "null" } ], "description": "The post this one quotes; null when it quotes none, or when the quoted post is no longer available (deleted, or not shown logged out)." }, "reply_control": { "description": "Who may reply, as Threads names it (everyone, accounts_you_follow, mentioned_only, …).", "type": [ "string", "null" ] }, "reply_to_author": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The author of the post this one replies to; null when it is not a reply." }, "topic_tag": { "description": "The topic or community tag shown on the post; null when none.", "type": [ "string", "null" ] } }, "required": [ "numeric_id", "is_reply", "reply_to_author", "quoted_post", "topic_tag", "link", "reply_control", "is_spoiler", "is_edited" ], "type": "object" }, "ThreadsPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 25), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ThreadsProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "ThreadsProfileSpecific": { "properties": { "interest_tags": { "description": "Topic labels Threads shows on the profile, as shown; [] when it shows none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "verified_link_urls": { "description": "The external_links URLs Threads marks as verified, in the same form; [] when none is marked (listed in unknown_fields when the source cannot see the links).", "items": { "type": "string" }, "type": "array" } }, "required": [ "interest_tags", "verified_link_urls" ], "type": "object" }, "ThreadsQuotedPost": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "id": { "description": "Its shortcode.", "type": [ "string", "null" ] }, "url": { "description": "Its URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "author" ], "type": "object" }, "ThreadsSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), newest first with sort=newest, Threads' best matches (its search ranking) with sort=relevance.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "ThreadsSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), Threads' search ranking.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TikTokAdCountryTargeting": { "properties": { "age_ranges": { "description": "Age ranges targeted (13-17, 18-24, 25-34, 35-44, 45-54, 55+); [] when not shown.", "items": { "type": "string" }, "type": "array" }, "breakdown": { "description": "Unique users reached there by age range and gender, the segments TikTok shows a number for; [] when none.", "items": { "$ref": "#/components/schemas/TikTokAdReachSegment" }, "type": "array" }, "country_code": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string" }, "genders": { "description": "Genders targeted (female, male, unknown); [] when not shown.", "items": { "type": "string" }, "type": "array" }, "reach": { "anyOf": [ { "$ref": "#/components/schemas/Range" }, { "type": "null" } ], "description": "Unique users the ad reached there (rounded: approximate_fields); null when not shown." } }, "required": [ "country_code", "reach", "age_ranges", "genders", "breakdown" ], "type": "object" }, "TikTokAdReachSegment": { "properties": { "age_range": { "description": "Age range (18-24, 55+).", "type": "string" }, "gender": { "description": "female, male or unknown.", "type": "string" }, "reach": { "$ref": "#/components/schemas/Range", "description": "Unique users reached (rounded: approximate_fields)." } }, "required": [ "age_range", "gender", "reach" ], "type": "object" }, "TikTokAdSpecific": { "properties": { "advertiser_business_id": { "description": "The advertiser's TikTok business ID (search_ads advertiser_id).", "type": [ "string", "null" ] }, "advertiser_registry_location": { "description": "Where the advertiser is registered (Italy).", "type": [ "string", "null" ] }, "budget": { "description": "Creative Center's budget level; null off the board. New values may be added; treat unknown values as other.", "enum": [ "low", "medium", "high", null ], "type": [ "string", "null" ] }, "category": { "description": "The ad's topic as TikTok files it (Apps, Food & Beverage).", "type": [ "string", "null" ] }, "ctr_top_percent": { "description": "Click-through rate rank: the ad is in the top this many percent of ads (4 = top 4%); null off the board.", "format": "double", "type": [ "number", "null" ] }, "is_removed": { "description": "TikTok took the ad down (its rules or local law), in some or all regions.", "type": [ "boolean", "null" ] }, "like_count": { "description": "Likes the ad drew, as Creative Center counts them; null off the board.", "format": "int64", "type": [ "integer", "null" ] }, "objective": { "description": "The campaign objective (Reach, Traffic).", "type": [ "string", "null" ] }, "rank": { "description": "Place on Creative Center's Top Ads board, 1 first; null off the board.", "format": "int64", "type": [ "integer", "null" ] }, "removal_country_codes": { "description": "Countries where TikTok took the ad down (ISO 3166-1 alpha-2); [] when it was not taken down (in unknown_fields when not shown).", "items": { "type": "string" }, "type": "array" }, "removal_reasons": { "description": "TikTok's reasons for the takedown; [] when none (in unknown_fields when not shown).", "items": { "type": "string" }, "type": "array" }, "targeting": { "anyOf": [ { "$ref": "#/components/schemas/TikTokAdTargeting" }, { "type": "null" } ], "description": "Whom the advertiser targeted and whom the ad reached, per country; null when not shown." } }, "required": [ "is_removed", "removal_reasons", "category", "objective", "removal_country_codes", "targeting", "advertiser_business_id", "advertiser_registry_location", "rank", "like_count", "ctr_top_percent", "budget" ], "type": "object" }, "TikTokAdTargeting": { "properties": { "cities": { "description": "Cities targeted; [] when none.", "items": { "type": "string" }, "type": "array" }, "countries": { "description": "Per country it ran in: the ages and genders targeted and the unique users reached.", "items": { "$ref": "#/components/schemas/TikTokAdCountryTargeting" }, "type": "array" }, "creator_interactions": { "description": "Creator interaction categories targeted; [] when none.", "items": { "type": "string" }, "type": "array" }, "device_models": { "description": "Device models targeted; [] when any.", "items": { "type": "string" }, "type": "array" }, "interests": { "description": "Interest categories targeted; [] when none.", "items": { "type": "string" }, "type": "array" }, "is_audience_excluded": { "description": "The advertiser excluded a custom audience.", "type": [ "boolean", "null" ] }, "is_custom_audience": { "description": "The advertiser targeted a custom audience (its own customer list or a lookalike).", "type": [ "boolean", "null" ] }, "is_high_spending_power": { "description": "Targeted at users TikTok rates as high spenders.", "type": [ "boolean", "null" ] }, "operating_systems": { "description": "Operating systems targeted; [] when any.", "items": { "type": "string" }, "type": "array" }, "provinces": { "description": "Provinces or states targeted within the countries; [] when none.", "items": { "type": "string" }, "type": "array" }, "video_interactions": { "description": "Video interaction categories targeted; [] when none.", "items": { "type": "string" }, "type": "array" } }, "required": [ "countries", "interests", "video_interactions", "creator_interactions", "provinces", "cities", "device_models", "operating_systems", "is_custom_audience", "is_audience_excluded", "is_high_spending_power" ], "type": "object" }, "TikTokCommentSpecific": { "properties": { "author_sec_uid": { "description": "The commenter's secUid, TikTok's account key that survives a rename.", "type": [ "string", "null" ] }, "language": { "description": "The comment's language as TikTok detected it, an ISO 639-1 code (en, fr); null when TikTok could not tell (emoji, a name) or does not say.", "type": [ "string", "null" ] }, "thread_id": { "description": "For a reply: the ID of its top-level comment (parent_id may name another reply it answers); null for a top-level comment.", "type": [ "string", "null" ] } }, "required": [ "author_sec_uid", "language", "thread_id" ], "type": "object" }, "TikTokDownloadSpecific": { "properties": { "is_download_allowed": { "description": "The creator lets viewers save the post in TikTok's app; false: saving is turned off (the files stay public). Null when TikTok does not say.", "type": [ "boolean", "null" ] } }, "required": [ "is_download_allowed" ], "type": "object" }, "TikTokEffectSpecific": { "properties": { "creator_sec_uid": { "description": "The creator's secUid, TikTok's account key that survives a rename; null for TikTok's own effects.", "type": [ "string", "null" ] } }, "required": [ "creator_sec_uid" ], "type": "object" }, "TikTokHashtagSpecific": { "properties": { "banner_url": { "description": "The hashtag page's cover image URL; null when it has none. TikTok CDN URLs can expire.", "format": "uri", "type": [ "string", "null" ] }, "industry": { "description": "The industry Creative Center files the hashtag under (Apparel & Accessories, Games, …), as shown; not normalized.", "type": [ "string", "null" ] }, "is_new_to_board": { "description": "First time on the board this period; null off a board.", "type": [ "boolean", "null" ] }, "is_promoted": { "description": "An advertiser's hashtag: a Branded Hashtag Challenge, or one Creative Center marks promoted.", "type": [ "boolean", "null" ] }, "period_post_count": { "description": "Posts with the tag published in the board's period (the request's window); null off a board.", "format": "int64", "type": [ "integer", "null" ] }, "period_view_count": { "description": "Views in the board's period of posts with the tag; null off a board.", "format": "int64", "type": [ "integer", "null" ] }, "rank": { "description": "Position on the requested trending board (1 = most popular; the request's country, period and industry); null off a board.", "format": "int64", "type": [ "integer", "null" ] }, "rank_change": { "description": "Places climbed since the previous period (negative: fell, 0: unchanged); null when new to the board or off a board.", "format": "int64", "type": [ "integer", "null" ] }, "trend": { "description": "The hashtag's popularity over the board's period, oldest first; [] off a board (in unknown_fields).", "items": { "$ref": "#/components/schemas/TikTokHashtagTrendPoint" }, "type": "array" }, "view_count": { "description": "Views across every post carrying the tag, all time, exact; null where TikTok does not show it.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "view_count", "banner_url", "is_promoted", "rank", "rank_change", "is_new_to_board", "period_post_count", "period_view_count", "industry", "trend" ], "type": "object" }, "TikTokHashtagTrendPoint": { "properties": { "popularity": { "description": "Popularity in the interval relative to the period's peak, 0 to 1, as Creative Center scales it.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "start_at": { "description": "Start of the interval (a day on TikTok's boards), RFC 3339 UTC.", "format": "date-time", "type": "string" } }, "required": [ "start_at", "popularity" ], "type": "object" }, "TikTokLiveSpecific": { "properties": { "host_follower_count": { "description": "The host's follower count at fetch time; null when hidden.", "format": "int64", "type": [ "integer", "null" ] }, "host_sec_uid": { "description": "The host's secUid, TikTok's account key that survives a rename.", "type": [ "string", "null" ] }, "is_age_restricted": { "description": "Viewers must be of age to watch the room; null when the source does not show it.", "type": [ "boolean", "null" ] }, "is_subscriber_only": { "description": "Only the host's paying subscribers can watch.", "type": [ "boolean", "null" ] }, "stream_id": { "description": "TikTok's ID of the room's current stream (in its playback links).", "type": [ "string", "null" ] } }, "required": [ "host_sec_uid", "host_follower_count", "stream_id", "is_subscriber_only", "is_age_restricted" ], "type": "object" }, "TikTokMatchedSong": { "properties": { "id": { "description": "TikTok's ID of the song (not a sound ID: a sound endpoint does not take it). An official clip of a song and the original sounds matched to it share it, so grouping on it counts every use of the song; null when not stated.", "type": [ "string", "null" ] }, "streaming_links": { "description": "The matched song on music streaming services, as TikTok links it; [] when none.", "items": { "$ref": "#/components/schemas/StreamingLink" }, "type": "array" } }, "required": [ "id", "streaming_links" ], "type": "object" }, "TikTokPlaceSpecific": { "properties": { "category_path": { "description": "TikTok's category from broadest to most specific (Food and Drink, Fast Food, Pizza Fast Food), repeats dropped; category is the last. [] when TikTok shows none (listed in unknown_fields when the source cannot see it).", "items": { "type": "string" }, "type": "array" }, "highlights": { "description": "The highlight tags TikTok shows from reviews (Excellent service, Pleasant atmosphere); [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "is_claimed": { "description": "True when a business has claimed the place on TikTok, false when none has; null when unknown.", "type": [ "boolean", "null" ] }, "parent_id": { "description": "ID of the place TikTok files this one under (the city of a venue); a TikTok place ID. Null for a top-level place or when unknown.", "type": [ "string", "null" ] }, "parent_name": { "description": "Name of the place in parent_id.", "type": [ "string", "null" ] }, "rating": { "description": "Average TikTok review score out of 5 (metrics.review_count reviews behind it); null when the place is unrated.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "category_path", "parent_id", "parent_name", "rating", "is_claimed", "highlights" ], "type": "object" }, "TikTokPostBoard": { "properties": { "engagement_rate": { "description": "Interactions per view over the post's life, as a fraction.", "format": "double", "type": [ "number", "null" ] }, "organic_view_count": { "description": "Organic views over the post's life.", "format": "int64", "type": [ "integer", "null" ] }, "period_end_at": { "description": "End of the board's window (Creative Center's latest published day).", "format": "date-time", "type": [ "string", "null" ] }, "period_engagement_rate": { "description": "Interactions per view in the board's window, as a fraction.", "format": "double", "type": [ "number", "null" ] }, "period_organic_view_count": { "description": "Organic (unpaid) views in the board's window.", "format": "int64", "type": [ "integer", "null" ] }, "period_six_second_view_rate": { "description": "Share of the window's views that lasted six seconds or more.", "format": "double", "type": [ "number", "null" ] }, "period_view_count": { "description": "Views in the board's window, paid and organic.", "format": "int64", "type": [ "integer", "null" ] }, "rank": { "description": "Position on the requested board (1 = top).", "format": "int64", "type": [ "integer", "null" ] }, "six_second_view_rate": { "description": "Share of all the post's views that lasted six seconds or more.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "rank", "period_end_at", "period_view_count", "period_organic_view_count", "organic_view_count", "period_engagement_rate", "engagement_rate", "period_six_second_view_rate", "six_second_view_rate" ], "type": "object" }, "TikTokPostLocation": { "properties": { "address": { "description": "Address line.", "type": [ "string", "null" ] }, "category": { "description": "Top-level place category.", "type": [ "string", "null" ] }, "city": { "description": "City.", "type": [ "string", "null" ] }, "id": { "description": "Place ID.", "type": [ "string", "null" ] }, "name": { "description": "Place name.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "address", "city", "category" ], "type": "object" }, "TikTokPostMusic": { "properties": { "author_name": { "description": "Who TikTok credits for the sound.", "type": [ "string", "null" ] }, "cover_url": { "description": "Sound cover image URL.", "format": "uri", "type": [ "string", "null" ] }, "duration_ms": { "description": "Sound length in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Sound ID (equals the sound's id).", "type": [ "string", "null" ] }, "is_original": { "description": "An original sound a creator uploaded (false: a catalogue track).", "type": [ "boolean", "null" ] }, "play_url": { "description": "Audio file URL, signed and expiring.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Sound title.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "author_name", "is_original", "duration_ms", "cover_url", "play_url" ], "type": "object" }, "TikTokPostSpecific": { "properties": { "author_follower_count": { "description": "The author's exact follower count; null when the source does not state it.", "format": "int64", "type": [ "integer", "null" ] }, "author_sec_uid": { "description": "The author's secUid, TikTok's account key that survives a rename.", "type": [ "string", "null" ] }, "board": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPostBoard" }, { "type": "null" } ], "description": "The post on Creative Center's top videos board (tiktok.top_posts); null off a board." }, "country_code": { "description": "ISO 3166-1 alpha-2 country TikTok registers the post to (not the viewer's).", "type": [ "string", "null" ] }, "is_ad": { "description": "The post runs as a TikTok ad.", "type": [ "boolean", "null" ] }, "is_ai_generated": { "description": "TikTok labels the post AI-generated.", "type": [ "boolean", "null" ] }, "location": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPostLocation" }, { "type": "null" } ], "description": "The tagged place; null when none." }, "music": { "anyOf": [ { "$ref": "#/components/schemas/TikTokPostMusic" }, { "type": "null" } ], "description": "The post's sound." } }, "required": [ "author_sec_uid", "country_code", "is_ad", "is_ai_generated", "location", "music", "author_follower_count", "board" ], "type": "object" }, "TikTokProfileSpecific": { "properties": { "display_name_changed_at": { "description": "When the display name last changed, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "friend_count": { "description": "Mutual follows: accounts it follows that follow it back.", "format": "int64", "type": [ "integer", "null" ] }, "is_business_account": { "description": "A TikTok business account (category names its business).", "type": [ "boolean", "null" ] }, "is_shop_seller": { "description": "Sells on TikTok Shop.", "type": [ "boolean", "null" ] }, "language": { "description": "The owner's app language (en, ko), not its posts'.", "type": [ "string", "null" ] }, "liked_post_count": { "description": "Posts it has liked (likes given); null when it keeps them private.", "format": "int64", "type": [ "integer", "null" ] }, "sec_uid": { "description": "TikTok's account key: survives a rename, and handle params take it.", "type": [ "string", "null" ] } }, "required": [ "sec_uid", "friend_count", "liked_post_count", "language", "is_business_account", "is_shop_seller", "display_name_changed_at" ], "type": "object" }, "TikTokShopProductMetrics": { "properties": { "rating_distribution": { "anyOf": [ { "$ref": "#/components/schemas/RatingDistribution" }, { "type": "null" } ], "description": "Reviews per star rating; null when TikTok Shop does not show the breakdown." }, "review_count": { "description": "Reviews behind rating.", "format": "int64", "type": [ "integer", "null" ] }, "sold_count": { "description": "Units sold across every market since the product was listed, as TikTok Shop counts them; null when not shown.", "format": "int64", "type": [ "integer", "null" ] }, "stock_count": { "description": "Units in stock across every variant, as TikTok Shop reports them (it may cap the number it shows); null when hidden.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "sold_count", "review_count", "stock_count", "rating_distribution" ], "type": "object" }, "TikTokShopProductSpecific": { "properties": { "brand": { "description": "Brand name, as TikTok Shop shows it; null when it shows none.", "type": [ "string", "null" ] }, "delivery_max_days": { "description": "Most days TikTok Shop estimates delivery takes in the product's market.", "format": "int64", "type": [ "integer", "null" ] }, "delivery_min_days": { "description": "Fewest days TikTok Shop estimates delivery takes in the product's market.", "format": "int64", "type": [ "integer", "null" ] }, "metrics": { "$ref": "#/components/schemas/TikTokShopProductMetrics", "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero." }, "rating": { "description": "Average review score out of 5 (metrics.review_count reviews behind it); null when unrated.", "format": "double", "type": [ "number", "null" ] }, "shop": { "anyOf": [ { "$ref": "#/components/schemas/TikTokShopShop" }, { "type": "null" } ], "description": "The selling shop's rating and counts (seller names the shop); null when the page shows none." }, "variants": { "description": "The purchasable variants (SKUs: a color, a size, a bundle), in TikTok Shop's order; [] for a product without variants (listed in unknown_fields when the source cannot see them).", "items": { "$ref": "#/components/schemas/ProductVariant" }, "type": "array" } }, "required": [ "brand", "rating", "variants", "delivery_min_days", "delivery_max_days", "metrics", "shop" ], "type": "object" }, "TikTokShopShop": { "properties": { "metrics": { "$ref": "#/components/schemas/TikTokShopShopMetrics", "description": "The shop's counts at fetch time; null = not shown, 0 = zero." }, "rating": { "description": "The shop's average review score out of 5, shown to one decimal; null when the shop is unrated.", "format": "double", "type": [ "number", "null" ] } }, "required": [ "rating", "metrics" ], "type": "object" }, "TikTokShopShopMetrics": { "properties": { "follower_count": { "description": "Accounts following the shop.", "format": "int64", "type": [ "integer", "null" ] }, "product_count": { "description": "Products the shop has on sale.", "format": "int64", "type": [ "integer", "null" ] }, "review_count": { "description": "Reviews of the shop's products, behind its rating.", "format": "int64", "type": [ "integer", "null" ] }, "sold_count": { "description": "Units the shop has sold across all its products and markets, as TikTok Shop counts them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "follower_count", "sold_count", "product_count", "review_count" ], "type": "object" }, "TikTokSoundSpecific": { "properties": { "album": { "description": "Album of a catalogue track; null for original sounds and when not stated.", "type": [ "string", "null" ] }, "is_commercial_music": { "description": "TikTok's own is_commerce_music flag, as served. Not a licence check: TikTok sets it on original sounds and leaves it false on many licensed catalogue tracks, so it does not say a sound is cleared for business accounts or ads.", "type": [ "boolean", "null" ] }, "matched_song": { "anyOf": [ { "$ref": "#/components/schemas/TikTokMatchedSong" }, { "type": "null" } ], "description": "The catalogue song TikTok matched the sound's audio to (for a catalogue track, the track itself): the song behind an original sound. null when TikTok names none." } }, "required": [ "album", "is_commercial_music", "matched_song" ], "type": "object" }, "TikTokSuggestionSpecific": { "properties": { "language": { "description": "The suggestion's language as TikTok labels it, an ISO 639-1 code (en, es); null when TikTok does not say.", "type": [ "string", "null" ] }, "score": { "description": "TikTok's predicted click-through rate for the suggestion, 0 to 1: a relative signal among one query's suggestions; null when not given.", "format": "double", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] } }, "required": [ "language", "score" ], "type": "object" }, "TiktokAdResponse": { "properties": { "data": { "$ref": "#/components/schemas/Ad" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokCommentResponse": { "properties": { "data": { "$ref": "#/components/schemas/Comment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), TikTok's comment ranking (the order its app shows).", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokDownloadResponse": { "properties": { "data": { "$ref": "#/components/schemas/Download" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokEffectResponse": { "properties": { "data": { "$ref": "#/components/schemas/Effect" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokEffect_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok's ranking of the effect's posts (the order its effect page shows).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokFollowersResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), newest follower first (most recently followed).", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokFollowingResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), most recently followed first.", "items": { "$ref": "#/components/schemas/Profile" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokHashtagResponse": { "properties": { "data": { "$ref": "#/components/schemas/Hashtag" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokHashtag_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 10), TikTok's ranking of the hashtag's top posts (the order its embed shows).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokLiked_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), most recent like first (when the account liked each post).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokLiveResponse": { "properties": { "data": { "$ref": "#/components/schemas/Live" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokPlace_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok's ranking of the place's posts (the order its place page shows).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokPlaylist_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), the playlist's own order (its owner's for a playlist, the order TikTok shows a collection's posts in).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokPlaylistsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), the account's playlists in the order it set, then its public collections.", "items": { "$ref": "#/components/schemas/Playlist" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 15), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokRepliesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), TikTok's reply order (the order its app shows: a reply to a reply follows the one it answers).", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_adsResponse": { "properties": { "data": { "description": "Up to limit items (page size 12), last shown, newest first with sort=newest, last shown, oldest first with sort=oldest, most unique users first with sort=popular, relevance (keywords) or newest with sort=relevance.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_hashtagsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok's relevance order for the keyword.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_soundsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_suggestionsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), TikTok's search box order (most likely search first).", "items": { "$ref": "#/components/schemas/Suggestion" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSearch_topResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokSoundResponse": { "properties": { "data": { "$ref": "#/components/schemas/Sound" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokSound_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok's ranking of the sound's posts (the order its sound page shows).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokTop_adsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), Creative Center's rank by rank_by, best first.", "items": { "$ref": "#/components/schemas/Ad" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokTop_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), Creative Center's rank by the rank_by metric (1 = top).", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokTrending_hashtagsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), Creative Center's trend rank (1 = most popular).", "items": { "$ref": "#/components/schemas/Hashtag" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokTrending_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok's explore feed order.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokshopProductResponse": { "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TiktokshopProductsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), TikTok Shop's store order: best-selling first (units sold, most first).", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokshopReviewsResponse": { "properties": { "data": { "description": "Up to limit items (page size 5), TikTok Shop's recommended order (the order its product page shows reviews in).", "items": { "$ref": "#/components/schemas/Review" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TiktokshopSearch_productsResponse": { "properties": { "data": { "description": "Up to limit items (page size 30), TikTok Shop's relevance order.", "items": { "$ref": "#/components/schemas/Product" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "Topic": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform or parsed from display text (\"189M reels\": platform_specific.instagram.post_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "The platform's summary of the topic, as plain text with paragraph breaks (on Instagram, superscript markers ¹, ² cite platform_specific.instagram.source_urls by position). Null when the page has none.", "type": [ "string", "null" ] }, "id": { "description": "Platform-native topic ID; on platforms whose topic pages are keyed by their words (Instagram), the words lowercased and joined by hyphens (harry-potter).", "type": "string" }, "name": { "description": "The topic's title as its page shows it (Harry Potter); null when the source does not show it.", "type": [ "string", "null" ] }, "platform": { "description": "Platform ID (instagram, tiktok, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/TopicPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "related_searches": { "description": "Related searches the platform suggests for the topic, in its order; each is a topic of its own (pass it as url). [] when none.", "items": { "type": "string" }, "type": "array" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "Canonical topic page URL.", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "name", "url", "description", "related_searches", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "TopicPlatformSpecific": { "properties": { "instagram": { "anyOf": [ { "$ref": "#/components/schemas/InstagramTopicSpecific" }, { "type": "null" } ], "description": "An Instagram topic's own fields." }, "pinterest": { "anyOf": [ { "$ref": "#/components/schemas/PinterestTopicSpecific" }, { "type": "null" } ], "description": "A Pinterest topic's own fields." } }, "type": "object" }, "Transcript": { "properties": { "available_languages": { "description": "BCP-47 caption languages the platform offers for this post; [] if none or not listed.", "items": { "type": "string" }, "type": "array" }, "duration_ms": { "description": "Media duration in milliseconds; null when unknown.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Platform-native ID of the post (equals post.id); of an ad library entry, its library ID (equals ad.id).", "type": "string" }, "is_auto_generated": { "description": "True when the track was machine-generated (platform auto-captions or ASR).", "type": "boolean" }, "language": { "description": "BCP-47 language of the returned transcript; null when unknown.", "examples": [ "en" ], "type": [ "string", "null" ] }, "platform": { "description": "Platform the media is hosted on.", "examples": [ "youtube" ], "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/TranscriptPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "segments": { "description": "Timed cues in order; never empty on success.", "items": { "$ref": "#/components/schemas/Segment" }, "type": "array" }, "source": { "description": "captions = platform caption track; asr = speech-to-text on the audio. New values may be added.", "enum": [ "captions", "asr" ], "type": "string" }, "text": { "description": "Full transcript: segment texts joined with single spaces.", "type": "string" }, "url": { "description": "Canonical URL of the post (of an ad library entry, its library page).", "format": "uri", "type": "string" } }, "required": [ "platform", "id", "url", "language", "source", "is_auto_generated", "available_languages", "duration_ms", "segments", "text", "platform_specific" ], "type": "object" }, "TranscriptPlatformSpecific": { "properties": { "reddit": { "anyOf": [ { "$ref": "#/components/schemas/RedditTranscriptSpecific" }, { "type": "null" } ], "description": "A Reddit transcript's own fields." }, "rumble": { "anyOf": [ { "$ref": "#/components/schemas/RumbleTranscriptSpecific" }, { "type": "null" } ], "description": "A Rumble transcript's own fields." } }, "type": "object" }, "Trend": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded, bucketed or capped by the platform (Google's search volume bucket, Pinterest's rounded changes). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "categories": { "description": "Categories the platform files the trend under, as shown (not normalized), the main one first; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "platform": { "description": "Platform ID (pinterest, google, bluesky, …).", "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/TrendPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "rank": { "description": "Position on the requested board, 1 = top; null when the answer is not a board.", "format": "int64", "minimum": 1, "type": [ "integer", "null" ] }, "term": { "description": "The trend's words as the platform shows them, whitespace-trimmed: a search term (Pinterest, Google and Instagram, usually lowercase: pass it as query to the platform's search endpoints) or a topic's headline (Bluesky).", "examples": [ "fall nails" ], "type": "string" }, "thumbnail_url": { "description": "A picture the platform shows beside the trend (a Pin's on Pinterest, a news article's on Google, a post's on Instagram); null when none or not read. Platform CDN URLs can expire.", "format": "uri", "type": [ "string", "null" ] }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them, such as a board's history); null already means unknown for every other field. [] when every list is known.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The trend's public page on the platform: its trend page where one answers logged out (Google Trends' explore page, Instagram's page for the term, Bluesky's feed of the topic's posts), else the platform's search results for it (Pinterest).", "format": "uri", "type": "string" } }, "required": [ "platform", "term", "url", "rank", "categories", "thumbnail_url", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "TrendPlatformSpecific": { "properties": { "google": { "anyOf": [ { "$ref": "#/components/schemas/GoogleTrendSpecific" }, { "type": "null" } ], "description": "A Google Trends trend's own fields." }, "pinterest": { "anyOf": [ { "$ref": "#/components/schemas/PinterestTrendSpecific" }, { "type": "null" } ], "description": "A Pinterest Trends trend's own fields." } }, "type": "object" }, "TrendPoint": { "properties": { "end_at": { "description": "End of the interval, exclusive (the next interval's start_at), RFC 3339 UTC.", "format": "date-time", "type": "string" }, "popularity": { "description": "Searches in the interval relative to the series' peak, 0 to 1 (1 = the peak), as the platform scales them.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "start_at": { "description": "Start of the interval (a week on Pinterest), RFC 3339 UTC.", "format": "date-time", "type": "string" } }, "required": [ "start_at", "end_at", "popularity" ], "type": "object" }, "TruthsocialGroup": { "properties": { "display_name": { "description": "The group's name.", "type": [ "string", "null" ] }, "id": { "description": "The group's ID.", "type": [ "string", "null" ] }, "member_count": { "description": "Members of the group.", "format": "int64", "type": [ "integer", "null" ] }, "slug": { "description": "The group's name in its URL (truthsocial.com/group/).", "type": [ "string", "null" ] }, "url": { "description": "The group's page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "slug", "display_name", "url", "member_count" ], "type": "object" }, "TruthsocialLink": { "properties": { "description": { "description": "The card's summary of the page.", "type": [ "string", "null" ] }, "image_url": { "description": "The card's image.", "format": "uri", "type": [ "string", "null" ] }, "provider": { "description": "The site the card names (www.foxnews.com).", "type": [ "string", "null" ] }, "title": { "description": "The card's headline.", "type": [ "string", "null" ] }, "url": { "description": "The linked page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "url", "title", "description", "image_url", "provider" ], "type": "object" }, "TruthsocialPoll": { "properties": { "expires_at": { "description": "When voting closes (or closed), RFC 3339 UTC; null when it never does.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "The poll's ID.", "type": [ "string", "null" ] }, "is_expired": { "description": "Whether voting has closed.", "type": [ "boolean", "null" ] }, "is_multiple_choice": { "description": "Whether a voter can pick several options.", "type": [ "boolean", "null" ] }, "options": { "description": "The options, in the poll's order.", "items": { "$ref": "#/components/schemas/TruthsocialPollOption" }, "type": "array" }, "vote_count": { "description": "Votes cast, over all options.", "format": "int64", "type": [ "integer", "null" ] }, "voter_count": { "description": "People who voted.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "expires_at", "is_expired", "is_multiple_choice", "vote_count", "voter_count", "options" ], "type": "object" }, "TruthsocialPollOption": { "properties": { "title": { "description": "The option's text.", "type": [ "string", "null" ] }, "vote_count": { "description": "Votes for it.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "title", "vote_count" ], "type": "object" }, "TruthsocialPostRef": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "downvote_count": { "description": "Its downvotes; null unless it was made in a group, the only posts that can be downvoted.", "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Its post ID.", "type": [ "string", "null" ] }, "metrics": { "$ref": "#/components/schemas/PostMetrics", "description": "Its own counts: likes, replies and ReTruths. Null counts when only its id is known." }, "published_at": { "description": "When it was posted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "url": { "description": "Its URL; null when its author is unknown.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "published_at", "author", "metrics", "downvote_count" ], "type": "object" }, "TruthsocialPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TruthsocialPostSpecific": { "properties": { "downvote_count": { "description": "Downvotes. Only posts made in a group can be downvoted; null on any other post. A ReTruth's are its own: the reposted post's are in reblog_of.", "format": "int64", "type": [ "integer", "null" ] }, "edited_at": { "description": "When the text was last edited, RFC 3339 UTC; null when it never was.", "format": "date-time", "type": [ "string", "null" ] }, "group": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialGroup" }, { "type": "null" } ], "description": "The Truth Social group the post was made in; null when it was posted to the author's profile." }, "link": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialLink" }, { "type": "null" } ], "description": "The link preview card the post shows; null when none." }, "poll": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialPoll" }, { "type": "null" } ], "description": "The poll the post carries (the reposted post's, on a ReTruth); null when it has none." }, "quoted_post": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialPostRef" }, { "type": "null" } ], "description": "The post this one quotes; null when it quotes none. Only its id is known when Truth Social no longer shows it." }, "reblog_of": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialPostRef" }, { "type": "null" } ], "description": "The post this one ReTruths (reposts); null when it is not a ReTruth. A ReTruth carries the reposted post's text and media, and its own counts." }, "reply_to": { "anyOf": [ { "$ref": "#/components/schemas/TruthsocialPostRef" }, { "type": "null" } ], "description": "The post this one replies to; null when it is not a reply. Only its id and its author's id are known when Truth Social does not show it." } }, "required": [ "reblog_of", "quoted_post", "reply_to", "group", "link", "edited_at", "downvote_count", "poll" ], "type": "object" }, "TruthsocialPostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), newest first.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TruthsocialProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TruthsocialProfileSpecific": { "properties": { "is_accepting_messages": { "description": "True when the account takes direct messages.", "type": [ "boolean", "null" ] }, "is_bot": { "description": "True when the account says it is automated.", "type": [ "boolean", "null" ] }, "is_discoverable": { "description": "True when the account lets Truth Social suggest it to others; null when it has not said.", "type": [ "boolean", "null" ] }, "is_premium": { "description": "True when Truth Social marks the account as premium.", "type": [ "boolean", "null" ] }, "last_post_at": { "description": "The day of the account's latest post, as midnight UTC RFC 3339 (the platform gives only the day: listed in approximate_fields); null when it has never posted.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "is_bot", "last_post_at", "is_premium", "is_accepting_messages", "is_discoverable" ], "type": "object" }, "TwitchBroadcast": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/TwitchCategory" }, { "type": "null" } ], "description": "The category it was last filed under." }, "id": { "description": "Twitch's ID of the broadcast.", "type": [ "string", "null" ] }, "started_at": { "description": "When it went on air, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "title": { "description": "The title it aired under.", "type": [ "string", "null" ] } }, "required": [ "id", "title", "started_at", "category" ], "type": "object" }, "TwitchCategory": { "properties": { "box_art_url": { "description": "The category's cover image.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "Twitch's ID of the category.", "type": [ "string", "null" ] }, "name": { "description": "Its name (Just Chatting).", "type": [ "string", "null" ] }, "slug": { "description": "Its name in links (twitch.tv/directory/category/just-chatting).", "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "box_art_url" ], "type": "object" }, "TwitchChapter": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/TwitchCategory" }, { "type": "null" } ], "description": "The category; null when Twitch doesn't say." }, "duration_ms": { "description": "How long it lasts, in milliseconds; null on the last part of a broadcast still on air.", "format": "int64", "type": [ "integer", "null" ] }, "position_ms": { "description": "Where in the video it starts, in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "What Twitch shows for it: the category's name.", "type": [ "string", "null" ] } }, "required": [ "title", "position_ms", "duration_ms", "category" ], "type": "object" }, "TwitchLiveSpecific": { "properties": { "base_segment_id": { "description": "Twitch's ID of the recurring slot, the same every week; id names this week's occurrence.", "type": [ "string", "null" ] }, "cancellation_ends_at": { "description": "When the cancellation of this slot lapses, RFC 3339 UTC; null when it is not cancelled.", "format": "date-time", "type": [ "string", "null" ] }, "categories": { "description": "What the slot is filed under, whose first name is category; [] when the channel set none.", "items": { "$ref": "#/components/schemas/TwitchCategory" }, "type": "array" }, "is_cancelled": { "description": "True when the channel cancelled this slot. Twitch still lists it, and its status stays scheduled.", "type": [ "boolean", "null" ] }, "repeat_ends_after_count": { "description": "How many times the slot airs before it stops repeating: 1 is a one-off. 0 or null: the channel set no end, and it repeats every week.", "format": "int64", "type": [ "integer", "null" ] }, "scheduled_end_at": { "description": "When the scheduled broadcast is due to end, RFC 3339 UTC; null when the channel set no end.", "format": "date-time", "type": [ "string", "null" ] }, "vacation": { "anyOf": [ { "$ref": "#/components/schemas/TwitchScheduleBreak" }, { "type": "null" } ], "description": "The channel's latest break from its schedule, as Twitch keeps it: it can be long over. Null when it has none." } }, "required": [ "scheduled_end_at", "is_cancelled", "cancellation_ends_at", "base_segment_id", "categories", "repeat_ends_after_count", "vacation" ], "type": "object" }, "TwitchPostSpecific": { "properties": { "animated_preview_url": { "description": "An image holding frames of the video one above the other, which Twitch's site animates as its preview; null on a clip and while the video is still recording. On an old video the file itself can be gone.", "format": "uri", "type": [ "string", "null" ] }, "author_follower_count": { "description": "The channel's followers at fetch time, when the answer has them.", "format": "int64", "type": [ "integer", "null" ] }, "broadcast_id": { "description": "Twitch's ID of the broadcast the clip was cut from; null on a video.", "type": [ "string", "null" ] }, "broadcast_type": { "description": "What Twitch calls this kind of video: archive (a past broadcast), highlight, upload, premiere_upload, past_premiere or clip.", "type": [ "string", "null" ] }, "category": { "anyOf": [ { "$ref": "#/components/schemas/TwitchCategory" }, { "type": "null" } ], "description": "What it is filed under; null when nothing was set." }, "chapters": { "description": "The parts of a video by category, in order, as Twitch marks them; [] when it marks none and on a clip, and listed in unknown_fields where the answer doesn't have them.", "items": { "$ref": "#/components/schemas/TwitchChapter" }, "type": "array" }, "clip_id": { "description": "Twitch's number for a clip. Its links take the slug, which is id; null on a video.", "type": [ "string", "null" ] }, "clipped_by": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account that made the clip; author is the channel it was clipped from. Null on a video, and when Twitch no longer names the account." }, "content_labels": { "description": "Twitch's content classification labels, its own IDs in its order (MatureGame, Gambling, DebatedSocialIssuesAndPolitics): is_nsfw is true on any of them but politics. [] when it has none, and listed in unknown_fields where the answer doesn't have them.", "items": { "type": "string" }, "type": "array" }, "deletes_at": { "description": "When Twitch will delete the video: past broadcasts expire, RFC 3339 UTC. Null when none is set (highlights and uploads stay) and on a clip.", "format": "date-time", "type": [ "string", "null" ] }, "embed_url": { "description": "The clip's embeddable player; null on a video.", "format": "uri", "type": [ "string", "null" ] }, "is_featured": { "description": "True when the channel features the clip; null on a video.", "type": [ "boolean", "null" ] }, "is_recording": { "description": "True for a past broadcast that is still being recorded because the stream is on air; null on a clip.", "type": [ "boolean", "null" ] }, "is_restricted": { "description": "True when Twitch keeps the video from logged-out viewers, usually for the channel's subscribers: its fields are still answered and media[].url is null. Null on a clip, and where the answer doesn't carry what says so (the video's page, when Twitch's API is down).", "type": [ "boolean", "null" ] }, "renditions": { "description": "The clip's files, one per quality, best first; media[0] is the first. [] on a video, and listed in unknown_fields where a source doesn't see them.", "items": { "$ref": "#/components/schemas/TwitchRendition" }, "type": "array" }, "source_video": { "anyOf": [ { "$ref": "#/components/schemas/TwitchSourceVideo" }, { "type": "null" } ], "description": "The past broadcast the clip was cut from; null on a video, and when Twitch no longer keeps it." }, "vertical_renditions": { "description": "The files of the clip's vertical version, where it has one, best first; [] when it has none and on a video, and listed in unknown_fields where a source doesn't see them.", "items": { "$ref": "#/components/schemas/TwitchRendition" }, "type": "array" } }, "required": [ "broadcast_type", "category", "is_recording", "is_restricted", "content_labels", "deletes_at", "animated_preview_url", "chapters", "clip_id", "embed_url", "is_featured", "clipped_by", "broadcast_id", "source_video", "author_follower_count", "renditions", "vertical_renditions" ], "type": "object" }, "TwitchProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile", "description": "In Twitch's words: `is_verified` is Partner badge, `metrics.post_count` is videos." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TwitchProfileSpecific": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/TwitchCategory" }, { "type": "null" } ], "description": "The category the channel has set, whose name is category." }, "channel_title": { "description": "The title the channel has set for its stream, which stays while it is off air.", "type": [ "string", "null" ] }, "concurrent_viewer_count": { "description": "People watching now; null when off air.", "format": "int64", "type": [ "integer", "null" ] }, "is_affiliate": { "description": "True for a Twitch Affiliate, the program below Partner. Partners are is_verified: the badge Twitch draws is theirs.", "type": [ "boolean", "null" ] }, "is_live": { "description": "True while the channel is on air, false when it is not.", "type": [ "boolean", "null" ] }, "is_mature": { "description": "True when the channel marks itself as for mature audiences.", "type": [ "boolean", "null" ] }, "language": { "description": "The broadcast language the channel has set, lowercase (en).", "type": [ "string", "null" ] }, "last_broadcast": { "anyOf": [ { "$ref": "#/components/schemas/TwitchBroadcast" }, { "type": "null" } ], "description": "The channel's latest broadcast, on air or over; null when it has never streamed." }, "offline_image_url": { "description": "The image the player shows while the channel is off air.", "format": "uri", "type": [ "string", "null" ] }, "primary_color_hex": { "description": "The channel's accent color as hex digits without the #.", "type": [ "string", "null" ] }, "stream": { "anyOf": [ { "$ref": "#/components/schemas/TwitchStream" }, { "type": "null" } ], "description": "The broadcast on air now; null when off air." }, "team": { "anyOf": [ { "$ref": "#/components/schemas/TwitchTeam" }, { "type": "null" } ], "description": "The Twitch team the channel lists first; null when it lists none." } }, "required": [ "is_live", "concurrent_viewer_count", "is_affiliate", "stream", "last_broadcast", "channel_title", "category", "language", "is_mature", "primary_color_hex", "offline_image_url", "team" ], "type": "object" }, "TwitchRendition": { "properties": { "expires_at": { "description": "When url stops working, RFC 3339 UTC, read from Twitch's signed token; null when unknown.", "format": "date-time", "type": [ "string", "null" ] }, "frame_rate": { "description": "Frames per second, when Twitch states it.", "format": "double", "type": [ "number", "null" ] }, "quality": { "description": "Twitch's name for the quality: the height in pixels (1080).", "type": [ "string", "null" ] }, "url": { "description": "The MP4 file, signed and expiring: see expires_at.", "format": "uri", "type": "string" } }, "required": [ "quality", "frame_rate", "url", "expires_at" ], "type": "object" }, "TwitchScheduleBreak": { "properties": { "end_at": { "description": "When the break ends, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "reason": { "description": "Twitch's word for the break, lowercase (vacation).", "type": [ "string", "null" ] }, "start_at": { "description": "When the break starts, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "start_at", "end_at", "reason" ], "type": "object" }, "TwitchScheduleResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), Soonest first, a week per page.", "items": { "$ref": "#/components/schemas/Live" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "TwitchSourceVideo": { "properties": { "id": { "description": "The video's number.", "type": [ "string", "null" ] }, "offset_ms": { "description": "Where in the video the clip starts, in milliseconds; null when Twitch doesn't say.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "The video's title.", "type": [ "string", "null" ] }, "url": { "description": "The video's page.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "title", "offset_ms" ], "type": "object" }, "TwitchStream": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/TwitchCategory" }, { "type": "null" } ], "description": "The category it is filed under." }, "id": { "description": "Twitch's ID of the broadcast, which last_broadcast.id and a clip's broadcast_id also write.", "type": [ "string", "null" ] }, "started_at": { "description": "When it went on air, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "tags": { "description": "The tags the channel set, as shown; [] when none.", "items": { "type": "string" }, "type": "array" }, "thumbnail_url": { "description": "A preview frame of the broadcast, renewed while it airs.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "The broadcast's title.", "type": [ "string", "null" ] }, "type": { "description": "Twitch's word for what is on air (live).", "type": [ "string", "null" ] } }, "required": [ "id", "title", "type", "started_at", "tags", "category", "thumbnail_url" ], "type": "object" }, "TwitchTeam": { "properties": { "display_name": { "description": "Its name as shown.", "type": [ "string", "null" ] }, "id": { "description": "Twitch's ID of the team.", "type": [ "string", "null" ] }, "name": { "description": "Its name in links.", "type": [ "string", "null" ] } }, "required": [ "id", "name", "display_name" ], "type": "object" }, "TwitchTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TwitchVideoResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "TwitchVideosResponse": { "properties": { "data": { "description": "Up to limit items (page size 100), newest first with sort=newest, Twitch's most viewed first, of all time with sort=popular.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "Username": { "properties": { "id": { "description": "The username checked, as its identifier: the same value as username (a name, free or taken, has no other ID in a sign-up check).", "examples": [ "socialtap" ], "type": "string" }, "is_available": { "description": "True when the platform would let someone register the username now; false when it is taken, reserved or breaks the platform's username rules (reason and message say which); null when the platform did not say.", "type": [ "boolean", "null" ] }, "message": { "description": "The platform's own explanation when the username is not available, as its sign-up form shows it (English); null when it is available.", "type": [ "string", "null" ] }, "platform": { "description": "Platform whose sign-up checked the username.", "examples": [ "instagram" ], "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/UsernamePlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "reason": { "description": "Why the username is not available: taken = registered to an account or reserved by the platform (platforms don't tell the two apart); invalid = breaks the platform's username rules (length, characters). Null when it is available or the platform gave no reason. New values may be added.", "enum": [ "taken", "invalid", null ], "type": [ "string", "null" ] }, "suggestions": { "description": "Free usernames the platform's sign-up form proposes for this one, in its order; [] when it proposes none (platforms suggest nothing for short, protected or brand names). Free when proposed: someone can take one at any time.", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The profile page at this username: the account's page when it is taken, the page it would have once registered (until then the platform answers it as not found); null when that address is one of the platform's own pages (instagram.com/explore/), not an account's.", "format": "uri", "type": [ "string", "null" ] }, "username": { "description": "The username checked, without @, in the platform's canonical form (lowercase where usernames are case-insensitive).", "examples": [ "socialtap" ], "type": "string" } }, "required": [ "platform", "id", "username", "url", "is_available", "reason", "message", "suggestions", "platform_specific" ], "type": "object" }, "UsernamePlatformSpecific": { "type": "object" }, "Warning": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "WebPage": { "properties": { "approximate_fields": { "description": "JSON paths of values rounded by the platform (Facebook's \"57K\": metrics.share_count). [] when all exact.", "items": { "type": "string" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/WebPageMetrics", "description": "Counts at fetch time; null = the platform did not say, 0 = it counts none." }, "platform": { "description": "Platform that counted the page's link.", "examples": [ "pinterest" ], "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/WebPagePlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none; a web page has no lists, so always [].", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The web page's link, exactly as sent (not normalized): platforms that count the exact string (Pinterest) count https://example.com and https://example.com/ apart.", "examples": [ "https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/" ], "format": "uri", "type": "string" } }, "required": [ "platform", "url", "metrics", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "WebPageMetrics": { "properties": { "share_count": { "description": "How many times the platform's users shared this link to it, as its own share or save button counts them (Pinterest: saves, each a Pin of the page). 0 when none did, which is also the answer for a page that doesn't exist: platforms count links without opening them. Rounded where the platform shows it rounded (Facebook; see approximate_fields). Null when the platform gave no count.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "share_count" ], "type": "object" }, "WebPagePlatformSpecific": { "type": "object" }, "WebResult": { "properties": { "approximate_fields": { "description": "JSON paths of values parsed from the index's display text or rounded there (profile.metrics.follower_count from \"13K followers\", a profile.bio or post.text the snippet cut short). Filled values are exact and leave the list. [] when all exact.", "items": { "type": "string" }, "type": "array" }, "community": { "anyOf": [ { "$ref": "#/components/schemas/CommunitySummary" }, { "type": "null" } ], "description": "The community the result names (type community: a group, a subreddit): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "details": { "anyOf": [ { "$ref": "#/components/schemas/WebResultDetails" }, { "type": "null" } ], "description": "The item's own record from the platform, fetched when the request asked for it (fill=true): what the platform's endpoint for the kind returns, under the result's type (details.profile). Null when not asked for, when the platform has no endpoint for the kind, or when it did not serve the item (meta.warnings says how many)." }, "hashtag": { "anyOf": [ { "$ref": "#/components/schemas/HashtagSummary" }, { "type": "null" } ], "description": "The hashtag the result names (type hashtag): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "matched_url": { "description": "The page the index listed: the item's own page, or one of its pages that names it (a video of an account, for a profile found through it).", "format": "uri", "type": "string" }, "place": { "anyOf": [ { "$ref": "#/components/schemas/PlaceSummary" }, { "type": "null" } ], "description": "The place the result names (type place): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "platform": { "description": "Platform the item is on.", "examples": [ "instagram" ], "type": "string" }, "platform_specific": { "$ref": "#/components/schemas/WebResultPlatformSpecific", "description": "Fields only this platform has, under its ID (platform_specific.); each null when unknown." }, "position": { "description": "Zero-based rank of the result in the list, across pages: the search engine's order, counting only the results kept.", "format": "int64", "minimum": 0, "type": "integer" }, "post": { "anyOf": [ { "$ref": "#/components/schemas/PostSummary" }, { "type": "null" } ], "description": "The post the result names (type post): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/ProfileSummary" }, { "type": "null" } ], "description": "The account the result names (type profile): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "snippet": { "description": "The index's excerpt of the page: often the item's description and counts as the page stated them when it was indexed, days or weeks ago. Null when the index shows none.", "type": [ "string", "null" ] }, "sound": { "anyOf": [ { "$ref": "#/components/schemas/SoundSummary" }, { "type": "null" } ], "description": "The sound the result names (type sound): what its link and the index's text say of it, completed from details when the result is filled. Null for every other type." }, "title": { "description": "The page's title as the index shows it: often the item's name, but not the item's own field. Null when the index shows none.", "type": [ "string", "null" ] }, "type": { "description": "The kind of item the result names, as the resource that describes it: profile (an account), post, hashtag, sound, place or community. The item's summary is the field of that name, and a filled result's record is details.. A search that finds several kinds (a platform's top search) mixes them in one list. New values may be added as more kinds are searchable; treat unknown values as other.", "enum": [ "profile", "post", "hashtag", "sound", "place", "community" ], "type": "string" }, "unknown_fields": { "description": "JSON paths of lists whose [] means unknown rather than none; [] when every list is known (a result has none yet).", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The item's canonical link on the platform (the account's page for a profile, the post's for a post).", "format": "uri", "type": "string" } }, "required": [ "platform", "type", "position", "url", "matched_url", "title", "snippet", "profile", "post", "hashtag", "sound", "place", "community", "details", "platform_specific", "approximate_fields", "unknown_fields" ], "type": "object" }, "WebResultDetails": { "properties": { "community": { "anyOf": [ { "$ref": "#/components/schemas/Community" }, { "type": "null" } ], "description": "The community's full record (type community), as the platform's endpoint for it returns it now; null for every other type." }, "hashtag": { "anyOf": [ { "$ref": "#/components/schemas/Hashtag" }, { "type": "null" } ], "description": "The hashtag's full record (type hashtag), as the platform's hashtag endpoint returns it now; null for every other type." }, "place": { "anyOf": [ { "$ref": "#/components/schemas/Place" }, { "type": "null" } ], "description": "The place's full record (type place), as the platform's place endpoint returns it now; null for every other type." }, "post": { "anyOf": [ { "$ref": "#/components/schemas/Post" }, { "type": "null" } ], "description": "The post's full record (type post), as the platform's post endpoint returns it now; null for every other type." }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/Profile" }, { "type": "null" } ], "description": "The account's full record (type profile), as the platform's profile endpoint returns it now; null for every other type." }, "sound": { "anyOf": [ { "$ref": "#/components/schemas/Sound" }, { "type": "null" } ], "description": "The sound's full record (type sound), as the platform's sound endpoint returns it now; null for every other type." } }, "required": [ "profile", "post", "hashtag", "sound", "place", "community" ], "type": "object" }, "WebResultPlatformSpecific": { "properties": { "facebook": { "anyOf": [ { "$ref": "#/components/schemas/FacebookWebResultSpecific" }, { "type": "null" } ], "description": "What the index shows of a Facebook account beyond the summary." }, "linkedin": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInWebResultSpecific" }, { "type": "null" } ], "description": "What the index shows of a LinkedIn account beyond the summary." } }, "type": "object" }, "XAffiliation": { "properties": { "badge_url": { "description": "The badge image (the organization's avatar).", "format": "uri", "type": [ "string", "null" ] }, "name": { "description": "The organization's name, as the badge's label shows it.", "type": [ "string", "null" ] }, "url": { "description": "The organization's X profile URL, when the badge links to one.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "name", "url", "badge_url" ], "type": "object" }, "XArticle": { "properties": { "cover_image_url": { "description": "Its cover image.", "format": "uri", "type": [ "string", "null" ] }, "id": { "description": "The article's own ID (x.com/i/article/), not the post's.", "type": [ "string", "null" ] }, "modified_at": { "description": "When it was last changed, RFC 3339 UTC; null when the source does not show it.", "format": "date-time", "type": [ "string", "null" ] }, "preview_text": { "description": "The short preview X shows of the body.", "type": [ "string", "null" ] } }, "required": [ "id", "preview_text", "cover_image_url", "modified_at" ], "type": "object" }, "XCard": { "properties": { "description": { "description": "Its description.", "type": [ "string", "null" ] }, "domain": { "description": "The domain of the linked page.", "type": [ "string", "null" ] }, "image_url": { "description": "Its largest image.", "format": "uri", "type": [ "string", "null" ] }, "title": { "description": "Its headline.", "type": [ "string", "null" ] }, "type": { "description": "X's name for the card (summary, summary_large_image, player, broadcast, …). New values may be added.", "type": [ "string", "null" ] }, "url": { "description": "Where the card leads, when X says.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "type", "url", "title", "description", "domain", "image_url" ], "type": "object" }, "XCommunityResponse": { "properties": { "data": { "$ref": "#/components/schemas/Community" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "XCommunitySpecific": { "properties": { "creator": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The account that created it (it may have passed to another admin since)." }, "invite_policy": { "description": "Who can invite people in: members, moderators, admins or none. New values may be added.", "enum": [ "members", "moderators", "admins", "none", null ], "type": [ "string", "null" ] }, "join_policy": { "description": "How people join: open (anyone), moderator_approval or admin_approval (a request someone approves), invite_only (by invitation). New values may be added.", "enum": [ "open", "moderator_approval", "admin_approval", "invite_only", null ], "type": [ "string", "null" ] }, "join_question": { "description": "The question X asks people who ask to join, as its moderators wrote it; null when it asks none.", "type": [ "string", "null" ] }, "moderator_count": { "description": "People who run it, its admin included, as X counts them.", "format": "int64", "type": [ "integer", "null" ] }, "sample_members": { "description": "The few members X shows on the community's page: a sample chosen by X, not its member list.", "items": { "$ref": "#/components/schemas/ProfileRef" }, "type": "array" }, "search_tags": { "description": "Words its moderators chose for people to find it by; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" } }, "required": [ "join_policy", "join_question", "invite_policy", "creator", "moderator_count", "search_tags", "sample_members" ], "type": "object" }, "XEmbeddedPost": { "properties": { "author": { "$ref": "#/components/schemas/ProfileRef", "description": "Its author." }, "id": { "description": "Its ID, as x.post takes it.", "type": [ "string", "null" ] }, "media": { "description": "Its attachments; [] for a text post.", "items": { "$ref": "#/components/schemas/Media" }, "type": "array" }, "metrics": { "$ref": "#/components/schemas/PostMetrics", "description": "Its counts at fetch time." }, "published_at": { "description": "When it was posted, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "text": { "description": "Its text, with the links written out.", "type": [ "string", "null" ] }, "url": { "description": "Its URL.", "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "url", "text", "published_at", "author", "media", "metrics" ], "type": "object" }, "XMediaVariant": { "properties": { "bitrate": { "description": "Bits per second; null for a playlist, which holds several.", "format": "int64", "type": [ "integer", "null" ] }, "content_type": { "description": "Its type (video/mp4, application/x-mpegURL).", "type": [ "string", "null" ] }, "media_index": { "description": "Which item of media this is a rendition of, from 0.", "format": "int64", "type": "integer" }, "url": { "description": "The file or playlist.", "format": "uri", "type": "string" } }, "required": [ "media_index", "url", "content_type", "bitrate" ], "type": "object" }, "XPoll": { "properties": { "choices": { "description": "The choices, in the post's order.", "items": { "$ref": "#/components/schemas/XPollChoice" }, "type": "array" }, "duration_minutes": { "description": "How long voting runs, in minutes.", "format": "int64", "type": [ "integer", "null" ] }, "ends_at": { "description": "When voting ends or ended, RFC 3339 UTC.", "format": "date-time", "type": [ "string", "null" ] }, "is_final": { "description": "True when voting is over and the counts are final.", "type": [ "boolean", "null" ] }, "total_votes": { "description": "Votes across every choice; null when a choice's count is hidden.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "choices", "total_votes", "ends_at", "duration_minutes", "is_final" ], "type": "object" }, "XPollChoice": { "properties": { "label": { "description": "The choice's text.", "type": [ "string", "null" ] }, "vote_count": { "description": "Exact votes for it; null when X does not show them.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "label", "vote_count" ], "type": "object" }, "XPostCommunity": { "properties": { "id": { "description": "The community's ID, as x.com/i/communities/ shows it.", "type": [ "string", "null" ] }, "name": { "description": "Its name; null when the source does not show it.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": "object" }, "XPostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "XPostSpecific": { "properties": { "article": { "anyOf": [ { "$ref": "#/components/schemas/XArticle" }, { "type": "null" } ], "description": "The X Article this post publishes (its title is in title, its body in text); null when it is an ordinary post." }, "author_metrics": { "anyOf": [ { "$ref": "#/components/schemas/ProfileMetrics" }, { "type": "null" } ], "description": "The author's counts at fetch time (followers, following, posts), which X answers with the post; null when the source does not show them. x.profile has the rest of the account." }, "author_verified_type": { "description": "The kind of verified organization X says the author is (business: the gold check, government: the grey one); null when it is neither. New values may be added; treat unknown values as other.", "enum": [ "business", "government", null ], "type": [ "string", "null" ] }, "card": { "anyOf": [ { "$ref": "#/components/schemas/XCard" }, { "type": "null" } ], "description": "The preview card the post shows for a link or a broadcast; null when it has none, or when X answers the card without its content." }, "cashtags": { "description": "Cashtags in the text, without the $, case kept; [] if none.", "items": { "type": "string" }, "type": "array" }, "community": { "anyOf": [ { "$ref": "#/components/schemas/XPostCommunity" }, { "type": "null" } ], "description": "The community the post was posted to; null when none." }, "conversation_id": { "description": "ID of the post that started the conversation (this post's own ID when it started one); null when the source does not show it.", "type": [ "string", "null" ] }, "edit_post_ids": { "description": "IDs of every version of this post, oldest first, the last one current; one ID when it was never edited, [] when the source does not show them.", "items": { "type": "string" }, "type": "array" }, "is_author_blue_verified": { "description": "True when the author has the blue check of an X Premium subscription; null when unknown. author.is_verified is true for any check.", "type": [ "boolean", "null" ] }, "is_edited": { "description": "True when the post has more than one version; null when the source does not show them.", "type": [ "boolean", "null" ] }, "links": { "description": "The links in the text, written out from X's t.co short links, each once, titled as the post shows them; [] if none.", "items": { "$ref": "#/components/schemas/Link" }, "type": "array" }, "media_variants": { "description": "Every rendition X offers of the post's videos and GIFs (MP4s by bitrate, the HLS playlist); media[].url is the best MP4. [] when the post has none.", "items": { "$ref": "#/components/schemas/XMediaVariant" }, "type": "array" }, "poll": { "anyOf": [ { "$ref": "#/components/schemas/XPoll" }, { "type": "null" } ], "description": "The poll in the post, with exact vote counts; null when it has none." }, "quoted_post": { "anyOf": [ { "$ref": "#/components/schemas/XEmbeddedPost" }, { "type": "null" } ], "description": "The post this one quotes, as X embeds it; null when it quotes none, or when the quoted post is no longer shown." }, "quoted_post_id": { "description": "ID of the post this one quotes; null when it quotes none. Stays set when the quoted post itself is gone.", "type": [ "string", "null" ] }, "reply_to_author": { "anyOf": [ { "$ref": "#/components/schemas/ProfileRef" }, { "type": "null" } ], "description": "The author of the post this one replies to (ID and username, when X says); null when it is not a reply." }, "reply_to_post_id": { "description": "ID of the post this one replies to; null when it is not a reply.", "type": [ "string", "null" ] }, "reposted_post": { "anyOf": [ { "$ref": "#/components/schemas/XEmbeddedPost" }, { "type": "null" } ], "description": "The post this repost shows, with its own author and counts; null when this is no repost. text, media and metrics are that post's." }, "reposted_post_id": { "description": "ID of the post this repost shows; null when this is no repost.", "type": [ "string", "null" ] }, "source": { "description": "The client the post was sent from, as X labels it (Twitter Web Client, Twitter for iPhone, …); null when X does not say, as on most recent posts.", "type": [ "string", "null" ] } }, "required": [ "author_metrics", "is_author_blue_verified", "author_verified_type", "conversation_id", "reply_to_post_id", "reply_to_author", "quoted_post_id", "quoted_post", "reposted_post_id", "reposted_post", "edit_post_ids", "is_edited", "source", "cashtags", "links", "media_variants", "poll", "card", "article", "community" ], "type": "object" }, "XProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "XProfileSpecific": { "properties": { "affiliation": { "anyOf": [ { "$ref": "#/components/schemas/XAffiliation" }, { "type": "null" } ], "description": "The organization X shows the account as affiliated with (its badge beside the name); null when none or when the source does not show it." }, "highlighted_post_count": { "description": "Posts on the profile's Highlights tab; null when the source does not show it.", "format": "int64", "type": [ "integer", "null" ] }, "is_blue_verified": { "description": "True when the account has the blue check of an X Premium subscription, false when it does not; null when unknown. is_verified is true for any check.", "type": [ "boolean", "null" ] }, "is_identity_verified": { "description": "True when X verified the owner's identity with an ID document, false when it did not; null when the source does not show it.", "type": [ "boolean", "null" ] }, "is_possibly_sensitive": { "description": "True when X marks the account's media as possibly sensitive by default, false otherwise; null when unknown.", "type": [ "boolean", "null" ] }, "like_count": { "description": "Posts the account has liked (likes given, not received); null when the source does not show it.", "format": "int64", "type": [ "integer", "null" ] }, "listed_count": { "description": "Public lists the account is a member of; null when the source does not show it.", "format": "int64", "type": [ "integer", "null" ] }, "media_count": { "description": "Posts with photos or videos, as the profile's Media tab counts them; null when the source does not show it.", "format": "int64", "type": [ "integer", "null" ] }, "pinned_post_ids": { "description": "IDs of the posts pinned to the top of the profile, as x.post takes them; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" }, "professional_type": { "description": "The professional account kind the owner chose (business or creator); null for a personal account or when the source does not show it. New values may be added; treat unknown values as other.", "enum": [ "business", "creator", null ], "type": [ "string", "null" ] }, "verified_at": { "description": "When the account's current check was granted, RFC 3339 UTC; null when it has none or the source does not show it.", "format": "date-time", "type": [ "string", "null" ] }, "verified_type": { "description": "The kind of verified organization X says the account is (business: the gold check, government: the grey one); null when it is neither, or when the source does not show it. New values may be added; treat unknown values as other.", "enum": [ "business", "government", null ], "type": [ "string", "null" ] }, "withheld_in_countries": { "description": "ISO 3166-1 alpha-2 codes of the countries where X withholds the account for legal reasons, upper case; [] when none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" } }, "required": [ "verified_type", "is_blue_verified", "is_identity_verified", "verified_at", "listed_count", "media_count", "like_count", "highlighted_post_count", "pinned_post_ids", "professional_type", "affiliation", "is_possibly_sensitive", "withheld_in_countries" ], "type": "object" }, "XSearch_communitiesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "XSearch_hashtagsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "XSearch_postsResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "XSearch_profilesResponse": { "properties": { "data": { "description": "Up to limit items (page size 50), the search engine's ranking (most relevant first).", "items": { "$ref": "#/components/schemas/WebResult" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "YouTubeChapter": { "properties": { "start_ms": { "description": "Start, in ms from the beginning.", "format": "int64", "type": [ "integer", "null" ] }, "title": { "description": "Chapter title.", "type": [ "string", "null" ] } }, "required": [ "title", "start_ms" ], "type": "object" }, "YouTubeHashtagSpecific": { "properties": { "channel_count": { "description": "Channels that posted with the tag, rounded by YouTube (in approximate_fields).", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "channel_count" ], "type": "object" }, "YouTubePlaylistSpecific": { "properties": { "updated_at": { "description": "When its owner last changed it, RFC 3339 UTC; YouTube shows only a date (listed in approximate_fields).", "format": "date-time", "type": [ "string", "null" ] }, "view_count": { "description": "Views YouTube counts for the playlist as a whole.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "view_count", "updated_at" ], "type": "object" }, "YouTubePostSpecific": { "properties": { "author_subscriber_count": { "description": "The channel's subscriber count, rounded by YouTube (in approximate_fields); null when hidden.", "format": "int64", "type": [ "integer", "null" ] }, "category": { "description": "YouTube category (Music, Gaming, …), in English.", "type": [ "string", "null" ] }, "chapters": { "description": "Chapters in playback order; [] when none.", "items": { "$ref": "#/components/schemas/YouTubeChapter" }, "type": "array" }, "description_links": { "description": "Links in the description, in order, deduplicated; [] when none.", "items": { "type": "string" }, "type": "array" }, "is_age_restricted": { "description": "Viewers must sign in to confirm their age; null when the answer does not tell.", "type": [ "boolean", "null" ] }, "is_live_now": { "description": "A live stream on air now.", "type": [ "boolean", "null" ] }, "is_paywalled": { "description": "Must be bought or rented (movies, paid content).", "type": [ "boolean", "null" ] }, "is_unlisted": { "description": "Unlisted: watchable by link, not listed on the channel or in search.", "type": [ "boolean", "null" ] }, "keywords": { "description": "The uploader's tags; [] when none.", "items": { "type": "string" }, "type": "array" }, "live_ended_at": { "description": "When a live stream or premiere ended; null while live or if never live.", "format": "date-time", "type": [ "string", "null" ] }, "live_started_at": { "description": "When a live stream or premiere went on air; null if never live.", "format": "date-time", "type": [ "string", "null" ] }, "scheduled_start_at": { "description": "When a scheduled stream or premiere is due to start; null otherwise.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "category", "keywords", "chapters", "description_links", "is_unlisted", "is_age_restricted", "is_paywalled", "is_live_now", "live_started_at", "live_ended_at", "scheduled_start_at", "author_subscriber_count" ], "type": "object" }, "YouTubeProfileSpecific": { "properties": { "is_business_email_listed": { "description": "True when the channel lists a business email (shown to signed-in users only; the address is not returned); null otherwise, since YouTube shows nothing for a channel without one.", "type": [ "boolean", "null" ] }, "is_official_artist_channel": { "description": "True for an Official Artist Channel (the note badge after its name), false for any other channel; null when the page shows no badge row (YouTube's built-in channels).", "type": [ "boolean", "null" ] }, "is_subscriber_count_hidden": { "description": "True when the channel hides its subscriber count (metrics.follower_count is then null; neither its About panel nor its header shows one), false when YouTube shows it; null when that cannot be told (no About panel or header seen).", "type": [ "boolean", "null" ] }, "keywords": { "description": "The channel's keywords as its owner wrote them, a quoted phrase as one keyword; [] when it has none (listed in unknown_fields when the source cannot see them).", "items": { "type": "string" }, "type": "array" } }, "required": [ "keywords", "is_official_artist_channel", "is_subscriber_count_hidden", "is_business_email_listed" ], "type": "object" }, "YoutubeCommentsResponse": { "properties": { "data": { "description": "Up to limit items (page size 20), newest first with sort=newest, YouTube's Top comments ranking with sort=popular.", "items": { "$ref": "#/components/schemas/Comment" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "YoutubeEngagementResponse": { "properties": { "data": { "$ref": "#/components/schemas/Engagement" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "YoutubePostResponse": { "properties": { "data": { "$ref": "#/components/schemas/Post" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "YoutubePostsResponse": { "properties": { "data": { "description": "Up to limit items (page size 48), newest first with sort=newest, oldest first with sort=oldest, YouTube's Popular order (most viewed first) with sort=popular.", "items": { "$ref": "#/components/schemas/Post" }, "type": "array" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" }, "page": { "$ref": "#/components/schemas/PageInfo" } }, "required": [ "data", "page", "meta" ], "type": "object" }, "YoutubeProfileResponse": { "properties": { "data": { "$ref": "#/components/schemas/Profile" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" }, "YoutubeTranscriptResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transcript" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "required": [ "data", "meta" ], "type": "object" } }, "securitySchemes": { "apiKey": { "in": "header", "name": "x-api-key", "type": "apiKey" }, "session": { "description": "The dashboard session (https://socialtap.dev/dashboard/): a person signed in, acting on one of their accounts (x-account-id; default: their own) with their role in it. Browsers send it; API clients use the API key.", "in": "cookie", "name": "__Host-st_session", "type": "apiKey" } } }, "info": { "description": "SocialTap is the social media scraper API for developers and AI agents. Send a public link, a handle or a search and get live data back in one schema. Failed requests are free. Available now: ads on Facebook, Google, LinkedIn and TikTok; albums on Apple Music and Spotify; comments on Bluesky, Facebook, Instagram, Reddit, Rumble, Snapchat, Threads, TikTok and YouTube; communities on Facebook, Reddit and X; downloads on TikTok; effects on TikTok; embeds on Instagram; engagement stats on Facebook, Instagram, Reddit, Rumble, TikTok and YouTube; events on Facebook; hashtags on Instagram and TikTok; livestreams on TikTok and Twitch; offers on Amazon; places on Facebook and Instagram; playlists on Amazon, Apple Music, Instagram, Pinterest, Spotify and TikTok; podcasts on Spotify; posts on Amazon, Apple Music, Bluesky, Facebook, Instagram, Kick, Kwai, LinkedIn, Pinterest, Reddit, Rumble, Snapchat, SoundCloud, Spotify, Telegram, Threads, TikTok, Truth Social, Twitch, X and YouTube; products on Amazon, Facebook and TikTok Shop; profiles on Amazon, Apple Music, Bluesky, Facebook, Google, Instagram, Komi, Kwai, LinkedIn, Linkme, Linktree, Lnk.Bio, Pillar, Pinterest, Reddit, Rumble, Snapchat, SoundCloud, Spotify, Telegram, Threads, TikTok, Truth Social, Twitch, X and YouTube; reviews on Amazon and TikTok Shop; sounds on Instagram and TikTok; suggestions on Google, Instagram and TikTok; topics on Instagram and Pinterest; transcripts on Facebook, Instagram, Kick, Reddit, Rumble, TikTok, Twitch and YouTube; trends on Pinterest; usernames on Instagram; web pages on Pinterest; web results on Facebook, Instagram, LinkedIn, Telegram, TikTok and X.\n\n**AI agents and coding assistants:** before writing integration code, read [llms.txt](https://socialtap.dev/llms.txt) (how to authenticate, pick an endpoint, paginate and handle errors, plus every endpoint), the [agent guide](https://socialtap.dev/docs/agents/) and the [API reference](https://socialtap.dev/docs/reference/). Every docs page is also Markdown: append `index.md` to its URL or send `Accept: text/markdown`.\n\nAuthenticate with the `x-api-key` header. Branch on `error.code`, never on `message`; retry only the codes an operation's `x-socialtap-retry` lists as retryable ([error codes](https://socialtap.dev/docs/errors/)). Plans do not limit request rate: a per-account runaway ceiling answers `rate_limited` with a `retry-after` header.\n\nEvery operation states its price in `x-socialtap-pricing` (credits per request, or per page for lists), list operations their cursor paging in `x-socialtap-pagination`.\n\nFailed requests and cache hits cost no credits.", "title": "SocialTap API", "version": "1" }, "openapi": "3.1.0", "paths": { "/status.json": { "get": { "description": "Public, no API key. `status` is health from the scheduled canaries: an endpoint is degraded after repeated failed runs and healthy again after several passes; unknown until first checked, and again when the canary has not run recently. `success_rate` is the share of customer requests in the last `success_rate_window_minutes` that got an answer, measured where every request ends (failures on SocialTap's side, including capacity refusals, count against it; requests refused for credits or rate do not count), rounded down; null when there was too little traffic. Cached for 60 seconds.", "operationId": "status.get", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "endpoints": { "items": { "properties": { "id": { "type": "string" }, "last_checked": { "format": "date-time", "type": [ "string", "null" ] }, "measured": { "description": "Requests, success rate and latency between measured_from and measured_to; null when the endpoint had fewer than measured_min_requests requests.", "properties": { "check_requests": { "description": "Of requests, how many were our own scheduled checks.", "minimum": 0, "type": "integer" }, "p50_ms": { "description": "Median time the engine took for a successful answer, ms; null when none was timed.", "minimum": 0, "type": [ "integer", "null" ] }, "p95_ms": { "description": "95th percentile of that time, ms; null when none was timed.", "minimum": 0, "type": [ "integer", "null" ] }, "requests": { "description": "Requests measured: customer requests plus scheduled checks.", "minimum": 0, "type": "integer" }, "success_rate": { "description": "Share of requests that succeeded (0..1, rounded down).", "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "requests", "check_requests", "success_rate", "p50_ms", "p95_ms" ], "type": [ "object", "null" ] }, "since": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "Canary health; unknown until first checked, or when the canary has not run recently.", "enum": [ "healthy", "degraded", "unknown" ], "type": "string" }, "success_rate": { "description": "Real-traffic success rate over the window (0..1, rounded down); null when there was too little traffic.", "maximum": 1, "minimum": 0, "type": [ "number", "null" ] } }, "required": [ "id", "status", "since", "last_checked", "success_rate", "measured" ], "type": "object" }, "type": "array" }, "environment": { "type": "string" }, "generated_at": { "format": "date-time", "type": "string" }, "measured_from": { "description": "Start of every endpoint's measured window; null until the measurement has run.", "format": "date-time", "type": [ "string", "null" ] }, "measured_min_requests": { "description": "Fewest requests an endpoint needs in the window for its measured numbers to be published.", "minimum": 1, "type": "integer" }, "measured_to": { "description": "End of every endpoint's measured window; null until the measurement has run.", "format": "date-time", "type": [ "string", "null" ] }, "success_rate_window_minutes": { "description": "Window of every endpoint's success_rate.", "type": "integer" } }, "required": [ "generated_at", "environment", "success_rate_window_minutes", "measured_from", "measured_to", "measured_min_requests", "endpoints" ], "type": "object" } } }, "description": "Health document" } }, "security": [], "summary": "Live health of every endpoint", "tags": [ "Status" ], "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [], "retry_after_header": "retry-after", "retryable_codes": [] } } }, "/v1/account": { "delete": { "description": "Locks the account at once (every key revoked, the owner's sessions ended, jobs and webhooks stopped) and deletes it for good after `grace_s` (7 days), unless its owner signs in again and chooses it; unspent credits are forfeited. Its people on other accounts stay on those. The owner only, with a fresh sign-in. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "account.delete", "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_id": { "description": "The account being deleted.", "type": "string" }, "credits_forfeited": { "description": "The balance when the deletion was asked for: forfeited, with no refund, when the account is deleted.", "type": "integer" }, "deletes_at": { "description": "When the account is deleted for good, unless its owner signs in before then (which cancels the deletion), RFC 3339 UTC.", "format": "date-time", "type": "string" }, "object": { "description": "Always account_deletion.", "enum": [ "account_deletion" ], "type": "string" }, "requested_at": { "description": "When its deletion was asked for, RFC 3339 UTC.", "format": "date-time", "type": "string" } }, "required": [ "object", "account_id", "requested_at", "deletes_at", "credits_forfeited" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Delete the account (after a grace period)", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Delete the account (after a grace period)", "tags": [ "Account" ], "x-socialtap-auth": { "auth": "session", "role": "owner", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "get": { "description": "The account's balance and plan, the low-balance alert threshold, and the calling key: its scopes, spend limit (with what it used this interval) and expiry. Free; never cached. A pending agent key may call it (and nothing else) to learn when its owner confirmed.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "account.get", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "api_key": { "description": "The key that made this request; null for a dashboard session.", "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user" ], "type": [ "object", "null" ] }, "available": { "description": "Credits new requests can set aside now: balance minus what requests in flight and unfinished jobs hold. For a busy account it may lag concurrent requests by about a second.", "type": "integer" }, "balance": { "description": "Credits the account owns, including those held by requests in flight and unfinished jobs.", "type": "integer" }, "created_at": { "description": "When the account was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "email": { "description": "The owner's email address: sign-in links, receipts and balance alerts go there.", "type": "string" }, "free_credits_skipped": { "description": "Why this account got no free credits when it was confirmed; null when it got them, or isn't confirmed yet. disposable_address: a throwaway mail service. domain_daily_limit, network_daily_limit: too many new accounts today from its email domain, or from its network. mailbox_used: this mailbox already had them. A daily limit is tried again at the next session, on a later day; the others stand. Everything else works as on any account, buying credits included. New values may be added.", "enum": [ "disposable_address", "domain_daily_limit", "network_daily_limit", "mailbox_used" ], "type": [ "string", "null" ] }, "id": { "description": "Account ID (acct_…).", "type": "string" }, "keep_response_bodies": { "description": "Whether each request's answer body is kept, for 7 days (GET /v1/requests/{id}/response); off by default.", "type": "boolean" }, "low_balance_threshold": { "description": "credits.low fires (event and email) when a request takes the balance from above this to at or below it; null when off.", "type": [ "integer", "null" ] }, "max_rps": { "description": "The account's runaway-protection ceiling, in requests per second: a safety limit that stops a runaway client, not a plan limit (plans have no rate limit). Requests above it fail with rate_limited (free) and Retry-After; short bursts above it are admitted (the RateLimit-Policy header states the burst). GET /v1/usage/rate shows how close the account runs to it; ask support to raise it. An account that has never paid has a lower ceiling, which its first payment removes within a minute.", "type": "integer" }, "object": { "description": "Always account.", "enum": [ "account" ], "type": "string" }, "plan": { "description": "Plan ID.", "type": "string" }, "status": { "description": "unverified: created by an agent signup whose owner has not confirmed by email yet (no free credits, live keys pending).", "enum": [ "active", "unverified" ], "type": "string" } }, "required": [ "object", "id", "email", "status", "plan", "balance", "available", "low_balance_threshold", "max_rps", "keep_response_bodies", "api_key", "free_credits_skipped", "created_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get the account, balance and calling key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get the account, balance and calling key", "tags": [ "Account" ], "x-socialtap-auth": { "auth": "key", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "patch": { "description": "low_balance_threshold: credits.low (an event and an email to the owner) fires once each time a request takes the balance from above it to at or below it; credits.depleted fires when the balance reaches 0 (and the owner is emailed, at most once a day, which no setting turns off). keep_response_bodies: keep each request's response (GET /v1/requests/{id}/response). Absent fields keep their value. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.", "operationId": "account.update", "requestBody": { "content": { "application/json": { "schema": { "properties": { "keep_response_bodies": { "description": "true keeps the answer body of every request made from now on up to 1 MB each (a longer one is cut), for 7 days: GET /v1/requests/{id}/response returns it. false stops keeping them; bodies already kept are deleted when their time is up. Takes effect within a minute.", "type": [ "boolean", "null" ] }, "low_balance_threshold": { "description": "Credits; null turns credits.low off. Setting it never fires the event by itself: only a request that crosses it does.", "maximum": 1000000000, "minimum": 0, "type": [ "integer", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "api_key": { "description": "The key that made this request; null for a dashboard session.", "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user" ], "type": [ "object", "null" ] }, "available": { "description": "Credits new requests can set aside now: balance minus what requests in flight and unfinished jobs hold. For a busy account it may lag concurrent requests by about a second.", "type": "integer" }, "balance": { "description": "Credits the account owns, including those held by requests in flight and unfinished jobs.", "type": "integer" }, "created_at": { "description": "When the account was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "email": { "description": "The owner's email address: sign-in links, receipts and balance alerts go there.", "type": "string" }, "free_credits_skipped": { "description": "Why this account got no free credits when it was confirmed; null when it got them, or isn't confirmed yet. disposable_address: a throwaway mail service. domain_daily_limit, network_daily_limit: too many new accounts today from its email domain, or from its network. mailbox_used: this mailbox already had them. A daily limit is tried again at the next session, on a later day; the others stand. Everything else works as on any account, buying credits included. New values may be added.", "enum": [ "disposable_address", "domain_daily_limit", "network_daily_limit", "mailbox_used" ], "type": [ "string", "null" ] }, "id": { "description": "Account ID (acct_…).", "type": "string" }, "keep_response_bodies": { "description": "Whether each request's answer body is kept, for 7 days (GET /v1/requests/{id}/response); off by default.", "type": "boolean" }, "low_balance_threshold": { "description": "credits.low fires (event and email) when a request takes the balance from above this to at or below it; null when off.", "type": [ "integer", "null" ] }, "max_rps": { "description": "The account's runaway-protection ceiling, in requests per second: a safety limit that stops a runaway client, not a plan limit (plans have no rate limit). Requests above it fail with rate_limited (free) and Retry-After; short bursts above it are admitted (the RateLimit-Policy header states the burst). GET /v1/usage/rate shows how close the account runs to it; ask support to raise it. An account that has never paid has a lower ceiling, which its first payment removes within a minute.", "type": "integer" }, "object": { "description": "Always account.", "enum": [ "account" ], "type": "string" }, "plan": { "description": "Plan ID.", "type": "string" }, "status": { "description": "unverified: created by an agent signup whose owner has not confirmed by email yet (no free credits, live keys pending).", "enum": [ "active", "unverified" ], "type": "string" } }, "required": [ "object", "id", "email", "status", "plan", "balance", "available", "low_balance_threshold", "max_rps", "keep_response_bodies", "api_key", "free_credits_skipped", "created_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Update account settings", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Update account settings", "tags": [ "Account" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/account/leave": { "post": { "description": "Takes the signed-in person off the account they act on. The owner can't leave: hand the account over, or delete it. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "account.leave", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "deleted": { "description": "Always true.", "type": "boolean" }, "id": { "type": "string" }, "object": { "description": "The deleted object's type (webhook_endpoint).", "type": "string" } }, "required": [ "object", "id", "deleted" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Leave the account", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Leave the account", "tags": [ "Team" ], "x-socialtap-auth": { "auth": "session", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/account/transfer": { "post": { "description": "Makes a member or admin the owner; the owner becomes an admin, and account email goes to the new owner. The owner only, with a fresh sign-in. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "account.transfer", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "user_id": { "description": "The member who becomes the owner (GET /v1/members). The current owner becomes an admin.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Their verified email address.", "type": "string" }, "is_you": { "description": "Whether this is the signed-in person.", "type": "boolean" }, "joined_at": { "description": "When they joined the account, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "object": { "description": "Always member.", "enum": [ "member" ], "type": "string" }, "role": { "description": "owner: everything, including deleting the account and handing it to someone else (exactly one). admin: billing, keys, webhooks, settings and people, never the owner. member: reads the account and uses the playground with a key it is given; changes nothing.", "enum": [ "owner", "admin", "member" ], "type": "string" }, "user_id": { "description": "The person's ID: change their role or remove them with it.", "type": "string" } }, "required": [ "object", "user_id", "email", "role", "joined_at", "is_you" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Hand the account to another member", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Hand the account to another member", "tags": [ "Team" ], "x-socialtap-auth": { "auth": "session", "role": "owner", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/agent_claims/approve": { "post": { "description": "The approval page calls it. The agent can then collect a key on the account this session acts on, once: its secret exists only in the agent's answer, and the key can never manage the account. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "agent_claims.approve", "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The code the agent shows, or the one in its link.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "object": { "description": "Always agent_claim_decision.", "enum": [ "agent_claim_decision" ], "type": "string" }, "redirect_to": { "description": "An OAuth client: where the browser goes next.", "type": "string" }, "status": { "description": "What was decided.", "enum": [ "approved", "denied" ], "type": "string" } }, "required": [ "object", "status" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Approve an agent's request for a key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Approve an agent's request for a key", "tags": [ "Signup" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/agent_claims/deny": { "post": { "description": "The approval page calls it. The request ends for good, and the agent is told. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "agent_claims.deny", "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The code the agent shows, or the one in its link.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "object": { "description": "Always agent_claim_decision.", "enum": [ "agent_claim_decision" ], "type": "string" }, "redirect_to": { "description": "An OAuth client: where the browser goes next.", "type": "string" }, "status": { "description": "What was decided.", "enum": [ "approved", "denied" ], "type": "string" } }, "required": [ "object", "status" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Refuse an agent's request for a key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Refuse an agent's request for a key", "tags": [ "Signup" ], "x-socialtap-auth": { "auth": "session", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/agent_claims/lookup": { "post": { "description": "The approval page calls it with the code an agent shows its person: what is asking, from where, and what its key could do. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "agent_claims.lookup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The code the agent shows, or the one in its link.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "client_name": { "description": "What the agent calls itself. Nothing verifies it.", "type": "string" }, "created_at": { "description": "When it asked, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "expires_at": { "description": "When the request lapses, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "key_name": { "description": "The label its key will have.", "type": "string" }, "location": { "description": "Roughly where the request came from: city and country, where known. Absent for an OAuth client, like network.", "type": "string" }, "loopback": { "description": "An OAuth client on the person's own computer: the approval goes back to a local port.", "type": "boolean" }, "network": { "description": "The network it came from: the client's IPv4 address or IPv6 /64. Absent for an OAuth client: its request comes through the person's own browser.", "type": "string" }, "object": { "description": "Always agent_claim.", "enum": [ "agent_claim" ], "type": "string" }, "redirect_host": { "description": "An OAuth client: the host the approval goes back to.", "type": "string" }, "scopes": { "description": "What its key may do.", "items": { "type": "string" }, "type": "array" }, "user_code": { "description": "The code the agent shows, to compare. Absent for an OAuth client, which shows none.", "type": "string" } }, "required": [ "object", "key_name", "scopes", "created_at", "expires_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "See an agent's request for a key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "See an agent's request for a key", "tags": [ "Signup" ], "x-socialtap-auth": { "auth": "session", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/agent_signup": { "post": { "deprecated": true, "description": "Deprecated: agents follow /auth.md instead, which emails nobody and also works for an existing account. Send your human's email address and get a key that stays pending until the human confirms by email, which grants the free credits. Agents never get spending power without a human. For an address that already has an account, no keys are made: the owner is emailed a sign-in link to create one in the dashboard, and the answer is 202 with the human signup's object (check your email).\n\n**Auth:** none.", "operationId": "agent_signup.create", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "description": "Your human's email address: they confirm there before the live key works.", "maxLength": 254, "minLength": 3, "type": "string" }, "name": { "description": "Your name as an agent, shown to the human and used as the keys' label: at most 40 ASCII letters, digits, spaces, hyphens, underscores or parentheses, starting with a letter or digit (anything else is invalid_input). Default: \"Agent\".", "maxLength": 100, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "account_id": { "description": "The new account (unverified until the human confirms).", "type": "string" }, "confirmation_expires_at": { "description": "When the confirmation link stops working; then sign up again.", "format": "date-time", "type": "string" }, "email": { "description": "Where the confirmation link was sent.", "type": "string" }, "free_credits": { "description": "Credits the account gets when the human confirms.", "type": "integer" }, "live_key": { "description": "Pending until the human confirms by email; until then it can only read GET /v1/account (poll api_key.status).", "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "secret": { "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.", "type": "string" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user", "secret" ], "type": "object" }, "object": { "description": "Always agent_signup.", "enum": [ "agent_signup" ], "type": "string" } }, "required": [ "object", "account_id", "email", "free_credits", "confirmation_expires_at", "live_key" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Sign up as an agent: a key that works on confirm", "headers": { "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "email": { "description": "Where the link was sent.", "type": "string" }, "expires_at": { "description": "When the link stops working, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "object": { "description": "Always signup.", "enum": [ "signup" ], "type": "string" } }, "required": [ "object", "email", "expires_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "The address already has an account: no keys were made; its owner was emailed a sign-in link to create a key for you in the dashboard. Ask them to check their email.", "headers": { "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [], "summary": "Sign up as an agent: a key that works on confirm", "tags": [ "Signup" ], "x-socialtap-auth": { "auth": "none", "role": "", "scope": "" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/amazon/deal_products": { "get": { "description": "Returns Amazon's Today's Deals on any Amazon marketplace, all deals or one category's, in Amazon's own order. Each product has its deal price and the list or typical price it beats, the deal's type, badge and end time, the share of a lightning deal claimed, and any coupon's price. You also get the title, image, brand and star rating with its exact count.\n\nReturns `{data, page, meta}`: `data` holds up to 100 `Product` items (the shared schema, the same on every platform), Amazon's Today's Deals order (its own ranking, as the grid shows it). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/deal_products/ (Markdown: https://socialtap.dev/docs/reference/amazon/deal_products/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/deal_products/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/deal_products/" }, "operationId": "amazon.deal_products.list", "parameters": [ { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace whose deals to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Prices are that marketplace's, in its currency. Default: the category link's marketplace, else US. A country other than the category link's is refused.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace whose deals to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Prices are that marketplace's, in its currency. Default: the category link's marketplace, else US. A country other than the category link's is refused.", "examples": [ "US" ], "type": "string" } }, { "description": "Only the deals of one category: its browse node ID (172282 is Electronics on amazon.com), or a link that names one: a category link (amazon.com/b?node=172282), a search link filtered to a department, or a Today's Deals link with a department picked (its price and discount filters aren't applied). A product's platform_specific.amazon.categories[].id and a deal's platform_specific.amazon.deal.department_ids are such IDs. Omit for every deal. Browse nodes are each marketplace's own.", "example": "172282", "in": "query", "name": "category", "schema": { "description": "Only the deals of one category: its browse node ID (172282 is Electronics on amazon.com), or a link that names one: a category link (amazon.com/b?node=172282), a search link filtered to a department, or a Today's Deals link with a department picked (its price and discount filters aren't applied). A product's platform_specific.amazon.categories[].id and a deal's platform_specific.amazon.deal.department_ids are such IDs. Omit for every deal. Browse nodes are each marketplace's own.", "examples": [ "172282" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.rating_distribution" ], "attributes": [], "availability": "in_stock", "category": null, "category_id": null, "condition": "new", "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0G2D1R15Q", "max_price": null, "media": [], "original_price": 99.99, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": "Ring", "categories": [], "contributors": [], "deal": { "badge": "60% off", "claimed_percent": null, "coupon_id": null, "coupon_price": null, "department_ids": [ "16333372011", "172282", "493964" ], "ends_at": null, "id": "d0d0a6d6", "label": "Early Black Friday Deal", "original_price_label": "typical", "status": "available", "type": "best_deal" }, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 8694, "rating_distribution": { "five_star_count": 6260, "four_star_count": 696, "one_star_count": 956, "three_star_count": 522, "two_star_count": 261 } }, "parent_asin": null, "rank": null, "rating": 4.2, "ships_from": null, "variants": [] } }, "price": 39.99, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/51kY6VkfPeL.jpg", "title": "Ring Battery Doorbell 2K (newest model), Matte Mocha", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0G2D1R15Q" }, { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.rating_distribution" ], "attributes": [], "availability": "in_stock", "category": null, "category_id": null, "condition": "new", "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0CHDM8VVZ", "max_price": null, "media": [], "original_price": 399, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": "Bambu Lab", "categories": [], "contributors": [], "deal": { "badge": "13% off", "claimed_percent": null, "coupon_id": null, "coupon_price": null, "department_ids": [ "16310091", "16310161" ], "ends_at": null, "id": "23721016", "label": "Limited time deal", "original_price_label": "list", "status": "available", "type": "best_deal" }, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 444, "rating_distribution": { "five_star_count": 355, "four_star_count": 22, "one_star_count": 36, "three_star_count": 27, "two_star_count": 4 } }, "parent_asin": null, "rank": null, "rating": 4.5, "ships_from": null, "variants": [] } }, "price": 349, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/61IXKmM4f9L.jpg", "title": "Bambu Lab P1S 3D Printer, Ready-to-Use FDM 3D Printer | Beginner-Friendly Ecosystem with MakerWorld Model Library, Enclosed CoreXY, High Speed & Precision Printing", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0CHDM8VVZ" }, { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.rating_distribution" ], "attributes": [], "availability": "in_stock", "category": null, "category_id": null, "condition": "new", "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0FQV6LMVX", "max_price": null, "media": [], "original_price": 1199, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": "EF ECOFLOW", "categories": [], "contributors": [], "deal": { "badge": "27% off", "claimed_percent": null, "coupon_id": null, "coupon_price": null, "department_ids": [ "16310091", "16310161", "2972638011" ], "ends_at": null, "id": "ee891d27", "label": "Limited time deal", "original_price_label": "list", "status": "available", "type": "best_deal" }, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 661, "rating_distribution": { "five_star_count": 582, "four_star_count": 40, "one_star_count": 26, "three_star_count": 13, "two_star_count": 0 } }, "parent_asin": null, "rank": null, "rating": 4.7, "ships_from": null, "variants": [] } }, "price": 878.99, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/61XcQS5XuML.jpg", "title": "EF ECOFLOW DELTA 3 Max Portable Power Station, 2048Wh LFP Battery, 2400W | 3400W X-Boost Output, Ultra-Fast 0-80% Charging in 1.13 Hr, Home Backup & RV Camping, Solar Generator (Solar Panel Optional)", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0FQV6LMVX" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/AmazonDeal_productsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Today's Deals with deal price, badge and end time", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.deal_products", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Amazon's Today's Deals order (its own ranking, as the grid shows it)", "page_max": 100, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/offers": { "get": { "description": "Returns every seller's offer of an Amazon product, from its link, short link or ASIN, on any Amazon marketplace. Each offer has the seller with its ID, star rating and rating count, the price and list price, the condition with the seller's notes, the shipping fee and delivery dates, and who ships it. The buy box offer comes first, marked featured when Amazon's offers panel pins it; a product nobody sells right now returns an empty list.\n\nReturns `{data, page, meta}`: `data` holds up to 11 `Offer` items (the shared schema, the same on every platform), The buy box offer first, then every other offer in Amazon's order: by price plus delivery, lowest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/offers/ (Markdown: https://socialtap.dev/docs/reference/amazon/offers/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/offers/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/offers/" }, "operationId": "amazon.offers.list", "parameters": [ { "description": "The product: its link on any Amazon marketplace (amazon.com/dp/B0FQFB8FMG, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /gp/offer-listing/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B0FQFB8FMG, or a book's ISBN-10).", "example": "https://www.amazon.com/Apple-AirPods-Pro-3/dp/B0FQFB8FMG", "in": "query", "name": "url", "required": true, "schema": { "description": "The product: its link on any Amazon marketplace (amazon.com/dp/B0FQFB8FMG, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /gp/offer-listing/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B0FQFB8FMG, or a book's ISBN-10).", "examples": [ "https://www.amazon.com/dp/B0FQFB8FMG" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Offers, prices and delivery are that marketplace's. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Offers, prices and delivery are that marketplace's. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 11, "in": "query", "name": "limit", "schema": { "default": 11, "maximum": 11, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "shipping.earliest_delivery_at", "shipping.latest_delivery_at" ], "availability": "in_stock", "condition": "new", "condition_label": "New", "country_code": "US", "currency": "USD", "id": "B0FQFB8FMG:ATVPDKIKX0DER:new", "is_featured": true, "metrics": { "seller_rating_count": null }, "original_price": 249, "platform": "amazon", "platform_specific": { "amazon": { "condition_note": null, "is_fulfilled_by_amazon": true, "seller_positive_percent": null, "ships_from": "Amazon.com" } }, "price": 199, "product_id": "B0FQFB8FMG", "seller": { "avatar_url": null, "display_name": "Amazon.com", "id": "ATVPDKIKX0DER", "is_verified": null, "url": null, "username": null }, "seller_rating": null, "shipping": { "earliest_delivery_at": "2026-11-15T00:00:00Z", "fee": 0, "is_offered": true, "latest_delivery_at": "2026-11-15T00:00:00Z" }, "title": null, "unknown_fields": [], "url": "https://www.amazon.com/dp/B0FQFB8FMG?smid=ATVPDKIKX0DER" }, { "approximate_fields": [ "shipping.earliest_delivery_at", "shipping.latest_delivery_at" ], "availability": "in_stock", "condition": "used", "condition_label": "Used - Acceptable", "country_code": "US", "currency": "USD", "id": "B0FQFB8FMG:amazon-resale:used-acceptable", "is_featured": false, "metrics": { "seller_rating_count": null }, "original_price": null, "platform": "amazon", "platform_specific": { "amazon": { "condition_note": "Minor packaging damage observed during inspection.", "is_fulfilled_by_amazon": true, "seller_positive_percent": null, "ships_from": "Amazon.com" } }, "price": 183.08, "product_id": "B0FQFB8FMG", "seller": { "avatar_url": null, "display_name": "Amazon Resale", "id": null, "is_verified": null, "url": null, "username": null }, "seller_rating": null, "shipping": { "earliest_delivery_at": "2026-11-15T00:00:00Z", "fee": 0, "is_offered": true, "latest_delivery_at": "2026-11-15T00:00:00Z" }, "title": null, "unknown_fields": [], "url": null }, { "approximate_fields": [ "shipping.earliest_delivery_at", "shipping.latest_delivery_at" ], "availability": "in_stock", "condition": "used", "condition_label": "Used - Good", "country_code": "US", "currency": "USD", "id": "B0FQFB8FMG:amazon-resale:used-good", "is_featured": false, "metrics": { "seller_rating_count": null }, "original_price": null, "platform": "amazon", "platform_specific": { "amazon": { "condition_note": "Item may not come in original packaging.", "is_fulfilled_by_amazon": true, "seller_positive_percent": null, "ships_from": "Amazon.com" } }, "price": 185.07, "product_id": "B0FQFB8FMG", "seller": { "avatar_url": null, "display_name": "Amazon Resale", "id": null, "is_verified": null, "url": null, "username": null }, "seller_rating": null, "shipping": { "earliest_delivery_at": "2026-11-15T00:00:00Z", "fee": 0, "is_offered": true, "latest_delivery_at": "2026-11-15T00:00:00Z" }, "title": null, "unknown_fields": [], "url": null } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "product", "id": "B0FQFB8FMG", "url": "https://www.amazon.com/dp/B0FQFB8FMG" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "end" } } } }, "schema": { "$ref": "#/components/schemas/AmazonOffersResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Every seller's price, condition and delivery for an ASIN", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.offers", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "The buy box offer first, then every other offer in Amazon's order: by price plus delivery, lowest first", "page_max": 11, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "offer", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/product": { "get": { "description": "Returns an Amazon product from its link, short link or ASIN, on any Amazon marketplace. You get the title, the current price with the list price it is discounted from, the seller and who ships it, stock, the star rating with its exact count and breakdown, and the monthly sales badge. It also has the Best Sellers Rank, brand or authors, the bullets and description, every specification, all images and videos, and every variation's ASIN.\n\nReturns `{data, meta}`: `data` is a `Product` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/product/ (Markdown: https://socialtap.dev/docs/reference/amazon/product/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/product/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/product/" }, "operationId": "amazon.product.get", "parameters": [ { "description": "The product: its link on any Amazon marketplace (amazon.com/dp/B0FQFB8FMG, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B0FQFB8FMG, or a book's ISBN-10).", "example": "https://www.amazon.com/Apple-AirPods-Pro-3/dp/B0FQFB8FMG", "in": "query", "name": "url", "required": true, "schema": { "description": "The product: its link on any Amazon marketplace (amazon.com/dp/B0FQFB8FMG, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B0FQFB8FMG, or a book's ISBN-10).", "examples": [ "https://www.amazon.com/dp/B0FQFB8FMG" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Prices, stock and sellers are that marketplace's. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Prices, stock and sellers are that marketplace's. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.rating_distribution", "platform_specific.amazon.metrics.bought_past_month_count" ], "attributes": [ { "name": "Brand", "value": "Apple" }, { "name": "Color", "value": "White" }, { "name": "Ear Placement", "value": "In Ear" } ], "availability": "in_stock", "category": null, "category_id": null, "condition": "new", "condition_label": null, "country_code": "US", "currency": "USD", "description": "WORLD’S BEST IN-EAR ACTIVE NOISE CANCELLATION — Removes up to 2x more unwanted noise than AirPods Pro 2* so you can stay fully immersed in the moment.*\n\nBREAKTHROUGH AUDIO PERFORMANCE — Experience breathtaking, three-dimensional audio with AirPods Pro 3. A new acoustic architectu…", "id": "B0FQFB8FMG", "max_price": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_SL1500_.jpg", "width": null }, { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://m.media-amazon.com/images/I/71dt0UurPZL._AC_SL1500_.jpg", "width": null }, { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://m.media-amazon.com/images/I/61pH6X22khL._AC_SL1500_.jpg", "width": null } ], "original_price": 249, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": "In Stock", "best_sellers_ranks": [], "brand": "Apple", "categories": [], "contributors": [], "deal": null, "features": [ "WORLD’S BEST IN-EAR ACTIVE NOISE CANCELLATION — Removes up to 2x more unwanted noise than AirPods Pro 2* so you can stay fully immersed in the moment.*", "BREAKTHROUGH AUDIO PERFORMANCE — Experience breathtaking, three-dimensional audio with AirPods Pro 3. A new acoustic architecture delivers transformed bass, detailed clarity so you can hear every instrument, and stunningly vivid vocals.", "HEART RATE SENSING — Built-in heart rate sensing lets you track your heart rate and calories burned for up to 50 different workout types.* With iPhone, you will have access to the Move ring, step count, and the new Workout Buddy,* powered by Apple Intelligence.*" ], "is_sponsored": null, "metrics": { "bought_past_month_count": 10000, "offer_count": 11, "rating_count": 17730, "rating_distribution": { "five_star_count": 14007, "four_star_count": 1241, "one_star_count": 1596, "three_star_count": 532, "two_star_count": 355 } }, "parent_asin": null, "rank": null, "rating": 4.4, "ships_from": "Amazon.com", "variants": [] } }, "price": 199, "seller": { "avatar_url": null, "display_name": "Amazon.com", "id": "ATVPDKIKX0DER", "is_verified": null, "url": null, "username": null }, "shipping": { "fee": 0, "is_offered": true }, "thumbnail_url": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_SL1500_.jpg", "title": "Apple AirPods Pro 3 Wireless Earbuds with Active Noise Cancellation", "type": "product", "unknown_fields": [], "url": "https://www.amazon.com/dp/B0FQFB8FMG" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "product", "id": "B0FQFB8FMG", "url": "https://www.amazon.com/dp/B0FQFB8FMG" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/AmazonProductResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Price, rating, monthly sales and specs by ASIN", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.product", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/reviews": { "get": { "description": "Returns the top customer reviews an Amazon product page shows, from the product's link, short link or ASIN, on any Amazon marketplace outside the US. Each review has its star rating, title, full text and language, the reviewer with their profile link, the variation bought, whether the purchase is verified, how many people found it helpful, its photos and videos, and the date and country it was written in.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Review` items (the shared schema, the same on every platform), Amazon's top reviews: the marketplace's own first, then other countries'. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/reviews/ (Markdown: https://socialtap.dev/docs/reference/amazon/reviews/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/reviews/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/reviews/" }, "operationId": "amazon.reviews.list", "parameters": [ { "description": "The product: its link on any Amazon marketplace (amazon.co.uk/dp/B003AIF4Q4, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B003AIF4Q4, or a book's ISBN-10) with country.", "example": "https://www.amazon.co.uk/dp/0735211299", "in": "query", "name": "url", "required": true, "schema": { "description": "The product: its link on any Amazon marketplace (amazon.co.uk/dp/B003AIF4Q4, with or without the title before /dp/, /gp/product/, /gp/aw/d/, /product-reviews/ and the older /exec/obidos/ASIN/ links), a short link (amzn.to, a.co/d/, amzn.eu/d/, amzn.asia/d/, amzn.com), or its ASIN alone (B003AIF4Q4, or a book's ISBN-10) with country.", "examples": [ "https://www.amazon.co.uk/dp/B003AIF4Q4" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: GB (amazon.co.uk), DE, FR, IT, ES, CA, JP, IN, AU, … Each shows its own customers' top reviews first, then top reviews from other countries. Default: the link's marketplace, else US (amazon.com, which shows reviews only to signed-in visitors).", "example": "GB", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: GB (amazon.co.uk), DE, FR, IT, ES, CA, JP, IN, AU, … Each shows its own customers' top reviews first, then top reviews from other countries. Default: the link's marketplace, else US (amazon.com, which shows reviews only to signed-in visitors).", "examples": [ "GB" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 20, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "published_at" ], "author": { "avatar_url": null, "display_name": "A B Hann", "id": "amzn1.account.AFOIQIFVHELUIDZNA3PZAAHUQH6A", "is_verified": null, "url": "https://www.amazon.co.uk/gp/profile/amzn1.account.AFOIQIFVHELUIDZNA3PZAAHUQH6A", "username": null }, "country_code": "GB", "id": "R26NWF54CTYPDH", "is_incentivized": false, "is_verified_purchase": true, "language": "en", "media": [], "metrics": { "helpful_count": 25 }, "platform": "amazon", "platform_specific": {}, "product_id": "0735211299", "published_at": "2026-03-04T00:00:00Z", "rating": 5, "text": "Atomic Habits completely changed the way I think about progress and self-improvement. Instead of focusing on huge life overhauls, it breaks everything down into small, practical changes that actually feel manageable.\n\nWhat I appreciated most is how actionable the advice is. The s…", "title": "Simple Ideas, Powerful Results", "unknown_fields": [], "url": "https://www.amazon.co.uk/gp/customer-reviews/R26NWF54CTYPDH", "variant_id": "1847941834", "variant_title": "Format: Paperback" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://m.media-amazon.com/images/S/amazon-avatars-global/ce2aa141-d825-444f-859e-e735d5e639d2._CR0%2C0%2C500%2C500_SX460_SX48_.jpeg", "display_name": "John M", "id": "amzn1.account.AGRCKXSEGOJY6VKWXVUZBOSJ35SA", "is_verified": null, "url": "https://www.amazon.co.uk/gp/profile/amzn1.account.AGRCKXSEGOJY6VKWXVUZBOSJ35SA", "username": null }, "country_code": "GB", "id": "R2R5XY27STL9YL", "is_incentivized": false, "is_verified_purchase": true, "language": "en", "media": [], "metrics": { "helpful_count": 12 }, "platform": "amazon", "platform_specific": {}, "product_id": "0735211299", "published_at": "2026-09-10T00:00:00Z", "rating": 5, "text": "Atomic Habits has genuinely changed the way I look at several areas of my life. Rather than focusing on dramatic overnight transformations, it helped me understand the power of small, consistent actions and how they gradually shape our identity and future.\n\nOne of the most impact…", "title": "A Powerful Book That Changed My Outlook", "unknown_fields": [], "url": "https://www.amazon.co.uk/gp/customer-reviews/R2R5XY27STL9YL", "variant_id": "1847941834", "variant_title": "Format: Paperback" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": null, "display_name": "Rodrigo Ferreira", "id": "amzn1.account.AECVB7TIUUBFDS43YI24MB2B6ILQ", "is_verified": null, "url": "https://www.amazon.co.uk/gp/profile/amzn1.account.AECVB7TIUUBFDS43YI24MB2B6ILQ", "username": null }, "country_code": "GB", "id": "RQW3OS75ABF74", "is_incentivized": false, "is_verified_purchase": true, "language": "en", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/61ezPtvAdKL._SY500_.jpg", "type": "image", "url": "https://m.media-amazon.com/images/I/61ezPtvAdKL.jpg", "width": null }, { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/517WaERYwEL._SY500_.jpg", "type": "image", "url": "https://m.media-amazon.com/images/I/517WaERYwEL.jpg", "width": null }, { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/61+X8YMvgVL._SY500_.jpg", "type": "image", "url": "https://m.media-amazon.com/images/I/61+X8YMvgVL.jpg", "width": null } ], "metrics": { "helpful_count": 7 }, "platform": "amazon", "platform_specific": {}, "product_id": "0735211299", "published_at": "2026-07-09T00:00:00Z", "rating": 4, "text": "I haven’t finished the entire book yet, but I’ve read enough to understand its core message. The idea that tiny, consistent changes compound into major long‑term transformation is genuinely useful, and it’s helped me pay more attention to small wins I normally overlook. I’ve alre…", "title": "Helpful framework for small improvements, but oversimplifies the mental side of habit change", "unknown_fields": [], "url": "https://www.amazon.co.uk/gp/customer-reviews/RQW3OS75ABF74", "variant_id": "1847941834", "variant_title": "Format: Paperback" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "product", "id": "0735211299", "url": "https://www.amazon.co.uk/dp/0735211299" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "platform_limit" } } } }, "schema": { "$ref": "#/components/schemas/AmazonReviewsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Top customer reviews of a product, by marketplace", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.reviews", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Amazon's top reviews: the marketplace's own first, then other countries'", "page_max": 20, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "review", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/search_products": { "get": { "description": "Returns Amazon's search results for a keyword, on any Amazon marketplace, page by page. Each product has its ASIN, title, price with the list price it is discounted from, image, star rating with the exact number of ratings, and the monthly sales badge. Results that show a brand line also carry the brand, and sponsored results are flagged. Sort by relevance, price, newest or best sellers.\n\nReturns `{data, page, meta}`: `data` holds up to 60 `Product` items (the shared schema, the same on every platform), Amazon's Featured order, sponsored results among them with sort=relevance (the default), Amazon's Newest Arrivals: the most recently listed first with sort=newest, Amazon's Best Sellers order: the most bought first with sort=popular, the lowest price first with sort=price_asc, the highest price first with sort=price_desc. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/search_products/ (Markdown: https://socialtap.dev/docs/reference/amazon/search_products/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/search_products/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/search_products/" }, "operationId": "amazon.search_products.list", "parameters": [ { "description": "What to search for, as typed into Amazon's search box: keywords, a brand, a model or an ISBN. An Amazon search results link searches its keywords on its marketplace.", "example": "wireless earbuds", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for, as typed into Amazon's search box: keywords, a brand, a model or an ISBN. An Amazon search results link searches its keywords on its marketplace.", "examples": [ "wireless earbuds" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to search, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Results, prices and currency are that marketplace's. Default: US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to search, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Results, prices and currency are that marketplace's. Default: US.", "examples": [ "US" ], "type": "string" } }, { "description": "Order of the results. relevance (default): Amazon's Featured order. price_asc, price_desc: the lowest or the highest price first. newest: Amazon's Newest Arrivals. popular: Amazon's Best Sellers order.", "example": "", "in": "query", "name": "sort", "schema": { "default": "relevance", "description": "Order of the results. relevance (default): Amazon's Featured order. price_asc, price_desc: the lowest or the highest price first. newest: Amazon's Newest Arrivals. popular: Amazon's Best Sellers order.", "enum": [ "relevance", "price_asc", "price_desc", "newest", "popular" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 60, "in": "query", "name": "limit", "schema": { "default": 60, "maximum": 60, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.bought_past_month_count" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0H8NFRF3S", "max_price": null, "media": [], "original_price": 199.99, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": false, "metrics": { "bought_past_month_count": 1000, "offer_count": null, "rating_count": 673, "rating_distribution": null }, "parent_asin": null, "rank": null, "rating": 4.9, "ships_from": null, "variants": [] } }, "price": 19.97, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/61rw2e+AtUL._AC_UY654_FMwebp_QL65_.jpg", "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Soft White", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0H8NFRF3S" }, { "approximate_fields": [ "platform_specific.amazon.rating", "platform_specific.amazon.metrics.bought_past_month_count" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0FQFB8FMG", "max_price": null, "media": [], "original_price": 249, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": false, "metrics": { "bought_past_month_count": 10000, "offer_count": null, "rating_count": 17730, "rating_distribution": null }, "parent_asin": null, "rank": null, "rating": 4.4, "ships_from": null, "variants": [] } }, "price": 199, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_UY654_FMwebp_QL65_.jpg", "title": "Apple AirPods Pro 3 Wireless Earbuds with Active Noise Cancellation", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0FQFB8FMG" }, { "approximate_fields": [ "platform_specific.amazon.rating" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0HKS3S2XJ", "max_price": null, "media": [], "original_price": 249.99, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": false, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 363, "rating_distribution": null }, "parent_asin": null, "rank": null, "rating": 4.7, "ships_from": null, "variants": [] } }, "price": 19.99, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://m.media-amazon.com/images/I/61D5ZCSIymL._AC_UY654_FMwebp_QL65_.jpg", "title": "Wireless Earbuds, Bluetooth 6.0 Headphones HiFi Stereo 50H Playback LED Digital Display Ear Buds with ENC Noise Canceling Headset, IPX7 Waterproof Earphones for Gym/Running/Work(Black)", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0HKS3S2XJ" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/AmazonSearch_productsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Products by keyword with price, rating and sales", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.search_products", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Amazon's Featured order, sponsored results among them", "orders": { "newest": "Amazon's Newest Arrivals: the most recently listed first", "popular": "Amazon's Best Sellers order: the most bought first", "price_asc": "the lowest price first", "price_desc": "the highest price first", "relevance": "Amazon's Featured order, sponsored results among them" }, "page_max": 60, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/seller": { "get": { "description": "Returns an Amazon third-party seller from its merchant ID or seller page link, on any Amazon marketplace. You get its name, logo and About text, its positive feedback share, and its star rating with exact rating counts per star for the last month, three months, year and lifetime. It also has the business details the seller must disclose: legal name, address, phone, email, and VAT and trade register numbers where shown.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/seller/ (Markdown: https://socialtap.dev/docs/reference/amazon/seller/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/seller/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/seller/" }, "operationId": "amazon.seller.get", "parameters": [ { "description": "The seller: its merchant ID (A3A7XJ7DLGM1CB, the seller= in its links) or its link on any Amazon marketplace: its page (amazon.com/sp?seller=…), the older /gp/aag/main?seller=, /gp/help/seller/at-a-glance.html?seller= and /shops/… links, or its storefront (amazon.com/s?me=…, /sp/redirect/storefront?seller=…). Sellers have no username.", "example": "https://www.amazon.com/sp?seller=AN8LN2YPKS7DF", "in": "query", "name": "handle", "required": true, "schema": { "description": "The seller: its merchant ID (A3A7XJ7DLGM1CB, the seller= in its links) or its link on any Amazon marketplace: its page (amazon.com/sp?seller=…), the older /gp/aag/main?seller=, /gp/help/seller/at-a-glance.html?seller= and /shops/… links, or its storefront (amazon.com/s?me=…, /sp/redirect/storefront?seller=…). Sellers have no username.", "examples": [ "AN8LN2YPKS7DF" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … A seller's ratings and details are that marketplace's. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … A seller's ratings and details are that marketplace's. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "platform_specific.amazon.seller_feedback.positive_percent", "platform_specific.amazon.seller_feedback.last_30_days.rating", "platform_specific.amazon.seller_feedback.last_90_days.rating" ], "avatar_url": "https://m.media-amazon.com/images/I/31M25Gjck3L.jpg", "banner_url": null, "bio": "Due to Datavision's longstanding relationships with all major manufacturers we are able to offer a broader selection of products than even the largest online retailer.\n\nDatavision is also an Authorized Retailer for all major manufacturers including Apple, Sony, SONOS, Dyson, Sams…", "category": null, "country_code": "US", "created_at": null, "display_name": "DataVision Computer Video", "external_links": [], "id": "AN8LN2YPKS7DF", "is_private": false, "is_verified": null, "location": "55 W 39th Street, NEW YORK, NY, 10018, US", "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "amazon", "platform_specific": { "amazon": { "seller_business": { "address": "55 W 39th Street, NEW YORK, NY, 10018, US", "business_type": null, "customer_service_address": null, "customer_service_phone": "888-888-2087", "email": null, "legal_name": "DataVision Computer Video, Inc.", "phone": null, "trade_register_number": null, "vat_number": null }, "seller_feedback": { "last_12_months": { "rating": 4.1, "rating_count": 178, "rating_distribution": { "five_star_count": 128, "four_star_count": 9, "one_star_count": 36, "three_star_count": 2, "two_star_count": 3 }, "review_count": 178 }, "last_30_days": { "rating": 2.7, "rating_count": 12, "rating_distribution": { "five_star_count": 5, "four_star_count": 0, "one_star_count": 7, "three_star_count": 0, "two_star_count": 0 }, "review_count": 12 }, "last_90_days": { "rating": 3.7, "rating_count": 36, "rating_distribution": { "five_star_count": 22, "four_star_count": 3, "one_star_count": 11, "three_star_count": 0, "two_star_count": 0 }, "review_count": 36 }, "lifetime": { "rating": 4.7, "rating_count": 144093, "rating_distribution": { "five_star_count": 123370, "four_star_count": 11762, "one_star_count": 4515, "three_star_count": 2784, "two_star_count": 1662 }, "review_count": 144086 }, "positive_percent": 77 }, "shop": null } }, "type": "unknown", "unknown_fields": [], "url": "https://www.amazon.com/sp?seller=AN8LN2YPKS7DF", "username": null }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "AN8LN2YPKS7DF", "url": "https://www.amazon.com/sp?seller=AN8LN2YPKS7DF" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/AmazonSellerResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Seller ratings, feedback counts and business details", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.seller", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/shop": { "get": { "description": "Returns an Amazon influencer's storefront from its handle or amazon.com/shop link, on any Amazon marketplace. You get the creator's name, picture, bio, social links and account ID, whether Amazon marks it a Top Creator, its curations with their post counts, and the products it shows as trending with their prices. Its idea lists, a page at a time, come from the Amazon Shop Lists API.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/shop/ (Markdown: https://socialtap.dev/docs/reference/amazon/shop/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/shop/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/shop/" }, "operationId": "amazon.shop.get", "parameters": [ { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @), its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or curations), or its account ID (amzn1.account.…, the id this API returns) or amazon.com/gp/profile/ link.", "example": "sydneydelrey", "in": "query", "name": "handle", "required": true, "schema": { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @), its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or curations), or its account ID (amzn1.account.…, the id this API returns) or amazon.com/gp/profile/ link.", "examples": [ "sydneydelrey" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … A storefront shows that marketplace's prices; Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … A storefront shows that marketplace's prices; Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "avatar_url": "https://m.media-amazon.com/images/I/71D+tmgGHHL._CR0%2C0%2C972%2C972_.jpg", "banner_url": null, "bio": "sharing all of my favorite Amazon finds ᥫ᭡ click the icons below to follow me on socials! all photo & video content is also shoppable x", "category": null, "country_code": null, "created_at": null, "display_name": "sydney del rey", "external_links": [ { "title": "TIKTOK", "url": "https://vm.tiktok.com/ZTFrowSpg/" }, { "title": "YOUTUBE", "url": "https://www.youtube.com/channel/UCWvW1JOQ-nsAinO1jLFgrVA" }, { "title": "PINTEREST", "url": "https://www.pinterest.com/sydneydelrey" } ], "id": "amzn1.account.AFLEV5XW2UDKGVOLTFVTZTVW3ZDQ", "is_private": false, "is_verified": null, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "amazon", "platform_specific": { "amazon": { "seller_business": null, "seller_feedback": null, "shop": { "curations": [ { "id": "bdca11e0-6920-4402-ac72-2f2016ed1e36", "post_count": 14, "thumbnail_url": "https://m.media-amazon.com/images/I/41hpqw-D5tL._US225_SCLZZZZZZZ_.jpg", "title": "SHOES ✨", "url": "https://www.amazon.com/shop/sydneydelrey/curation/bdca11e0-6920-4402-ac72-2f2016ed1e36" }, { "id": "71fad634-5787-4ee1-bc3c-6e3ca23e5eae", "post_count": 109, "thumbnail_url": "https://m.media-amazon.com/images/S/shoppable-media-external-prod-iad-us-east-1/8d48ee6a-0c49-4441-b385-a50fb9d86618/3254e-2233-46c9-89bd-434412530._SX225_SCLZZZZZZZ_.jpeg", "title": "f/w fit try ons", "url": "https://www.amazon.com/shop/sydneydelrey/curation/71fad634-5787-4ee1-bc3c-6e3ca23e5eae" }, { "id": "7e16f5d6-99a7-4277-b498-caffddd25cd5", "post_count": 12, "thumbnail_url": "https://m.media-amazon.com/images/I/41gq2G5kbDL._US225_SCLZZZZZZZ_.jpg", "title": "fall by category 🍂", "url": "https://www.amazon.com/shop/sydneydelrey/curation/7e16f5d6-99a7-4277-b498-caffddd25cd5" } ], "is_top_creator": true, "trending_picks": [ { "asin": "B0HCMQP824", "badge": "Deal", "currency": "USD", "image_url": "https://m.media-amazon.com/images/I/41HROkFYKfL._AC_.jpg", "price": 15.29, "url": "https://www.amazon.com/dp/B0HCMQP824" }, { "asin": "B0H9QNCXRZ", "badge": "Deal", "currency": "USD", "image_url": "https://m.media-amazon.com/images/I/31i0y9mO5GL._AC_.jpg", "price": 19.94, "url": "https://www.amazon.com/dp/B0H9QNCXRZ" }, { "asin": "B0H2CSDFJJ", "badge": "Deal", "currency": "USD", "image_url": "https://m.media-amazon.com/images/I/415s0nFsMDL._AC_.jpg", "price": 13.99, "url": "https://www.amazon.com/dp/B0H2CSDFJJ" } ] } } }, "type": "unknown", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "amzn1.account.AFLEV5XW2UDKGVOLTFVTZTVW3ZDQ", "url": "https://www.amazon.com/shop/sydneydelrey" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/AmazonShopResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Influencer storefront profiles, curations and picks", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.shop", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/shop_lists": { "get": { "description": "Returns an Amazon influencer's idea lists from its storefront handle or amazon.com/shop link, on any Amazon marketplace. Each list has its title, link, cover image, product count, exact heart count, whether it is pinned, and the ASINs of its first products. Lists come newest first, a page at a time, and the list pages on.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Playlist` items (the shared schema, the same on every platform), the storefront's order: the list created or changed most recently first, with the lists the influencer pinned at the top of the first page. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/shop_lists/ (Markdown: https://socialtap.dev/docs/reference/amazon/shop_lists/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/shop_lists/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/shop_lists/" }, "operationId": "amazon.shop_lists.list", "parameters": [ { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @), its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or curations), or its account ID (amzn1.account.…, the id the Amazon Shop API returns) or amazon.com/gp/profile/ link.", "example": "sydneydelrey", "in": "query", "name": "handle", "required": true, "schema": { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @), its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or curations), or its account ID (amzn1.account.…, the id the Amazon Shop API returns) or amazon.com/gp/profile/ link.", "examples": [ "sydneydelrey" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … A storefront shows that marketplace's prices; Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … A storefront shows that marketplace's prices; Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 20, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.amazon.products" ], "description": null, "id": "XYAIGEFWJGML", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": null, "display_name": null, "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "platform": "amazon", "platform_specific": { "amazon": { "heart_count": 27, "is_pinned": true, "product_count": 107, "products": [ { "asin": "B0GVJLT11G", "image_url": "https://m.media-amazon.com/images/I/51rkpKJTMSL._AC_.jpg", "url": "https://www.amazon.com/dp/B0GVJLT11G" }, { "asin": "B0CBV78KG1", "image_url": "https://m.media-amazon.com/images/I/3116aEzGVvL._AC_.jpg", "url": "https://www.amazon.com/dp/B0CBV78KG1" }, { "asin": "B0FDWQ3B2D", "image_url": "https://m.media-amazon.com/images/I/51XQoZ399aL._AC_.jpg", "url": "https://www.amazon.com/dp/B0FDWQ3B2D" } ] } }, "platform_type": "idea list", "thumbnail_url": "https://m.media-amazon.com/images/I/8153xDsodTL._AC_._US550_SCLZZZZZZZ_.jpg", "title": "Holiday home goods", "type": "playlist", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/list/XYAIGEFWJGML" }, { "approximate_fields": [ "platform_specific.amazon.products" ], "description": null, "id": "35KWG9X334D4Q", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": null, "display_name": null, "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "platform": "amazon", "platform_specific": { "amazon": { "heart_count": 203, "is_pinned": true, "product_count": 199, "products": [ { "asin": "B0H8Y7QSW1", "image_url": "https://m.media-amazon.com/images/I/41MHUWP3IbL._AC_.jpg", "url": "https://www.amazon.com/dp/B0H8Y7QSW1" }, { "asin": "B0GPL62DKQ", "image_url": "https://m.media-amazon.com/images/I/31pmcuxsQHL._AC_.jpg", "url": "https://www.amazon.com/dp/B0GPL62DKQ" }, { "asin": "B0F1K1KF8Q", "image_url": "https://m.media-amazon.com/images/I/418Krr3QwqL._AC_.jpg", "url": "https://www.amazon.com/dp/B0F1K1KF8Q" } ] } }, "platform_type": "idea list", "thumbnail_url": "https://m.media-amazon.com/images/I/81uZzOaydpL._AC_._US550_SCLZZZZZZZ_.jpg", "title": "thanksgiving fitspo", "type": "playlist", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/list/35KWG9X334D4Q" }, { "approximate_fields": [ "platform_specific.amazon.products" ], "description": null, "id": "3C0MB7YWND2K7", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": null, "display_name": null, "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "platform": "amazon", "platform_specific": { "amazon": { "heart_count": 501, "is_pinned": true, "product_count": 59, "products": [ { "asin": "B0F4CSXK79", "image_url": "https://m.media-amazon.com/images/I/41SaX31kWLL._AC_.jpg", "url": "https://www.amazon.com/dp/B0F4CSXK79" }, { "asin": "B0GXYS8B3N", "image_url": "https://m.media-amazon.com/images/I/215DmLHX1wL._AC_.jpg", "url": "https://www.amazon.com/dp/B0GXYS8B3N" }, { "asin": "B0C5R54TMC", "image_url": "https://m.media-amazon.com/images/I/41eoI7oRyiL._AC_.jpg", "url": "https://www.amazon.com/dp/B0C5R54TMC" } ] } }, "platform_type": "idea list", "thumbnail_url": "https://m.media-amazon.com/images/I/71noBGE95aL._AC_._US550_SCLZZZZZZZ_.jpg", "title": "my amazon boot collection", "type": "playlist", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/list/3C0MB7YWND2K7" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": null, "url": "https://www.amazon.com/shop/sydneydelrey" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/AmazonShop_listsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Influencer idea lists with product counts and products", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.shop_lists", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the storefront's order: the list created or changed most recently first, with the lists the influencer pinned at the top of the first page", "page_max": 20, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "playlist", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/shop_posts": { "get": { "description": "Returns an Amazon influencer's storefront videos and shoppable photos from its handle or amazon.com/shop link, on any Amazon marketplace. Each post has its link, image, exact heart count, whether it is pinned, and the ASINs of the products it tags; videos add their title, length, stream and captions. Posts come a page at a time, and the list pages on.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Post` items (the shared schema, the same on every platform), the storefront's: newest first within each tab, after the posts the influencer pinned; type=all lists the videos, then the photos. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\nIn Amazon's words: `metrics.like_count` is hearts.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/shop_posts/ (Markdown: https://socialtap.dev/docs/reference/amazon/shop_posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/shop_posts/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/shop_posts/" }, "operationId": "amazon.shop_posts.list", "parameters": [ { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @) or its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or lists), or its account ID (amzn1.account.…, the id the Amazon Shop API returns) or amazon.com/gp/profile/ link.", "example": "sydneydelrey", "in": "query", "name": "handle", "required": true, "schema": { "description": "The influencer's storefront: its handle (sydneydelrey, the name after /shop/ in its link, any case, with or without the @) or its link on any Amazon marketplace (amazon.com/shop/sydneydelrey, or a link to one of its photos, videos or lists), or its account ID (amzn1.account.…, the id the Amazon Shop API returns) or amazon.com/gp/profile/ link.", "examples": [ "sydneydelrey" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace to read, by country: US (amazon.com), GB (amazon.co.uk), DE, CA, IN, … Amazon shows a creator's storefront on other marketplaces too. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Which posts: all (default: the videos, then the photos), video (the Videos tab) or photo (the Photos tab). Each comes newest first, after the ones the influencer pinned.", "example": "video", "in": "query", "name": "type", "schema": { "default": "all", "description": "Which posts: all (default: the videos, then the photos), video (the Videos tab) or photo (the Photos tab). Each comes newest first, after the ones the influencer pinned.", "enum": [ "all", "video", "photo" ], "examples": [ "video" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 20, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "duration_ms", "media[].duration_ms" ], "author": { "avatar_url": null, "display_name": "sydney del rey", "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "coauthors": [], "duration_ms": 13000, "hashtags": [], "id": "amzn1.vse.video.06f941e7892544b88b70d6dceccb9f75", "is_nsfw": null, "is_pinned": false, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": 13000, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/71zBDXAfzuL.jpg", "type": "video", "url": "https://m.media-amazon.com/images/S/vse-vms-transcoding-artifact-us-east-1-prod/3f39ab0a-1c38-4793-95e8-84e0ac36cb89/default.vertical.jobtemplate.hls.m3u8", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": 3, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "amazon", "platform_specific": { "amazon": { "caption_tracks": [ { "language": "en", "url": "https://m.media-amazon.com/images/S/vse-vms-closed-captions-artifact-us-east-1-prod/closedCaptions/914c778f-c109-4c59-a938-9490a69df65b.vtt" } ], "products": [ { "asin": "B0H1KZ971L", "image_url": "https://m.media-amazon.com/images/I/31eFzhWptZL._AC_.jpg", "url": "https://www.amazon.com/dp/B0H1KZ971L" } ] } }, "platform_type": "video", "published_at": null, "text": null, "thumbnail_url": "https://m.media-amazon.com/images/I/71zBDXAfzuL.jpg", "title": "Cutest fall shoes", "type": "video", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/video/amzn1.vse.video.06f941e7892544b88b70d6dceccb9f75" }, { "approximate_fields": [ "duration_ms", "media[].duration_ms" ], "author": { "avatar_url": null, "display_name": "sydney del rey", "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "coauthors": [], "duration_ms": 12000, "hashtags": [], "id": "amzn1.vse.video.0268c2451115439da062daabeeeaa5c3", "is_nsfw": null, "is_pinned": false, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": 12000, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/B1wSa5vdPsL.jpg", "type": "video", "url": "https://m.media-amazon.com/images/S/vse-vms-transcoding-artifact-us-east-1-prod/ffa8185f-135a-43e3-9c06-2ee586932bf2/default.vertical.jobtemplate.hls.m3u8", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": 4, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "amazon", "platform_specific": { "amazon": { "caption_tracks": [ { "language": "en", "url": "https://m.media-amazon.com/images/S/vse-vms-closed-captions-artifact-us-east-1-prod/closedCaptions/a4105c6b-ff9c-4c3d-8de0-40979387ba53.vtt" } ], "products": [ { "asin": "B0GXYZZQV7", "image_url": "https://m.media-amazon.com/images/I/215DmLHX1wL._AC_.jpg", "url": "https://www.amazon.com/dp/B0GXYZZQV7" }, { "asin": "B0C5R54TMC", "image_url": "https://m.media-amazon.com/images/I/41eoI7oRyiL._AC_.jpg", "url": "https://www.amazon.com/dp/B0C5R54TMC" }, { "asin": "B0FL26334T", "image_url": "https://m.media-amazon.com/images/I/31QTHBsDpqL._AC_.jpg", "url": "https://www.amazon.com/dp/B0FL26334T" } ] } }, "platform_type": "video", "published_at": null, "text": null, "thumbnail_url": "https://m.media-amazon.com/images/I/B1wSa5vdPsL.jpg", "title": "Knee high boots I loveee", "type": "video", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/video/amzn1.vse.video.0268c2451115439da062daabeeeaa5c3" }, { "approximate_fields": [ "duration_ms", "media[].duration_ms" ], "author": { "avatar_url": null, "display_name": "sydney del rey", "id": null, "is_verified": null, "url": "https://www.amazon.com/shop/sydneydelrey", "username": "sydneydelrey" }, "coauthors": [], "duration_ms": 15000, "hashtags": [], "id": "amzn1.vse.video.0c05663ba13d416e9312c6d750ed8cac", "is_nsfw": null, "is_pinned": false, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": 15000, "expires_at": null, "height": null, "thumbnail_url": "https://m.media-amazon.com/images/I/71F4pVkSj7L.jpg", "type": "video", "url": "https://m.media-amazon.com/images/S/vse-vms-transcoding-artifact-us-east-1-prod/fc109474-4e87-4722-855c-0b782c25f91f/default.vertical.jobtemplate.hls.m3u8", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": 3, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "amazon", "platform_specific": { "amazon": { "caption_tracks": [ { "language": "en", "url": "https://m.media-amazon.com/images/S/vse-vms-closed-captions-artifact-us-east-1-prod/closedCaptions/cb17c115-bb41-470e-a684-d2f6b7fbdd0d.vtt" } ], "products": [ { "asin": "B0HBQPNWGF", "image_url": "https://m.media-amazon.com/images/I/41DxBh9NtVL._AC_.jpg", "url": "https://www.amazon.com/dp/B0HBQPNWGF" }, { "asin": "B0G3PNFZNS", "image_url": "https://m.media-amazon.com/images/I/41g8qPygidL._AC_.jpg", "url": "https://www.amazon.com/dp/B0G3PNFZNS" }, { "asin": "B0HJQXL7WZ", "image_url": "https://m.media-amazon.com/images/I/41493s3kcgL._AC_.jpg", "url": "https://www.amazon.com/dp/B0HJQXL7WZ" } ] } }, "platform_type": "video", "published_at": null, "text": null, "thumbnail_url": "https://m.media-amazon.com/images/I/71F4pVkSj7L.jpg", "title": "New fall tops you'll love!", "type": "video", "unknown_fields": [], "url": "https://www.amazon.com/shop/sydneydelrey/video/amzn1.vse.video.0c05663ba13d416e9312c6d750ed8cac" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": null, "url": "https://www.amazon.com/shop/sydneydelrey" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/AmazonShop_postsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Influencer storefront videos and photos with tagged products", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.shop_posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the storefront's: newest first within each tab, after the posts the influencer pinned; type=all lists the videos, then the photos", "page_max": 20, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/amazon/top_products": { "get": { "description": "Returns Amazon's Best Sellers of a category, ranked from the top, from its department, browse node or Best Sellers link, on any Amazon marketplace. Each product has its rank, ASIN, title, image, current price, star rating and exact rating count, and a book's author. The same category's New Releases come back the same way.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Product` items (the shared schema, the same on every platform), Amazon's rank in the list (1 = top). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/amazon/top_products/ (Markdown: https://socialtap.dev/docs/reference/amazon/top_products/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/amazon/top_products/index.md)", "url": "https://socialtap.dev/docs/reference/amazon/top_products/" }, "operationId": "amazon.top_products.list", "parameters": [ { "description": "The category: its department's slug as Amazon's Best Sellers links write it (electronics, books, or ce-de on Amazon Germany), optionally with a browse node after a slash (electronics/12097478011), the browse node alone (12097478011), or the list's link itself (amazon.com/gp/bestsellers/electronics/12097478011, a /zgbs/ link, or a New Releases, Movers & Shakers, Most Wished For or Gift Ideas link). A product's platform_specific.amazon.best_sellers_ranks[].category_id is one of these.", "example": "electronics", "in": "query", "name": "category", "required": true, "schema": { "description": "The category: its department's slug as Amazon's Best Sellers links write it (electronics, books, or ce-de on Amazon Germany), optionally with a browse node after a slash (electronics/12097478011), the browse node alone (12097478011), or the list's link itself (amazon.com/gp/bestsellers/electronics/12097478011, a /zgbs/ link, or a New Releases, Movers & Shakers, Most Wished For or Gift Ideas link). A product's platform_specific.amazon.best_sellers_ranks[].category_id is one of these.", "examples": [ "electronics" ], "maxLength": 2048, "type": "string" } }, { "description": "Which of the category's lists: best_sellers (the most sold), new_releases (the best-selling new and upcoming products), movers_and_shakers (the biggest sales rank gains in a day), most_wished_for (the most added to wish lists) or gift_ideas (the most bought as gifts). Amazon shows no products in the last three today. Default: the link's list, else best_sellers.", "example": "new_releases", "in": "query", "name": "list", "schema": { "description": "Which of the category's lists: best_sellers (the most sold), new_releases (the best-selling new and upcoming products), movers_and_shakers (the biggest sales rank gains in a day), most_wished_for (the most added to wish lists) or gift_ideas (the most bought as gifts). Amazon shows no products in the last three today. Default: the link's list, else best_sellers.", "enum": [ "best_sellers", "new_releases", "movers_and_shakers", "most_wished_for", "gift_ideas" ], "examples": [ "new_releases" ], "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace whose list to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Departments and their slugs are each marketplace's own. Default: the link's marketplace, else US.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Amazon marketplace whose list to read, by country: US (amazon.com), GB (amazon.co.uk), DE, JP, IN, … Departments and their slugs are each marketplace's own. Default: the link's marketplace, else US.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.amazon.rating" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B08JHCVHTY", "max_price": null, "media": [], "original_price": null, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 281899, "rating_distribution": null }, "parent_asin": null, "rank": 1, "rating": 4.4, "ships_from": null, "variants": [] } }, "price": 11.99, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://images-na.ssl-images-amazon.com/images/I/31YHGbJsldL._AC_UL900_SR900,600_.png", "title": "blink plus plan with monthly auto-renewal", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B08JHCVHTY" }, { "approximate_fields": [ "platform_specific.amazon.rating" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0DCH8VDXF", "max_price": null, "media": [], "original_price": null, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 20075, "rating_distribution": null }, "parent_asin": null, "rank": 2, "rating": 4.5, "ships_from": null, "variants": [] } }, "price": 19, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://images-na.ssl-images-amazon.com/images/I/513OSdW4elL._AC_UL900_SR900,600_.jpg", "title": "Apple EarPods Headphones with USB-C Plug, Wired Ear Buds with Built-in Remote to Control Music, Phone Calls, and Volume", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0DCH8VDXF" }, { "approximate_fields": [ "platform_specific.amazon.rating" ], "attributes": [], "availability": null, "category": null, "category_id": null, "condition": null, "condition_label": null, "country_code": "US", "currency": "USD", "description": null, "id": "B0GJTFXNRX", "max_price": null, "media": [], "original_price": null, "platform": "amazon", "platform_specific": { "amazon": { "availability_label": null, "best_sellers_ranks": [], "brand": null, "categories": [], "contributors": [], "deal": null, "features": [], "is_sponsored": null, "metrics": { "bought_past_month_count": null, "offer_count": null, "rating_count": 13061, "rating_distribution": null }, "parent_asin": null, "rank": 3, "rating": 4.6, "ships_from": null, "variants": [] } }, "price": 23, "seller": null, "shipping": { "fee": null, "is_offered": null }, "thumbnail_url": "https://images-na.ssl-images-amazon.com/images/I/61Qd9Z9caRL._AC_UL900_SR900,600_.jpg", "title": "Apple AirTag (2nd Generation): Tracker for Keychain, Wallet, and More; Locator with Sound; Simple One-Tap Setup with iPhone or iPad; Key Finder with up to 1.5X Precision Finding Range", "type": "product", "unknown_fields": [ "media", "attributes", "platform_specific.amazon.contributors" ], "url": "https://www.amazon.com/dp/B0GJTFXNRX" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "amazon", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/AmazonTop_productsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Top 100 products of any category, ranked", "tags": [ "Amazon" ], "x-socialtap-endpoint": "amazon.top_products", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Amazon's rank in the list (1 = top)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/api_keys": { "get": { "description": "The account's keys, newest first, revoked ones included; never their secrets. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "api_keys.list", "parameters": [ { "description": "Keys per page (default and maximum 100).", "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor of the previous page.", "in": "query", "name": "cursor", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "This page's items.", "items": { "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "page": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages" ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" } }, "required": [ "data", "page", "meta" ], "type": "object" } } }, "description": "List API keys", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "List API keys", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "post": { "description": "Creates a key with the given scopes, spend limit, expiry and IP allowlist. The secret is in this answer only: store it now. A key never gets a scope its creator lacks. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "api_keys.create", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expires_at": { "description": "RFC 3339, in the future. Default: never; made with an API key, that key's expiry (never later).", "format": "date-time", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (203.0.113.0/24, 2001:db8::/32). Default: [] (any); made with an API key, that key's allowlist (every entry within it).", "items": { "maxLength": 64, "type": "string" }, "maxItems": 50, "type": "array" }, "mode": { "description": "live, the only mode: test mode was retired on 2026-11-09, so \"test\" is invalid_input. Every key spends credits.", "enum": [ "live" ], "type": "string" }, "name": { "description": "Your label for the key. Default: \"API key\".", "maxLength": 100, "type": "string" }, "scopes": { "description": "Default: endpoints, jobs and account:read. Only an admin credential creates keys, and a key never gets a scope its creator lacks.", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array" }, "spend_limit": { "description": "Default: none; made with an API key, that key's own (a key never creates a looser one).", "properties": { "amount": { "description": "Most credits the key may spend per interval; above it, requests fail with spend_limit_reached.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" } }, "required": [ "amount", "interval" ], "type": [ "object", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "secret": { "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.", "type": "string" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user", "secret" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Create an API key", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Create an API key", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/api_keys/{id}": { "delete": { "description": "Revokes a key for good (a key may revoke itself), every secret it has (during a rotation, the previous one too), and with it every key with the admin scope that this key created, gave admin or rotated, and those keys' in turn, all at once: a leaked admin key's copies don't outlive it. The answer lists them (`also_revoked`) and the keys below it without admin, which keep working (`left_standing`), as do webhook endpoints: review them after a leak. A key can't revoke a key above it, which would revoke itself: forbidden, reason revoking_own_ancestor (use the dashboard, or rotate_secret). They stop working within a minute everywhere, each with its own `api_key.revoked` event; revoking it again changes nothing. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.", "operationId": "api_keys.revoke", "parameters": [ { "description": "Key ID (key_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "also_revoked": { "description": "The keys with the admin scope this key created, gave admin or rotated, and those keys' in turn, revoked with it.", "items": { "properties": { "id": { "description": "Key ID (key_…).", "type": "string" }, "name": { "description": "Its label.", "type": "string" }, "prefix": { "description": "The secret's first characters.", "type": "string" }, "scopes": { "description": "What it may call.", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" } }, "required": [ "id", "name", "prefix", "scopes" ], "type": "object" }, "type": "array" }, "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "left_standing": { "description": "The keys without admin below it, which keep working: review them after a leak, and revoke the ones that shouldn't stay.", "items": { "properties": { "id": { "description": "Key ID (key_…).", "type": "string" }, "name": { "description": "Its label.", "type": "string" }, "prefix": { "description": "The secret's first characters.", "type": "string" }, "scopes": { "description": "What it may call.", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" } }, "required": [ "id", "name", "prefix", "scopes" ], "type": "object" }, "type": "array" }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user", "also_revoked", "left_standing" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Revoke an API key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Revoke an API key", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "get": { "description": "One key and its spend this interval; never its secret. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "api_keys.get", "parameters": [ { "description": "Key ID (key_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get an API key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get an API key", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "patch": { "description": "Changes a key's name, scopes, spend limit, expiry or IP allowlist; absent fields keep their value. Takes effect within a minute everywhere. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.", "operationId": "api_keys.update", "parameters": [ { "description": "Key ID (key_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expires_at": { "description": "New expiry (RFC 3339, in the future); null: never expires.", "format": "date-time", "type": [ "string", "null" ] }, "ip_allowlist": { "description": "New allowlist; [] or null: any IP.", "items": { "maxLength": 64, "type": "string" }, "maxItems": 50, "type": [ "array", "null" ] }, "name": { "description": "New label.", "maxLength": 100, "type": [ "string", "null" ] }, "scopes": { "description": "New scopes (never more than the caller's own).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "maxItems": 5, "minItems": 1, "type": [ "array", "null" ] }, "spend_limit": { "description": "New spend limit; null removes it.", "properties": { "amount": { "description": "Most credits the key may spend per interval; above it, requests fail with spend_limit_reached.", "maximum": 1000000000, "minimum": 1, "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" } }, "required": [ "amount", "interval" ], "type": [ "object", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Update an API key", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Update an API key", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/api_keys/{id}/rotate_secret": { "post": { "description": "Issues a new secret for the same key (same ID, settings and spend), shown once: store it now. The current secret keeps working for `previous_secret_expires_in` seconds, so you can deploy the new one without downtime, but only for calls that need no admin scope (others: forbidden, reason previous_secret). 0 stops it, and rotating again ends the oldest secret, within a minute everywhere: at most two secrets work. A rotation keeps the key, its jobs and every key it made: after a leak, revoke the key instead. A key may rotate itself, or a key it could have created; rotating another key puts that key below it. In the dashboard, a rotation frees the key from any key above it. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "api_keys.rotate_secret", "parameters": [ { "description": "Key ID (key_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "previous_secret_expires_in": { "description": "Seconds the key's current secret keeps working after the new one is issued, at most 7 days; 0 stops it now. Default: 1 day.", "maximum": 604800, "minimum": 0, "type": [ "integer", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "created_at": { "description": "When the key was created, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "created_by_key": { "description": "The API key (key_…) that last created this key, gave it the admin scope or rotated it: revoking that key also revokes this one if this one has admin. Null when none did, or a person has rotated it in the dashboard since.", "type": [ "string", "null" ] }, "created_by_user": { "description": "The person (GET /v1/members user_id) who created this key in the dashboard, or whose key created it. They may have left the account since. Null when no person did (an operator, or a key from before this was recorded).", "type": [ "string", "null" ] }, "dashboard": { "description": "true for the account's built-in dashboard key: the dashboard's playground runs as it (so its requests are logged, counted and billed like any key's). Nobody holds its secret, so it works only from the signed-in dashboard. Only its spend_limit can be changed (to cap what the playground spends live); renaming, rescoping, restricting, rotating or revoking it is forbidden (details.reason dashboard_key). It is made on first use and revoked with the account.", "type": "boolean" }, "expires_at": { "description": "When the key stops working, RFC 3339 UTC; null when it never expires.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Key ID (key_…): manage the key with it. It is not the secret.", "type": "string" }, "ip_allowlist": { "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.", "items": { "type": "string" }, "type": "array" }, "last_used_at": { "description": "About when the key was last used (updated at most hourly); null when never.", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Your label for the key.", "type": "string" }, "object": { "description": "Always api_key.", "enum": [ "api_key" ], "type": "string" }, "prefix": { "description": "The secret's first characters, to recognize it.", "type": "string" }, "previous_secret_expires_at": { "description": "Until then the secret this key had before its last rotation works too (rotate_secret), RFC 3339 UTC; null when none does.", "format": "date-time", "type": [ "string", "null" ] }, "revoked_at": { "description": "When the key was revoked; null while it is not.", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "What the key may call: endpoints (data endpoints), jobs (create, read and cancel jobs; includes jobs:read), jobs:read (read jobs and their results), account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).", "items": { "enum": [ "endpoints", "jobs", "jobs:read", "account:read", "admin" ], "type": "string" }, "type": "array" }, "secret": { "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.", "type": "string" }, "spend_limit": { "description": "The key's spend limit and what it used this interval; null when the key has none.", "properties": { "amount": { "description": "Most credits the key may spend per interval.", "type": "integer" }, "interval": { "description": "Calendar day or month, UTC.", "enum": [ "day", "month" ], "type": "string" }, "resets_at": { "description": "Start of the next interval, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "used": { "description": "Credits the key spent this interval, plus what its requests in flight hold.", "type": "integer" } }, "required": [ "amount", "interval", "used", "resets_at" ], "type": [ "object", "null" ] }, "status": { "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.", "enum": [ "active", "pending", "expired", "revoked" ], "type": "string" } }, "required": [ "object", "id", "name", "status", "prefix", "scopes", "spend_limit", "expires_at", "ip_allowlist", "created_at", "last_used_at", "revoked_at", "dashboard", "previous_secret_expires_at", "created_by_key", "created_by_user", "secret" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Rotate an API key's secret", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Rotate an API key's secret", "tags": [ "API keys" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/applemusic/album": { "get": { "description": "Returns an Apple Music album, single or EP from its link or ID in any country's store, with every track's ISRC, the label, UPC and genres. It also has the credited artists, full-size cover, release date, copyright, Apple's editorial notes, audio formats, each track's length and preview, more releases by the artist and the album's other versions. Legacy iTunes links work too.\n\nReturns `{data, meta}`: `data` is a `Album` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/album/ (Markdown: https://socialtap.dev/docs/reference/applemusic/album/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/album/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/album/" }, "operationId": "applemusic.album.get", "parameters": [ { "description": "The album: its link (music.apple.com/us/album/lover/1468058165), with or without the slug and the store, on music.apple.com, geo.music.apple.com or itunes.apple.com; or its ID alone (1468058165). A track's link (with ?i=) names a track: the Apple Music Track API reads it.", "example": "https://music.apple.com/us/album/lover/1468058165", "in": "query", "name": "url", "required": true, "schema": { "description": "The album: its link (music.apple.com/us/album/lover/1468058165), with or without the slug and the store, on music.apple.com, geo.music.apple.com or itunes.apple.com; or its ID alone (1468058165). A track's link (with ?i=) names a track: the Apple Music Track API reads it.", "examples": [ "https://music.apple.com/us/album/lover/1468058165" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: an album has its own title language, track list and links per store, and can be missing from one. Default: the store in the link, else us.", "example": "us", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: an album has its own title language, track list and links per store, and can be missing from one. Default: the store in the link, else us.", "examples": [ "us" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "released_at" ], "artist_name": "Taylor Swift", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null } ], "copyrights": [ { "text": "℗ 2019 Taylor Swift", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/49/3d/ab/493dab54-f920-9043-6181-80993b8116c9/19UMGIM53909.rgb.jpg/3900x3900bb.jpg", "description": "There’s a reason Taylor Swift sounds so confident and cool on Lover, her seventh album and the most free-spirited yet. She’s in love—pure, steady, starry-eyed, shout-it-from-the-rooftops love. Arriving 13 years after her eponymous debut album—and following a string of songs that …", "duration_ms": 3711368, "genres": [ "Pop" ], "id": "1468058165", "is_explicit": false, "label": "Taylor Swift", "metrics": { "track_count": 18 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "content_rating": null, "editorial_summary": "A love letter to love itself.", "is_complete": true, "is_mastered_for_itunes": true, "is_prerelease": false, "more_by_artist": [ { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/6000x6000bb.jpg", "duration_ms": null, "id": "1440933849", "is_explicit": false, "kind": "album", "released_at": "2017-11-10T00:00:00Z", "title": "reputation", "track_count": 15, "url": "https://music.apple.com/us/album/reputation/1440933849" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a4/86/59/a486593a-53c9-1c2a-5122-8f25339f7359/24UMGIM44778.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "1742057774", "is_explicit": true, "kind": "album", "released_at": "2024-04-19T00:00:00Z", "title": "THE TORTURED POETS DEPARTMENT: THE ANTHOLOGY", "track_count": 31, "url": "https://music.apple.com/us/album/the-tortured-poets-department-the-anthology/1742057774" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/b5/80/dc/b580dca0-349d-036b-e09b-bd849f6affd8/20UMGIM64216.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "1528112358", "is_explicit": true, "kind": "album", "released_at": "2020-07-24T00:00:00Z", "title": "folklore (deluxe version)", "track_count": 17, "url": "https://music.apple.com/us/album/folklore-deluxe-version/1528112358" } ], "other_versions": [], "rank": null, "storefront": "us" } }, "released_at": "2019-08-23T00:00:00Z", "title": "Lover", "tracks": [ { "artist_name": "Taylor Swift", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null } ], "disc_number": 1, "duration_ms": 170651, "id": "1468058169", "is_explicit": false, "isrc": "USUG11901471", "metrics": { "view_count": null }, "play_url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/9c/e2/97/9ce2976a-b1c8-aa80-3e94-f4562cbad53e/mzaf_13898706762824220632.plus.aac.ep.m4a", "title": "I Forgot That You Existed", "track_number": 1, "url": "https://music.apple.com/us/album/i-forgot-that-you-existed/1468058165?i=1468058169" }, { "artist_name": "Taylor Swift", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null } ], "disc_number": 1, "duration_ms": 178426, "id": "1468058171", "is_explicit": false, "isrc": "USUG11901472", "metrics": { "view_count": null }, "play_url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/44/af/81/44af8168-9609-1b85-5048-ada08dceacf3/mzaf_5595361395314573470.plus.aac.ep.m4a", "title": "Cruel Summer", "track_number": 2, "url": "https://music.apple.com/us/album/cruel-summer/1468058165?i=1468058171" }, { "artist_name": "Taylor Swift", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null } ], "disc_number": 1, "duration_ms": 221300, "id": "1468058173", "is_explicit": false, "isrc": "USUG11901473", "metrics": { "view_count": null }, "play_url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview211/v4/e0/db/47/e0db47b0-7f70-0631-0414-cd4777d2fb3e/mzaf_6008069204816798831.plus.aac.ep.m4a", "title": "Lover", "track_number": 3, "url": "https://music.apple.com/us/album/lover/1468058165?i=1468058173" } ], "type": "album", "unknown_fields": [], "upc": "00602508005275", "url": "https://music.apple.com/us/album/lover/1468058165" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 334, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "album", "id": "1468058165", "url": "https://music.apple.com/us/album/lover/1468058165" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicAlbumResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Tracklist with ISRCs, label and UPC", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.album", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "album", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/artist": { "get": { "description": "Returns an Apple Music artist from its link or ID in any country's store, with its bio, genres, origin, top songs and albums. It also has the picture and banner, whether it is a person or a group, when it was born or formed, and its page's latest release, singles and EPs, music videos, playlists and similar artists, each with its ID, link, artwork and date.\n\nReturns `{data, meta}`: `data` is a `Profile` object (Apple Music calls it a artist) (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/artist/ (Markdown: https://socialtap.dev/docs/reference/applemusic/artist/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/artist/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/artist/" }, "operationId": "applemusic.artist.get", "parameters": [ { "description": "The artist: its link (music.apple.com/us/artist/taylor-swift/159260351, with or without the slug and the store, any of its section pages such as /top-songs or /see-all, on music.apple.com, geo.music.apple.com or itunes.apple.com) or the number in that link (159260351). Apple Music artists have no username.", "example": "159260351", "in": "query", "name": "handle", "required": true, "schema": { "description": "The artist: its link (music.apple.com/us/artist/taylor-swift/159260351, with or without the slug and the store, any of its section pages such as /top-songs or /see-all, on music.apple.com, geo.music.apple.com or itunes.apple.com) or the number in that link (159260351). Apple Music artists have no username.", "examples": [ "159260351" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: the same artist has its own bio language, sections and links per store. Default: the store in the link, else us.", "example": "us", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: the same artist has its own bio language, sections and links per store. Default: the store in the link, else us.", "examples": [ "us" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "banner_url": "https://is1-ssl.mzstatic.com/image/thumb/Features221/v4/a1/15/69/a11569c5-ad98-8244-db89-508129f379d6/9b2c00c3-0828-4828-b3e5-0f96e9c2650d.png/4320x1080sr.jpg", "bio": "The country world feigned surprise when, after three albums of Music Row-indebted songcraft, Taylor Swift formally embraced pop on 2012’s Red. But no one should have been shocked: Any 14-year-old capable of persuading her parents to move from suburban Pennsylvania to Nashville fo…", "category": null, "country_code": null, "created_at": null, "display_name": "Taylor Swift", "external_links": [], "id": "159260351", "is_private": null, "is_verified": null, "location": "West Reading, PA, United States", "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "albums": [ { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "6814997249", "is_explicit": true, "kind": "album", "released_at": "2026-09-24T00:00:00Z", "title": "The Life of a Showgirl: The Encore", "track_count": 16, "url": "https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/47/8a/b8/478ab8ac-d134-bad3-f700-364c83323bc6/26UMGIM11621.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "1875381397", "is_explicit": false, "kind": "album", "released_at": "2026-02-13T00:00:00Z", "title": "Opalite (Official Music Video Extended Versions) - Single", "track_count": 4, "url": "https://music.apple.com/us/album/opalite-official-music-video-extended-versions-single/1875381397" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/0e/e5/c7/0ee5c717-114f-f4e8-9f7c-e92dd6eb9152/25UM1IM74420.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "1850496031", "is_explicit": true, "kind": "album", "released_at": "2025-11-07T00:00:00Z", "title": "The Life of a Showgirl + Acoustic Collection", "track_count": 19, "url": "https://music.apple.com/us/album/the-life-of-a-showgirl-acoustic-collection/1850496031" } ], "amg_artist_id": null, "born_or_formed": "December 13, 1989", "editorial_summary": "Favorite Taylor’s artist page for updates on The Life of a Showgirl.", "genres": [ "Pop" ], "is_group": false, "latest_release": { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/89/98/98/8998984f-9a80-c3e1-d59d-e6a6db859e0c/26UM1IM31403.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "6821937445", "is_explicit": false, "kind": "album", "released_at": "2026-10-16T00:00:00Z", "title": "Patient Zero - Single", "track_count": 3, "url": "https://music.apple.com/us/album/patient-zero-single/6821937445" }, "music_videos": [ { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Video221/v4/02/21/39/022139aa-083d-21c1-f0b9-cb7dc630dc98/26UM1IM22083.crop.jpg/3701x1912mv.jpg", "duration_ms": 312384, "id": "6816241368", "is_explicit": false, "kind": "music_video", "released_at": "2026-09-28T00:00:00Z", "title": "Patient Zero", "track_count": null, "url": "https://music.apple.com/us/music-video/patient-zero/6816241368" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Video211/v4/19/2e/ca/192ecabc-b8d2-a613-06af-d608c1037642/26UM1IM22083.crop.jpg/3701x1912mv.jpg", "duration_ms": 312384, "id": "6818017941", "is_explicit": false, "kind": "music_video", "released_at": "2026-09-24T00:00:00Z", "title": "Patient Zero", "track_count": null, "url": "https://music.apple.com/us/music-video/patient-zero/6818017941" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Video211/v4/e1/ef/ce/e1efced7-7023-bcaf-d157-0492240aa10c/26UM1IM28169.crop.jpg/1912x1072mv.jpg", "duration_ms": 492139, "id": "6818017943", "is_explicit": false, "kind": "music_video", "released_at": "2026-09-24T00:00:00Z", "title": "Patient Zero (Expanded Video)", "track_count": null, "url": "https://music.apple.com/us/music-video/patient-zero-expanded-video/6818017943" } ], "playlists": [ { "artist_name": "Apple Music Pop", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1080x1080SC.FPESS05.jpg?l=en-US", "duration_ms": null, "id": "pl.3950454ced8c45a3b0cc693c2a7db97b", "is_explicit": null, "kind": "playlist", "released_at": null, "title": "Taylor Swift Essentials", "track_count": null, "url": "https://music.apple.com/us/playlist/taylor-swift-essentials/pl.3950454ced8c45a3b0cc693c2a7db97b" }, { "artist_name": "Apple Music Pop", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1080x1080SC.MVESS05.jpg?l=en-US", "duration_ms": null, "id": "pl.6929cc16ba9e48878fcabb6af6412d0a", "is_explicit": null, "kind": "playlist", "released_at": null, "title": "Taylor Swift Video Essentials", "track_count": null, "url": "https://music.apple.com/us/playlist/taylor-swift-video-essentials/pl.6929cc16ba9e48878fcabb6af6412d0a" }, { "artist_name": "Apple Music Pop", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1080x1080SC.FPSL03.jpg?l=en-US", "duration_ms": null, "id": "pl.57891bdd1bc840948374f1c4cbe9c840", "is_explicit": null, "kind": "playlist", "released_at": null, "title": "Taylor Swift’s Eras Tour Set List", "track_count": null, "url": "https://music.apple.com/us/playlist/taylor-swifts-eras-tour-set-list/pl.57891bdd1bc840948374f1c4cbe9c840" } ], "similar_artists": [ { "artist_name": null, "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/76/ca/e2/76cae283-f3ba-aa7f-6256-1817e9b5179f/ami-identity-2d92b3a772aa3368c092544fed8cac42-2026-06-26T22-33-16.704Z_cropped.png/2155x2155bb.jpg", "duration_ms": null, "id": "602767352", "is_explicit": null, "kind": "artist", "released_at": null, "title": "Lorde", "track_count": null, "url": "https://music.apple.com/us/artist/lorde/602767352" }, { "artist_name": null, "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/06/f0/41/06f0418f-97d3-34f8-f0a3-3acc37964d89/ami-identity-b7ce039aac2c803c4620ff4ff18920ca-2026-08-06T15-12-54.044Z_cropped.png/3750x3750bb.jpg", "duration_ms": null, "id": "412778295", "is_explicit": null, "kind": "artist", "released_at": null, "title": "Ariana Grande", "track_count": null, "url": "https://music.apple.com/us/artist/ariana-grande/412778295" }, { "artist_name": null, "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/47/79/63/47796327-5841-8691-ac9a-9e56e8e9d782/ami-identity-9dc79b57efd6f0e1ede00c6af8f8954c-2025-02-14T03-00-28.587Z_cropped.png/820x820bb.jpg", "duration_ms": null, "id": "280215834", "is_explicit": null, "kind": "artist", "released_at": null, "title": "Selena Gomez", "track_count": null, "url": "https://music.apple.com/us/artist/selena-gomez/280215834" } ], "singles": [ { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/89/98/98/8998984f-9a80-c3e1-d59d-e6a6db859e0c/26UM1IM31403.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "6821937445", "is_explicit": false, "kind": "album", "released_at": "2026-10-16T00:00:00Z", "title": "Patient Zero - Single", "track_count": 3, "url": "https://music.apple.com/us/album/patient-zero-single/6821937445" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/ae/c1/15/aec11538-c395-b88e-b0f9-7b5b07b8e676/ticket.zkazzkhn.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "6778230429", "is_explicit": false, "kind": "album", "released_at": "2026-06-12T00:00:00Z", "title": "I Knew It, I Knew You (From \"Toy Story 5\") - Single", "track_count": 3, "url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5-single/6778230429" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2b/14/dc/2b14dc4d-5173-7b38-b0ff-1c30daf5fa32/26UMGIM37308.rgb.jpg/3000x3000bb.jpg", "duration_ms": null, "id": "1888604488", "is_explicit": false, "kind": "album", "released_at": "2026-03-31T00:00:00Z", "title": "Elizabeth Taylor", "track_count": 4, "url": "https://music.apple.com/us/album/elizabeth-taylor/1888604488" } ], "storefront": "us", "top_songs": [ { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg", "duration_ms": 225868, "id": "6814997425", "is_explicit": false, "kind": "song", "released_at": "2026-09-24T00:00:00Z", "title": "Patient Zero", "track_count": null, "url": "https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg", "duration_ms": 178186, "id": "6775527443", "is_explicit": false, "kind": "song", "released_at": "2026-06-05T00:00:00Z", "title": "I Knew It, I Knew You (From \"Toy Story 5\")", "track_count": null, "url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5/6775527442?i=6775527443" }, { "artist_name": "Taylor Swift", "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg", "duration_ms": 226074, "id": "1833328840", "is_explicit": false, "kind": "song", "released_at": "2025-10-03T00:00:00Z", "title": "The Fate of Ophelia", "track_count": null, "url": "https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840" } ] } }, "type": "person", "unknown_fields": [], "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 434, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "159260351", "url": "https://music.apple.com/us/artist/taylor-swift/159260351" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicArtistResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Bio, origin, genres, top songs and albums", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.artist", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/search_albums": { "get": { "description": "Searches Apple Music albums, singles and EPs by keyword in any country's store and returns them a page at a time, with label, UPC and track count. Each has the credited artists with their IDs, full-size cover, release date, copyright, genres, explicit rating, audio formats, Apple's notes and its Mastered for iTunes badge. The Apple Music Album API returns the tracks.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Album` items (the shared schema, the same on every platform), Apple Music's own relevance order for the query. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/search_albums/ (Markdown: https://socialtap.dev/docs/reference/applemusic/search_albums/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/search_albums/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/search_albums/" }, "operationId": "applemusic.search_albums.list", "parameters": [ { "description": "What to search for: an album's title, an artist's name, or both together, in any language. Apple matches it as its web player's search box does.", "example": "lover", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for: an album's title, an artist's name, or both together, in any language. Apple matches it as its web player's search box does.", "examples": [ "lover" ], "maxLength": 500, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "JP", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "released_at" ], "artist_name": "Taylor Swift", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null } ], "copyrights": [ { "text": "℗ 2019 Taylor Swift", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/49/3d/ab/493dab54-f920-9043-6181-80993b8116c9/19UMGIM53909.rgb.jpg/3900x3900bb.jpg", "description": "There’s a reason Taylor Swift sounds so confident and cool on Lover, her seventh album and the most free-spirited yet. She’s in love—pure, steady, starry-eyed, shout-it-from-the-rooftops love. Arriving 13 years after her eponymous debut album—and following a string of songs that …", "duration_ms": null, "genres": [ "Pop" ], "id": "1468058165", "is_explicit": false, "label": "Taylor Swift", "metrics": { "track_count": 18 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "content_rating": null, "editorial_summary": "A love letter to love itself.", "is_complete": true, "is_mastered_for_itunes": true, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": null, "storefront": "us" } }, "released_at": "2019-08-23T00:00:00Z", "title": "Lover", "tracks": [], "type": "album", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "00602508005275", "url": "https://music.apple.com/us/album/lover/1468058165" }, { "approximate_fields": [ "released_at" ], "artist_name": "vaultboy", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/7d/2d/2d/7d2d2da3-ca61-3cea-6478-fddbc1a92f6d/49a6d979-37fe-4612-9ce0-4dbd71b4bd43_file_cropped.png/2000x2000bb.jpg", "display_name": "vaultboy", "id": "1542387120", "is_verified": null, "url": "https://music.apple.com/us/artist/vaultboy/1542387120", "username": null } ], "copyrights": [ { "text": "℗ 2026 broke", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/8a/fc/30/8afc3056-fd3b-3ba4-18b0-042e28b12576/612891173772.jpg/1400x1400bb.jpg", "description": null, "duration_ms": null, "genres": [ "Pop" ], "id": "6798022501", "is_explicit": true, "label": "broke", "metrics": { "track_count": 1 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "lossless", "lossy-stereo" ], "content_rating": "explicit", "editorial_summary": null, "is_complete": true, "is_mastered_for_itunes": false, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": null, "storefront": "us" } }, "released_at": "2026-08-14T00:00:00Z", "title": "LOVER - Single", "tracks": [], "type": "single", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "612891173772", "url": "https://music.apple.com/us/album/lover-single/6798022501" }, { "approximate_fields": [ "released_at" ], "artist_name": "Park Hyo Shin", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features211/v4/58/01/5f/58015f0a-bc1f-5814-080b-8edc678e95ea/mzl.aktvsodt.jpg/4000x4000bb.jpg", "display_name": "Park Hyo Shin", "id": "292946954", "is_verified": null, "url": "https://music.apple.com/us/artist/park-hyo-shin/292946954", "username": null } ], "copyrights": [ { "text": "℗ 2019 (주)글러브엔터테인먼트, under license to Dreamus", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music116/v4/17/c9/8e/17c98e9b-8a8b-1dcd-c0b1-bf3f1208f1d8/8809829710020.jpg/3000x3000bb.jpg", "description": null, "duration_ms": null, "genres": [ "Rock", "Pop", "K-Pop" ], "id": "1698506754", "is_explicit": false, "label": "(주)글러브엔터테인먼트", "metrics": { "track_count": 1 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "lossless", "lossy-stereo" ], "content_rating": null, "editorial_summary": null, "is_complete": true, "is_mastered_for_itunes": false, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": null, "storefront": "us" } }, "released_at": "2019-06-29T00:00:00Z", "title": "LOVER - Single", "tracks": [], "type": "single", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "8809829710020", "url": "https://music.apple.com/us/album/lover-single/1698506754" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 400, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicSearch_albumsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Albums, singles and EPs by keyword", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.search_albums", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own relevance order for the query", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "album", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/search_artists": { "get": { "description": "Searches Apple Music artists by name in any country's store and returns them a page at a time, each with its ID, bio, genres and origin. Each also has whether it is a person or a group, when it was born or formed, and its full-size picture and banner. The Apple Music Artist API adds the top songs, albums and similar artists.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Profile` items (Apple Music calls it a artist) (the shared schema, the same on every platform), Apple Music's own relevance order for the query. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/search_artists/ (Markdown: https://socialtap.dev/docs/reference/applemusic/search_artists/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/search_artists/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/search_artists/" }, "operationId": "applemusic.search_artists.list", "parameters": [ { "description": "What to search for: an artist's or a band's name, in any language. Apple matches it as its web player's search box does.", "example": "adele", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for: an artist's or a band's name, in any language. Apple matches it as its web player's search box does.", "examples": [ "adele" ], "maxLength": 500, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their names and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "JP", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their names and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features125/v4/a2/2d/df/a22ddf71-9254-043c-c162-11fbc25c5ff3/mzl.ilbjswky.jpg/2400x2400bb.jpg", "banner_url": "https://is1-ssl.mzstatic.com/image/thumb/Features69/v4/49/b8/ed/49b8edd2-17ed-0aa2-c14a-8cdee66b648c/pr_source.png/4320x1080bb.jpg", "bio": "Dozens of British artists share Adele’s origins—BRIT School, Myspace, pop stardom—but it takes rare talent to have your voice declared timeless in your career’s first flush. Adele Adkins honed hers as a kid in her North London bedroom, imitating Etta James every night for an hour…", "category": null, "country_code": null, "created_at": null, "display_name": "Adele", "external_links": [], "id": "262836961", "is_private": null, "is_verified": null, "location": "Tottenham, London, England", "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "albums": [], "amg_artist_id": null, "born_or_formed": "May 5, 1988", "editorial_summary": null, "genres": [ "Pop" ], "is_group": false, "latest_release": null, "music_videos": [], "playlists": [], "similar_artists": [], "singles": [], "storefront": "us", "top_songs": [] } }, "type": "person", "unknown_fields": [ "platform_specific.applemusic.top_songs", "platform_specific.applemusic.albums", "platform_specific.applemusic.singles" ], "url": "https://music.apple.com/us/artist/adele/262836961", "username": null }, { "approximate_fields": [], "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Music124/v4/4f/60/52/4f6052f0-54d7-5d45-3c3c-f957a969c390/887396302181.tif/1500x1500ac.jpg", "banner_url": null, "bio": null, "category": null, "country_code": null, "created_at": null, "display_name": "Adele", "external_links": [], "id": "563040812", "is_private": null, "is_verified": null, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "albums": [], "amg_artist_id": null, "born_or_formed": null, "editorial_summary": null, "genres": [ "Christian" ], "is_group": false, "latest_release": null, "music_videos": [], "playlists": [], "similar_artists": [], "singles": [], "storefront": "us", "top_songs": [] } }, "type": "person", "unknown_fields": [ "platform_specific.applemusic.top_songs", "platform_specific.applemusic.albums", "platform_specific.applemusic.singles" ], "url": "https://music.apple.com/us/artist/adele/563040812", "username": null }, { "approximate_fields": [], "avatar_url": null, "banner_url": null, "bio": null, "category": null, "country_code": null, "created_at": null, "display_name": "Adele", "external_links": [], "id": "1268134202", "is_private": null, "is_verified": null, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "albums": [], "amg_artist_id": null, "born_or_formed": null, "editorial_summary": null, "genres": [ "Pop" ], "is_group": false, "latest_release": null, "music_videos": [], "playlists": [], "similar_artists": [], "singles": [], "storefront": "us", "top_songs": [] } }, "type": "person", "unknown_fields": [ "platform_specific.applemusic.top_songs", "platform_specific.applemusic.albums", "platform_specific.applemusic.singles" ], "url": "https://music.apple.com/us/artist/adele/1268134202", "username": null } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 313, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicSearch_artistsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Artists by name, with bio and origin", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.search_artists", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own relevance order for the query", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/search_playlists": { "get": { "description": "Searches Apple Music playlists or radio stations by keyword in any country's store and returns them a page at a time, with who curates each. A playlist has its description, Apple's one-line note, cover, track count, whether it is editorial, when it last changed and its audio format. A station has its kind, band and frequency, whether it streams live and whether only subscribers can play it.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Playlist` items (the shared schema, the same on every platform), Apple Music's own relevance order for the query. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/search_playlists/ (Markdown: https://socialtap.dev/docs/reference/applemusic/search_playlists/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/search_playlists/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/search_playlists/" }, "operationId": "applemusic.search_playlists.list", "parameters": [ { "description": "What to search for: a playlist's or station's name, an artist, a mood, a genre, in any language. Apple matches it as its web player's search box does.", "example": "workout", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for: a playlist's or station's name, an artist, a mood, a genre, in any language. Apple matches it as its web player's search box does.", "examples": [ "workout" ], "maxLength": 500, "type": "string" } }, { "description": "What to list: playlists (the default) or radio stations. Both come back in the same playlist shape, and platform_type says which it is.", "example": "station", "in": "query", "name": "kind", "schema": { "default": "playlist", "description": "What to list: playlists (the default) or radio stations. Both come back in the same playlist shape, and platform_type says which it is.", "enum": [ "playlist", "station" ], "examples": [ "station" ], "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "JP", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "description": "Here’s where you’ll find the best tunes for working out that are making the rounds online. Just like your feed, this playlist is constantly being updated—if you hear a song you like, add it to your library.", "id": "pl.ee26872314e349ddaa91050dadbbaaff", "is_collaborative": false, "metrics": { "post_count": 100 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features211/v4/9a/7c/44/9a7c4409-33aa-4b66-f2e7-e4362c01f490/93eac142-43a5-4614-b866-614702fc22ba.png/1080x1080bb.jpg", "display_name": "Apple Music Fitness", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/apple-music-fitness/1558256909", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "1558256909", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "The best tunes from your social feeds for working out.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-10-30T04:02:36Z", "media_kind": null, "playlist_type": "editorial", "rank": null, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/46/9d/7b/469d7b24-d343-9f0a-27c0-2112b40dc513/d9221f7b-fe58-47c1-a1ea-2f5a19c03168.png/1080x1080SC.DN02.jpg?l=en-US", "title": "Viral Workout", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/viral-workout/pl.ee26872314e349ddaa91050dadbbaaff" }, { "approximate_fields": [], "description": "Get your sexy back with pop's divas, rap’s heavy hitters, and more. This playlist is updated regularly with the biggest hits of the 2000s. If you hear something you like, add it to your library.", "id": "pl.89b29d098bb64215a3caac990b3d80e0", "is_collaborative": false, "metrics": { "post_count": 100 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features211/v4/9a/7c/44/9a7c4409-33aa-4b66-f2e7-e4362c01f490/93eac142-43a5-4614-b866-614702fc22ba.png/1080x1080bb.jpg", "display_name": "Apple Music Fitness", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/apple-music-fitness/1558256909", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "1558256909", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "Get your sexy back with pop's divas, rap’s heavy hitters, and more.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-08-18T21:11:32Z", "media_kind": null, "playlist_type": "editorial", "rank": null, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features116/v4/40/99/84/409984d1-6457-53fe-9575-e1f173f2576c/9180e7c7-6797-4bdd-bc1c-3e6b0d010de7.png/1080x1080SC.DN02.jpg?l=en-US", "title": "2000s Workout", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/2000s-workout/pl.89b29d098bb64215a3caac990b3d80e0" }, { "approximate_fields": [], "description": "The best songs for getting you through that final lap or set. Our editors regularly update this playlist—if you hear something you like, add it to your library.", "id": "pl.4c62f568a0d64293a9c362037175c09b", "is_collaborative": false, "metrics": { "post_count": 139 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features211/v4/9a/7c/44/9a7c4409-33aa-4b66-f2e7-e4362c01f490/93eac142-43a5-4614-b866-614702fc22ba.png/1080x1080bb.jpg", "display_name": "Apple Music Fitness", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/apple-music-fitness/1558256909", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "1558256909", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "The best songs for getting you through that final lap or set.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-10-23T22:50:48Z", "media_kind": null, "playlist_type": "editorial", "rank": null, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features125/v4/b9/18/02/b9180250-a496-520c-70eb-6f01710b083d/U0MtTVMtV1ctSGlwLUhvcF9Xb3Jrb3V0LUFEQU1fSUQ9MTAwNDc4MTM5Ni5wbmc.png/1080x1080SC.DN02.jpg?l=en-US", "title": "Hip-Hop Workout", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/hip-hop-workout/pl.4c62f568a0d64293a9c362037175c09b" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 404, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicSearch_playlistsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Playlists and radio stations by keyword", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.search_playlists", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own relevance order for the query", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "playlist", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/search_tracks": { "get": { "description": "Searches Apple Music songs, music videos or radio episodes by keyword in any country's store and returns them a page at a time, each with its ISRC. Each also has the credited artists with their IDs, album, length, release date, composer, genres, explicit rating, audio formats, whether Apple has its lyrics, artwork and a preview clip. A radio episode has its show as author and when it aired.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Post` items (Apple Music calls it a track) (the shared schema, the same on every platform), Apple Music's own relevance order for the query. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/search_tracks/ (Markdown: https://socialtap.dev/docs/reference/applemusic/search_tracks/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/search_tracks/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/search_tracks/" }, "operationId": "applemusic.search_tracks.list", "parameters": [ { "description": "What to search for: a song's or video's title, an artist's name, an album's, or any of them together, in any language. Apple matches it as its web player's search box does.", "example": "taylor swift", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for: a song's or video's title, an artist's name, an album's, or any of them together, in any language. Apple matches it as its web player's search box does.", "examples": [ "taylor swift" ], "maxLength": 500, "type": "string" } }, { "description": "What to list: songs (the default), music videos or radio episodes. Every kind comes back in the same post shape, and platform_type says which it is.", "example": "music_video", "in": "query", "name": "kind", "schema": { "default": "song", "description": "What to list: songs (the default), music videos or radio episodes. Every kind comes back in the same post shape, and platform_type says which it is.", "enum": [ "song", "music_video", "radio_episode" ], "examples": [ "music_video" ], "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "JP", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to search: the results, their titles and their links differ by store. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null }, "coauthors": [], "duration_ms": 225868, "hashtags": [], "id": "6814997425", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/ec/c8/21/ecc821bd-1252-51fe-08f0-f3d548dcc91b/mzaf_6909590374062866776.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Taylor Swift", "album_id": "6814997249", "album_title": "The Life of a Showgirl: The Encore", "album_url": "https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249", "artist_name": "Taylor Swift", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Taylor Swift, Max Martin & Shellback", "content_rating": null, "curator_id": null, "disc_number": 2, "genres": [ "Pop" ], "is_4k": null, "is_apple_digital_master": true, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": true, "is_time_synced_lyrics_available": true, "isrc": "USUG12602391", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": null, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2026-09-24T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg", "title": "Patient Zero", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null }, "coauthors": [], "duration_ms": 226074, "hashtags": [], "id": "1833328840", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/4b/07/28/4b07285f-b50c-7aff-cb40-2d732256b703/mzaf_14590041634085649439.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Taylor Swift", "album_id": "1833328839", "album_title": "The Life of a Showgirl", "album_url": "https://music.apple.com/us/album/the-life-of-a-showgirl/1833328839", "artist_name": "Taylor Swift", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Taylor Swift, Max Martin & Shellback", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Pop" ], "is_4k": null, "is_apple_digital_master": true, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": true, "is_time_synced_lyrics_available": true, "isrc": "USUG12506436", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": null, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2025-10-03T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg", "title": "The Fate of Ophelia", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null }, "coauthors": [], "duration_ms": 178186, "hashtags": [], "id": "6775527443", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/73/76/42/737642e6-c478-bed7-f11f-efee96072450/mzaf_12192094637498612451.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Taylor Swift", "album_id": "6775527442", "album_title": "I Knew It, I Knew You (From \"Toy Story 5\") - Single", "album_url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5-single/6775527442", "artist_name": "Taylor Swift", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Taylor Swift & Jack Antonoff", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Country" ], "is_4k": null, "is_apple_digital_master": true, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": true, "is_time_synced_lyrics_available": true, "isrc": "USWD12641055", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": null, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2026-06-05T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg", "title": "I Knew It, I Knew You (From \"Toy Story 5\")", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5/6775527442?i=6775527443" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 494, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicSearch_tracksResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Songs, music videos and radio episodes by keyword", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.search_tracks", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own relevance order for the query", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/top_albums": { "get": { "description": "Returns Apple Music's chart of the most played albums in a country's store, top first, a page at a time, with each album's rank, label and UPC. Each row also has the credited artists with their IDs, full-size cover, release date, copyright, genres, track count, explicit rating, audio formats, Apple's notes and its Digital Master badge. Pick the store with country, the US by default.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Album` items (the shared schema, the same on every platform), Apple Music's own chart order (1 = most played). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/top_albums/ (Markdown: https://socialtap.dev/docs/reference/applemusic/top_albums/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/top_albums/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/top_albums/" }, "operationId": "applemusic.top_albums.list", "parameters": [ { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "US", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "released_at" ], "artist_name": "BigXthaPlug", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/2d/37/2e/2d372ebd-cf1a-b1f5-2e2e-b8aebb430cf2/ami_U003aidentity_U003a8cd8358dbec0e6453567ddb7d3121e91-2026-10-09T12-14-49.366Z_cropped.png/871x871bb.jpg", "display_name": "BigXthaPlug", "id": "1482508209", "is_verified": null, "url": "https://music.apple.com/us/artist/bigxthaplug/1482508209", "username": null } ], "copyrights": [ { "text": "℗ 2026 BigXthaPlug under exclusive license to UnitedMasters LLC", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/f2/30/e2/f230e2c5-8527-184a-12f7-442f85567061/711209295424.png/3000x3000bb.jpg", "description": "On his previous album, 2025’s I Hope You’re Happy, the irrepressible Dallas rapper BigXthaPlug took a break from being the torchbearer for Texas storytelling rap and reinvented himself as a brokenhearted country crooner. That record was BigX’s highest-charting album to date, but …", "duration_ms": null, "genres": [ "Hip-Hop/Rap" ], "id": "6827763091", "is_explicit": true, "label": "BigXthaPlug under exclusive license to UnitedMasters LLC", "metrics": { "track_count": 19 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "content_rating": "explicit", "editorial_summary": "The Dallas MC returns to his Southern rap roots.", "is_complete": true, "is_mastered_for_itunes": false, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": 1, "storefront": "us" } }, "released_at": "2026-11-02T00:00:00Z", "title": "BETTER OVER TIME", "tracks": [], "type": "album", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "711209295424", "url": "https://music.apple.com/us/album/better-over-time/6827763091" }, { "approximate_fields": [ "released_at" ], "artist_name": "Drake", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages112/v4/1b/71/65/1b716513-b0c1-9c6b-45aa-cbb9198248cc/01607cf1-1d52-43d2-84ce-d6fc1f4a3475_ami-identity-7665599cc626d803af7956b3691905e7-2022-11-30T21-07-19.526Z_cropped.png/1825x1825bb.jpg", "display_name": "Drake", "id": "271256", "is_verified": null, "url": "https://music.apple.com/us/artist/drake/271256", "username": null } ], "copyrights": [ { "text": "℗ 2026 OVO, under exclusive license to Republic Records, a division of UMG Recordings, Inc.", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/bb/45/62/bb4562a3-45a2-539c-b557-a18ea060a476/26UMGIM63616.rgb.jpg/4500x4500bb.jpg", "description": "& other nicknames I call my dear city", "duration_ms": null, "genres": [ "R&B/Soul" ], "id": "6818209777", "is_explicit": true, "label": "OVO/Republic", "metrics": { "track_count": 24 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "lossless", "lossy-stereo" ], "content_rating": "explicit", "editorial_summary": "The 2026 album, now with videos and four previously unreleased tracks.", "is_complete": true, "is_mastered_for_itunes": true, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": 2, "storefront": "us" } }, "released_at": "2026-10-02T00:00:00Z", "title": "HABIBTI (FOMO)", "tracks": [], "type": "album", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "00881061707059", "url": "https://music.apple.com/us/album/habibti-fomo/6818209777" }, { "approximate_fields": [ "released_at" ], "artist_name": "Olivia Rodrigo", "artists": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/ba/36/7a/ba367a61-9f8a-8905-9dbd-7a99db6ee77b/ami-identity-5b05d351a6e3c7256ef7680c8aef2894-2026-06-12T04-01-34.107Z_cropped.png/972x972bb.jpg", "display_name": "Olivia Rodrigo", "id": "979458609", "is_verified": null, "url": "https://music.apple.com/us/artist/olivia-rodrigo/979458609", "username": null } ], "copyrights": [ { "text": "℗ 2026 Olivia Rodrigo, under exclusive license to Geffen Records", "type": "p" } ], "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1d/1b/f9/1d1bf9b1-44c6-9a6c-6ffb-c158488c06ce/26UMGIM39303.rgb.jpg/4000x4000bb.jpg", "description": "A pop savant raises her game and her standards on her third album. Olivia Rodrigo has loved and lost many times since she cried through the suburbs as the heartbroken teenager in “drivers license.” She’s grown up, and her standards have gotten higher—for a good love song, but als…", "duration_ms": null, "genres": [ "Pop" ], "id": "1889992111", "is_explicit": true, "label": "Olivia Rodrigo PS", "metrics": { "track_count": 14 }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "content_rating": "explicit", "editorial_summary": "A pop savant raises her game and her standards on her third album.", "is_complete": true, "is_mastered_for_itunes": true, "is_prerelease": false, "more_by_artist": [], "other_versions": [], "rank": 3, "storefront": "us" } }, "released_at": "2026-06-12T00:00:00Z", "title": "you seem pretty sad for a girl so in love", "tracks": [], "type": "album", "unknown_fields": [ "tracks", "tracks[].artists", "platform_specific.applemusic.more_by_artist" ], "upc": "00199957777902", "url": "https://music.apple.com/us/album/you-seem-pretty-sad-for-a-girl-so-in-love/1889992111" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 336, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicTop_albumsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Most played albums chart by country", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.top_albums", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own chart order (1 = most played)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "album", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/top_playlists": { "get": { "description": "Returns Apple Music's chart of the most played playlists in a country's store, top first, a page at a time, with each playlist's rank and curator. Each row also has the title, Apple's description and note, full-size cover, track count, whether Apple's editors or an outside curator make it, when it last changed and its audio formats. Pick the store with country, the US by default.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Playlist` items (the shared schema, the same on every platform), Apple Music's own chart order (1 = most played). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/top_playlists/ (Markdown: https://socialtap.dev/docs/reference/applemusic/top_playlists/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/top_playlists/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/top_playlists/" }, "operationId": "applemusic.top_playlists.list", "parameters": [ { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "US", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "description": "Music has been an essential part of any holiday celebration for centuries. This playlist honors that history, collecting old chestnuts, new classics, and future sing-along staples to soundtrack your next Christmas. Trim the tree, open the presents, and serve up some eggnog as pop…", "id": "pl.b0e04e25887741ea845e1d5c88397fd4", "is_collaborative": false, "metrics": { "post_count": 100 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/dc/03/16/dc031679-6f1e-5ec0-cd81-17edf19c66c2/7e2c3f93-9d73-41c2-9cec-841a2240173a.png/1080x1080bb.jpg", "display_name": "Holiday", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/holiday/976439540", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "976439540", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "The songs that define the season.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-10-23T19:16:13Z", "media_kind": null, "playlist_type": "editorial", "rank": 1, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features112/v4/d1/a8/45/d1a84579-ce57-5a1f-1334-e6c417605020/befc39eb-584c-4681-92b0-16c913f1230a.png/4320x1080cc.jpg", "title": "Essential Christmas", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/essential-christmas/pl.b0e04e25887741ea845e1d5c88397fd4" }, { "approximate_fields": [], "description": "This playlist tracks what’s happening from the heart of the country scene to its outer edges. Find fan favorites you already love next to breakout stars and emerging voices. Topping the list this week is HARDY with “By God,” a track off the country star’s just-released EP Sides. …", "id": "pl.87bb5b36a9bd49db8c975607452bfa2b", "is_collaborative": false, "metrics": { "post_count": 73 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features/v4/a0/3c/32/a03c3207-70b9-5a3d-28d9-430e2a1891cc/2775cb3b-a652-41ea-91f5-e28fe0d43bde.png/1080x1080bb.jpg", "display_name": "Apple Music Country", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/apple-music-country/976439534", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "976439534", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "“By God” is HARDY at his most inspirational.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-10-30T23:33:21Z", "media_kind": null, "playlist_type": "editorial", "rank": 2, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features/v4/ea/0a/1d/ea0a1d2e-6b0b-e3b7-673f-2534fb354b22/dd2db469-90b2-4cd7-9c7b-83809965c0f9.png/1080x1080SC.DN02.jpg?l=en-US", "title": "Today’s Country", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/todays-country/pl.87bb5b36a9bd49db8c975607452bfa2b" }, { "approximate_fields": [], "description": "From the alt vanguard to modern vets, straightforward to left-field, R&B Now captures where the genre is now and points the way to where it’s going. In 2026, that meant another breakout year for Kehlani, the moment years of consistent artistry finally converted into mainstream do…", "id": "pl.9987b58cfa9747328b3fe9b974e2b797", "is_collaborative": false, "metrics": { "post_count": 50 }, "owner": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/Features/v4/47/94/31/479431e2-12bd-c03e-48bd-1022fe74b1b2/b8395439-127c-43b1-bea6-ebc3433a0e9c.png/1080x1080bb.jpg", "display_name": "Apple Music R&B", "id": null, "is_verified": null, "url": "https://music.apple.com/us/curator/apple-music-r-b/976439551", "username": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "audio_traits": [], "band": null, "curator_id": "976439551", "editorial_kind": null, "editorial_sub_kind": null, "editorial_summary": "In 2026, Kehlani’s “Folded” told us everything we needed to hear.", "frequency": null, "is_chart": false, "is_collaborative": false, "is_live": null, "is_subscription_required": null, "last_modified_at": "2026-11-04T17:39:22Z", "media_kind": null, "playlist_type": "editorial", "rank": 3, "station_kind": null, "storefront": "us" } }, "platform_type": "playlist", "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Features/v4/59/98/c9/5998c9a4-61d1-c40a-c790-f525acc95b40/4b4be703-911f-4917-8199-12762b25551d.png/1080x1080SC.DN02.jpg?l=en-US", "title": "R&B Now: Best of 2026", "type": "playlist", "unknown_fields": [], "url": "https://music.apple.com/us/playlist/r-b-now-best-of-2026/pl.9987b58cfa9747328b3fe9b974e2b797" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 384, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicTop_playlistsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Most played playlists chart by country", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.top_playlists", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own chart order (1 = most played)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "playlist", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/top_tracks": { "get": { "description": "Returns Apple Music's chart of the most played songs or music videos in a country's store, top first, a page at a time, with each one's rank and ISRC. Each row also has the credited artists with their IDs, album, length, release date, composer, genres, explicit rating, audio formats, whether Apple has its lyrics, artwork and a preview clip. Pick the store with country and the chart with kind: the US songs chart by default.\n\nReturns `{data, page, meta}`: `data` holds up to 100 `Post` items (Apple Music calls it a track) (the shared schema, the same on every platform), Apple Music's own chart order (1 = most played). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/top_tracks/ (Markdown: https://socialtap.dev/docs/reference/applemusic/top_tracks/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/top_tracks/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/top_tracks/" }, "operationId": "applemusic.top_tracks.list", "parameters": [ { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "example": "US", "in": "query", "name": "country", "schema": { "default": "US", "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store whose chart to read: each has its own. A country with no Apple Music store returns invalid_input. Default: US. UK is read as GB.", "examples": [ "JP" ], "type": "string" } }, { "description": "Which chart: most played songs (the default) or music videos. Both come back in the same post shape, and platform_type says which it is.", "example": "song", "in": "query", "name": "kind", "schema": { "default": "song", "description": "Which chart: most played songs (the default) or music videos. Both come back in the same post shape, and platform_type says which it is.", "enum": [ "song", "music_video" ], "examples": [ "music_video" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/7d/f9/5b/7df95b8e-26fb-5e14-f35d-f603abc52dc8/ami-identity-6b9f829473ca41446a842ac18b0e65ee-2026-01-27T17-02-20.725Z_cropped.png/2400x2400bb.jpg", "display_name": "Ella Langley", "id": "1384373733", "is_verified": null, "url": "https://music.apple.com/us/artist/ella-langley/1384373733", "username": null }, "coauthors": [], "duration_ms": 232226, "hashtags": [], "id": "1844932150", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/e2/91/4d/e2914d0a-7f1d-f04c-fbf4-c50b38548838/196873638690.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview211/v4/38/49/4c/38494cb4-f9e0-1db4-0b84-8c478cb55390/mzaf_14015374052766148372.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Ella Langley", "album_id": "1844932149", "album_title": "Choosin' Texas - Single", "album_url": "https://music.apple.com/us/album/choosin-texas-single/1844932149", "artist_name": "Ella Langley", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Ella Langley, Luke Dick, Miranda Lambert & Joybeth Taylor", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Country" ], "is_4k": null, "is_apple_digital_master": false, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": false, "is_time_synced_lyrics_available": true, "isrc": "USSM12504190", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": 1, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2025-10-17T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/e2/91/4d/e2914d0a-7f1d-f04c-fbf4-c50b38548838/196873638690.jpg/3000x3000bb.jpg", "title": "Choosin' Texas", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/choosin-texas/1844932149?i=1844932150" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/84/8a/4e/848a4e8b-48c7-e3fa-ae20-a42cd4b469a8/ami-identity-d59cbd95617167e768f2dbfe6377cf2e-2026-08-09T23-03-10.005Z_cropped.png/1454x1454bb.jpg", "display_name": "KAROL G", "id": "290814601", "is_verified": null, "url": "https://music.apple.com/us/artist/karol-g/290814601", "username": null }, "coauthors": [ { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/f2/bd/40/f2bd40bd-cbc0-bb7d-87b2-27f8b2eed765/ami-identity-7f43d3c2d6a3b0cb7b4be17c4fd5aca6-2024-10-24T17-10-43.339Z_cropped.png/1349x1349bb.jpg", "display_name": "Judeline", "id": "1487503245", "is_verified": null, "url": "https://music.apple.com/us/artist/judeline/1487503245", "username": null }, { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/7f/72/61/7f7261cb-880d-6bf2-73e7-07107d3764c4/file_cropped.png/1830x1830bb.jpg", "display_name": "rusowsky", "id": "1388592825", "is_verified": null, "url": "https://music.apple.com/us/artist/rusowsky/1388592825", "username": null } ], "duration_ms": 225835, "hashtags": [], "id": "6796864754", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/2b/66/b2/2b66b26c-ab23-faa1-c4ee-06fa2cce8f76/26UM1IM00558.rgb.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/f3/08/da/f308da3d-00cc-7682-7be9-87cb882f4ea5/mzaf_14078178240008272749.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "KAROL G", "album_id": "6796864741", "album_title": "NO ME ARREPIENTO DE SENTIR TANTO", "album_url": "https://music.apple.com/us/album/no-me-arrepiento-de-sentir-tanto/6796864741", "artist_name": "KAROL G, Judeline & rusowsky", "attribution": null, "audio_locale": "es-ES", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Cordel Dexter Burrell, Carolina Giraldo Navarro, Marco Masis, Omer Fedi, Lara Fernández Castrelo, Andres Jael Correa Rios & Ruslán Mediavilla", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Urbano latino", "Latin" ], "is_4k": null, "is_apple_digital_master": true, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": true, "is_time_synced_lyrics_available": true, "isrc": "USUG12607940", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": 2, "storefront": "us", "track_number": 11, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2026-08-05T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/2b/66/b2/2b66b26c-ab23-faa1-c4ee-06fa2cce8f76/26UM1IM00558.rgb.jpg/3000x3000bb.jpg", "title": "BbY WOW", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/bby-wow/6796864741?i=6796864754" }, { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/19/7a/a7/197aa7f2-53af-5777-72ed-e292b550d159/ami_U003aidentity_U003a11b6c33ddb521791b7ba1dd8c4dcf764-2026-10-16T00-09-37.146Z_cropped.png/902x902bb.jpg", "display_name": "Tate McRae", "id": "1446365464", "is_verified": null, "url": "https://music.apple.com/us/artist/tate-mcrae/1446365464", "username": null }, "coauthors": [], "duration_ms": 208810, "hashtags": [], "id": "6822497774", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/69/64/e4/6964e483-c02c-e389-14f4-c426e8c65f2c/196874840146.jpg/3000x3000bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/05/27/d4/0527d4f3-f6af-1ef8-6a32-25477b7b00ba/mzaf_9026536433413395761.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Tate McRae", "album_id": "6822497770", "album_title": "Housewife - Single", "album_url": "https://music.apple.com/us/album/housewife-single/6822497770", "artist_name": "Tate McRae", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Tate McRae, Julia Michaels, Ryan Tedder, Grant Boutin, Jasper Harris & Pablo Diaz-Reixa", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Pop" ], "is_4k": null, "is_apple_digital_master": false, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": false, "is_time_synced_lyrics_available": true, "isrc": "USRC12601916", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": 3, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2026-10-15T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/69/64/e4/6964e483-c02c-e389-14f4-c426e8c65f2c/196874840146.jpg/3000x3000bb.jpg", "title": "Housewife", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/housewife/6822497770?i=6822497774" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 488, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicTop_tracksResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Most played songs and music videos by country", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.top_tracks", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Apple Music's own chart order (1 = most played)", "page_max": 100, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/applemusic/track": { "get": { "description": "Returns an Apple Music song, music video or radio episode from its link or ID in any country's store, with its ISRC, composer and audio formats. It also has the artists, album, disc and track number, exact length, release date, genres, explicit rating, whether Apple has its lyrics, the classical work and movement, artwork and a preview clip. Legacy iTunes links work too.\n\nReturns `{data, meta}`: `data` is a `Post` object (Apple Music calls it a track) (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/applemusic/track/ (Markdown: https://socialtap.dev/docs/reference/applemusic/track/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/applemusic/track/index.md)", "url": "https://socialtap.dev/docs/reference/applemusic/track/" }, "operationId": "applemusic.track.get", "parameters": [ { "description": "The track: its album link with ?i= (music.apple.com/us/album/lover/1468058165?i=1468058169), its song link (music.apple.com/us/song/i-forgot-that-you-existed/1468058169), a music video's link (music.apple.com/us/music-video/hello/1544490140), a radio episode's link (music.apple.com/us/station/20-years-of-taylor-swift/ra.6825008805), with or without the slug and the store, on music.apple.com, geo.music.apple.com or itunes.apple.com; or its ID alone (1468058169, ra.6825008805).", "example": "https://music.apple.com/us/album/lover/1468058165?i=1468058169", "in": "query", "name": "url", "required": true, "schema": { "description": "The track: its album link with ?i= (music.apple.com/us/album/lover/1468058165?i=1468058169), its song link (music.apple.com/us/song/i-forgot-that-you-existed/1468058169), a music video's link (music.apple.com/us/music-video/hello/1544490140), a radio episode's link (music.apple.com/us/station/20-years-of-taylor-swift/ra.6825008805), with or without the slug and the store, on music.apple.com, geo.music.apple.com or itunes.apple.com; or its ID alone (1468058169, ra.6825008805).", "examples": [ "https://music.apple.com/us/album/lover/1468058165?i=1468058169" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: the same ID has its own title language, availability and links per store. Default: the store in the link, else us.", "example": "us", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The Apple Music store to read: the same ID has its own title language, availability and links per store. Default: the store in the link, else us.", "examples": [ "us" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "example": "en-US", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language of the answer's text, when Apple offers it beside the store's own. Default: the link's l=, else the store's own language.", "examples": [ "en-US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "published_at" ], "author": { "avatar_url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg", "display_name": "Taylor Swift", "id": "159260351", "is_verified": null, "url": "https://music.apple.com/us/artist/taylor-swift/159260351", "username": null }, "coauthors": [], "duration_ms": 170651, "hashtags": [], "id": "1468058169", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/49/3d/ab/493dab54-f920-9043-6181-80993b8116c9/19UMGIM53909.rgb.jpg/3900x3900bb.jpg", "type": "audio", "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/9c/e2/97/9ce2976a-b1c8-aa80-3e94-f4562cbad53e/mzaf_13898706762824220632.plus.aac.ep.m4a", "width": null } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "applemusic", "platform_specific": { "applemusic": { "air_ended_at": null, "album_artist_name": "Taylor Swift", "album_id": "1468058165", "album_title": "Lover", "album_url": "https://music.apple.com/us/album/lover/1468058165", "artist_name": "Taylor Swift", "attribution": null, "audio_locale": "en-US", "audio_traits": [ "atmos", "lossless", "lossy-stereo" ], "composer_name": "Taylor Swift, Louis Bell & Adam Feeney", "content_rating": null, "curator_id": null, "disc_number": 1, "genres": [ "Pop" ], "is_4k": null, "is_apple_digital_master": true, "is_explicit": false, "is_hdr": null, "is_live": null, "is_lyrics_available": true, "is_mastered_for_itunes": true, "is_time_synced_lyrics_available": true, "isrc": "USUG11901471", "long_note": null, "movement_count": null, "movement_name": null, "movement_number": null, "rank": null, "storefront": "us", "track_number": 1, "video_traits": [], "work_name": null } }, "platform_type": "song", "published_at": "2019-08-23T00:00:00Z", "text": null, "thumbnail_url": "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/49/3d/ab/493dab54-f920-9043-6181-80993b8116c9/19UMGIM53909.rgb.jpg/3900x3900bb.jpg", "title": "I Forgot That You Existed", "type": "audio", "unknown_fields": [], "url": "https://music.apple.com/us/album/i-forgot-that-you-existed/1468058165?i=1468058169" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "applemusic", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 154, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "1468058169", "url": "https://music.apple.com/us/album/i-forgot-that-you-existed/1468058165?i=1468058169" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/ApplemusicTrackResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Song with ISRC, composer and audio formats", "tags": [ "Apple Music" ], "x-socialtap-endpoint": "applemusic.track", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/billing/auto_topup": { "get": { "description": "The account's auto top-up: the pack it buys when the balance falls to its threshold, its monthly cap and what it charged this month, the saved card it charges, its latest top-up, and why it turned itself off, if it did. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "billing.auto_topup.get", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "currency": { "description": "The currency of the amounts (ISO 4217).", "enum": [ "usd" ], "type": "string" }, "enabled": { "description": "Whether a balance falling to threshold buys pack now.", "type": "boolean" }, "last_charge": { "description": "The latest top-up, whatever its outcome; null before the first.", "properties": { "amount_tax": { "description": "The tax in amount_total (Stripe Tax: only where SocialTap collects it); null when amount_total is.", "type": [ "integer", "null" ] }, "amount_total": { "description": "Charged, tax included, in cents of currency; null when nothing was charged or before it is known.", "type": [ "integer", "null" ] }, "created_at": { "description": "When the balance crossed the threshold, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "credits": { "description": "Credits the pack adds.", "type": "integer" }, "currency": { "description": "amount_total's currency (ISO 4217).", "enum": [ "usd" ], "type": "string" }, "id": { "description": "Top-up ID (atu_…): the ref of its credit_transaction, and on the Stripe payment's metadata.", "type": "string" }, "message": { "description": "What the bank or Stripe said, for people; null when reason is.", "type": [ "string", "null" ] }, "object": { "description": "Always auto_topup_charge.", "enum": [ "auto_topup_charge" ], "type": "string" }, "pack": { "description": "The credit pack (catalog pack ID).", "type": "string" }, "reason": { "description": "Why it failed (the off_reason it set) or was skipped (monthly_cap, trust_limit: it would have passed rolling_limit_cents); null otherwise.", "enum": [ "card_declined", "authentication_required", "no_card", "billing_address_required", "payment_failed", "disputed", "monthly_cap", "trust_limit" ], "type": [ "string", "null" ] }, "status": { "description": "processing (the charge is under way), succeeded (paid: its credits were added, once), failed (nothing charged: auto top-up turned off, see reason) or skipped (it would have passed the monthly cap or the 7-day limit: nothing charged, auto top-up stays on).", "enum": [ "processing", "succeeded", "failed", "skipped" ], "type": "string" } }, "required": [ "object", "id", "status", "pack", "credits", "amount_total", "amount_tax", "currency", "reason", "message", "created_at" ], "type": [ "object", "null" ] }, "month_resets_at": { "description": "Start of the next calendar month (UTC), when spent_this_month_cents starts again from 0.", "format": "date-time", "type": "string" }, "monthly_cap_cents": { "description": "The most auto top-up charges in a calendar month (UTC), tax included, in cents of currency; a top-up that would pass it does not run (the owner is emailed). null until set up.", "type": [ "integer", "null" ] }, "notice": { "description": "What a person should know about the change just made, in a sentence to show them: the chosen pack can't run under rolling_limit_cents, say, so it will be skipped. It never refuses the change. Null otherwise, and on every read.", "type": [ "string", "null" ] }, "object": { "description": "Always auto_topup.", "enum": [ "auto_topup" ], "type": "string" }, "off_at": { "description": "When it turned itself off, RFC 3339 UTC; null when off_reason is.", "format": "date-time", "type": [ "string", "null" ] }, "off_message": { "description": "What the bank or Stripe said, for people; null when off_reason is.", "type": [ "string", "null" ] }, "off_reason": { "description": "Why auto top-up turned itself off (null while on, or when a person turned it off): card_declined (the bank declined the charge), authentication_required (the bank asked the cardholder to confirm it: buy the pack in Billing, then turn auto top-up back on), no_card (no saved card), billing_address_required (Stripe Tax needs the card's billing address: add it in the payment settings), payment_failed (another payment error), disputed (a payment on this account was disputed: auto top-up turns on again only with a different card), bank_inquiry (a bank asked about a payment on this account, which is not yet a dispute: turn it back on when you are ready), plan_ended (it bought a monthly plan's top-up, and the plan ended). It never retries: fix the cause, then turn it on again.", "enum": [ "card_declined", "authentication_required", "no_card", "billing_address_required", "payment_failed", "disputed", "bank_inquiry", "plan_ended" ], "type": [ "string", "null" ] }, "pack": { "description": "The credit pack each top-up buys (catalog pack ID); null until auto top-up is first set up.", "type": [ "string", "null" ] }, "payment_method": { "description": "The saved card a top-up charges (the default card in the payment settings, else the newest); null when there is none, or when the payment processor could not be reached.", "properties": { "brand": { "description": "Card brand (visa, mastercard, amex, …).", "type": "string" }, "exp_month": { "description": "Expiry month (1–12).", "type": "integer" }, "exp_year": { "description": "Expiry year.", "type": "integer" }, "last4": { "description": "The card number's last four digits.", "type": "string" } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "rolling_limit_cents": { "description": "The most auto top-up charges in any 7 days, tax included, in cents, whatever monthly_cap_cents says: it grows with the payments that settled on this account, and support can lift it. A top-up that would pass it does not run (the owner is emailed); buying a pack by hand is never limited by it.", "type": "integer" }, "rolling_spent_cents": { "description": "What auto top-up charged in the last 7 days, tax included, counting a charge in progress, in cents.", "type": "integer" }, "spent_this_month_cents": { "description": "What auto top-up charged this calendar month, tax included, counting a charge in progress, in cents.", "type": "integer" }, "threshold": { "description": "Credits: a balance change that leaves the balance at or below this buys the pack, once until the balance is above it again. null until set up.", "type": [ "integer", "null" ] } }, "required": [ "object", "enabled", "pack", "threshold", "monthly_cap_cents", "currency", "spent_this_month_cents", "rolling_limit_cents", "rolling_spent_cents", "month_resets_at", "off_reason", "off_message", "off_at", "payment_method", "last_charge", "notice" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get auto top-up", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get auto top-up", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "patch": { "description": "Auto top-up buys `pack` with the account's saved card (off-session; sales tax added where SocialTap collects it, as at checkout) whenever a balance change leaves the balance at or below `threshold`, one top-up at a time, never past `monthly_cap_cents` in a calendar month (UTC), tax included (by default `default_cap_packs` (3) × the pack's price). A charge that fails is never retried: auto top-up turns off, the owner is emailed why, and a person turns it back on once the card is fixed. A top-up that would pass `rolling_limit_cents` in any 7 days is skipped, the owner is told how to lift it, it runs by itself once there is room, and `notice` says so when the chosen pack is already past it. A dispute of any payment on the account turns it off, and it turns on again only with a different card; a bank's inquiry only turns it off. The owner is emailed when anyone else turns it on or raises its cap. The dashboard session only, with a fresh sign-in: it authorizes charges to the card. Absent fields keep their value. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "billing.auto_topup.update", "requestBody": { "content": { "application/json": { "schema": { "properties": { "enabled": { "description": "true turns auto top-up on: it needs a saved card (not one disputed on this account), a pack and a threshold (the low-balance alert's when left out), and sets monthly_cap_cents to 3 × the pack's price when none was set. A balance already at or below the threshold buys the pack at the next request. false turns it off; nothing in progress is canceled.", "type": [ "boolean", "null" ] }, "monthly_cap_cents": { "description": "Cents; at least the pack's price (or no top-up could run).", "maximum": 10000000, "minimum": 1, "type": [ "integer", "null" ] }, "pack": { "description": "A credit pack ID of the catalog (packs).", "maxLength": 20, "type": [ "string", "null" ] }, "threshold": { "description": "Credits.", "maximum": 1000000000, "minimum": 0, "type": [ "integer", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "currency": { "description": "The currency of the amounts (ISO 4217).", "enum": [ "usd" ], "type": "string" }, "enabled": { "description": "Whether a balance falling to threshold buys pack now.", "type": "boolean" }, "last_charge": { "description": "The latest top-up, whatever its outcome; null before the first.", "properties": { "amount_tax": { "description": "The tax in amount_total (Stripe Tax: only where SocialTap collects it); null when amount_total is.", "type": [ "integer", "null" ] }, "amount_total": { "description": "Charged, tax included, in cents of currency; null when nothing was charged or before it is known.", "type": [ "integer", "null" ] }, "created_at": { "description": "When the balance crossed the threshold, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "credits": { "description": "Credits the pack adds.", "type": "integer" }, "currency": { "description": "amount_total's currency (ISO 4217).", "enum": [ "usd" ], "type": "string" }, "id": { "description": "Top-up ID (atu_…): the ref of its credit_transaction, and on the Stripe payment's metadata.", "type": "string" }, "message": { "description": "What the bank or Stripe said, for people; null when reason is.", "type": [ "string", "null" ] }, "object": { "description": "Always auto_topup_charge.", "enum": [ "auto_topup_charge" ], "type": "string" }, "pack": { "description": "The credit pack (catalog pack ID).", "type": "string" }, "reason": { "description": "Why it failed (the off_reason it set) or was skipped (monthly_cap, trust_limit: it would have passed rolling_limit_cents); null otherwise.", "enum": [ "card_declined", "authentication_required", "no_card", "billing_address_required", "payment_failed", "disputed", "monthly_cap", "trust_limit" ], "type": [ "string", "null" ] }, "status": { "description": "processing (the charge is under way), succeeded (paid: its credits were added, once), failed (nothing charged: auto top-up turned off, see reason) or skipped (it would have passed the monthly cap or the 7-day limit: nothing charged, auto top-up stays on).", "enum": [ "processing", "succeeded", "failed", "skipped" ], "type": "string" } }, "required": [ "object", "id", "status", "pack", "credits", "amount_total", "amount_tax", "currency", "reason", "message", "created_at" ], "type": [ "object", "null" ] }, "month_resets_at": { "description": "Start of the next calendar month (UTC), when spent_this_month_cents starts again from 0.", "format": "date-time", "type": "string" }, "monthly_cap_cents": { "description": "The most auto top-up charges in a calendar month (UTC), tax included, in cents of currency; a top-up that would pass it does not run (the owner is emailed). null until set up.", "type": [ "integer", "null" ] }, "notice": { "description": "What a person should know about the change just made, in a sentence to show them: the chosen pack can't run under rolling_limit_cents, say, so it will be skipped. It never refuses the change. Null otherwise, and on every read.", "type": [ "string", "null" ] }, "object": { "description": "Always auto_topup.", "enum": [ "auto_topup" ], "type": "string" }, "off_at": { "description": "When it turned itself off, RFC 3339 UTC; null when off_reason is.", "format": "date-time", "type": [ "string", "null" ] }, "off_message": { "description": "What the bank or Stripe said, for people; null when off_reason is.", "type": [ "string", "null" ] }, "off_reason": { "description": "Why auto top-up turned itself off (null while on, or when a person turned it off): card_declined (the bank declined the charge), authentication_required (the bank asked the cardholder to confirm it: buy the pack in Billing, then turn auto top-up back on), no_card (no saved card), billing_address_required (Stripe Tax needs the card's billing address: add it in the payment settings), payment_failed (another payment error), disputed (a payment on this account was disputed: auto top-up turns on again only with a different card), bank_inquiry (a bank asked about a payment on this account, which is not yet a dispute: turn it back on when you are ready), plan_ended (it bought a monthly plan's top-up, and the plan ended). It never retries: fix the cause, then turn it on again.", "enum": [ "card_declined", "authentication_required", "no_card", "billing_address_required", "payment_failed", "disputed", "bank_inquiry", "plan_ended" ], "type": [ "string", "null" ] }, "pack": { "description": "The credit pack each top-up buys (catalog pack ID); null until auto top-up is first set up.", "type": [ "string", "null" ] }, "payment_method": { "description": "The saved card a top-up charges (the default card in the payment settings, else the newest); null when there is none, or when the payment processor could not be reached.", "properties": { "brand": { "description": "Card brand (visa, mastercard, amex, …).", "type": "string" }, "exp_month": { "description": "Expiry month (1–12).", "type": "integer" }, "exp_year": { "description": "Expiry year.", "type": "integer" }, "last4": { "description": "The card number's last four digits.", "type": "string" } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "type": [ "object", "null" ] }, "rolling_limit_cents": { "description": "The most auto top-up charges in any 7 days, tax included, in cents, whatever monthly_cap_cents says: it grows with the payments that settled on this account, and support can lift it. A top-up that would pass it does not run (the owner is emailed); buying a pack by hand is never limited by it.", "type": "integer" }, "rolling_spent_cents": { "description": "What auto top-up charged in the last 7 days, tax included, counting a charge in progress, in cents.", "type": "integer" }, "spent_this_month_cents": { "description": "What auto top-up charged this calendar month, tax included, counting a charge in progress, in cents.", "type": "integer" }, "threshold": { "description": "Credits: a balance change that leaves the balance at or below this buys the pack, once until the balance is above it again. null until set up.", "type": [ "integer", "null" ] } }, "required": [ "object", "enabled", "pack", "threshold", "monthly_cap_cents", "currency", "spent_this_month_cents", "rolling_limit_cents", "rolling_spent_cents", "month_resets_at", "off_reason", "off_message", "off_at", "payment_method", "last_charge", "notice" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Turn auto top-up on or off, or change it", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Turn auto top-up on or off, or change it", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_error" ] } } }, "/v1/billing/checkout": { "post": { "description": "Creates a Stripe Checkout session for a credit pack; open the returned url to pay. Credits are added when payment completes; GET /v1/billing/checkout/{id} follows it.", "operationId": "billing.checkout.create", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "pack": { "description": "Pack ID.", "enum": [ "1k", "30k", "250k", "2m", "starter_topup", "growth_topup", "scale_topup" ], "type": "string" } }, "required": [ "pack" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "Checkout session" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Buy a credit pack (Stripe Checkout)", "tags": [ "Billing" ], "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "idempotency_key_in_progress" ] } } }, "/v1/billing/checkout/{id}": { "get": { "description": "A purchase POST /v1/billing/checkout or POST /v1/billing/subscription/checkout started for this account, as Stripe has it, and whether its credits were added (a paid one's are, once, by the time it answers). Poll while open. Other accounts' sessions are not_found. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "billing.checkout.get", "parameters": [ { "description": "Checkout session ID (cs_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "amount_total": { "description": "Paid, tax included, in the currency's smallest unit; null until known.", "type": [ "integer", "null" ] }, "credits": { "description": "Credits the pack adds, or the plan adds each month.", "type": "integer" }, "credits_added": { "description": "Whether its credits were added (once). A later refund or dispute takes back what is unspent.", "type": "boolean" }, "currency": { "description": "amount_total's currency (ISO 4217); null until known.", "type": [ "string", "null" ] }, "id": { "description": "Checkout session ID (cs_…).", "type": "string" }, "object": { "description": "Always checkout_session.", "enum": [ "checkout_session" ], "type": "string" }, "pack": { "description": "The credit pack bought (catalog pack ID); empty for a monthly plan.", "type": "string" }, "payment_status": { "description": "paid once captured; a complete session stays unpaid while a delayed payment clears.", "enum": [ "paid", "unpaid", "no_payment_required" ], "type": "string" }, "plan": { "description": "The monthly plan subscribed to (catalog plan ID); null for a credit pack.", "type": [ "string", "null" ] }, "status": { "description": "open (not paid yet), complete (checkout finished) or expired (abandoned, nothing charged).", "enum": [ "open", "complete", "expired" ], "type": "string" } }, "required": [ "object", "id", "pack", "plan", "credits", "status", "payment_status", "credits_added", "amount_total", "currency" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get a credit pack purchase", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get a credit pack purchase", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_error" ] } } }, "/v1/billing/portal": { "post": { "description": "A Stripe customer portal link for the account's payment settings: add, replace or remove the saved card that monthly plans and auto top-up charge, change the billing address and tax ID that sales tax and receipts use, and read past invoices. The dashboard session only, with a fresh sign-in: it shows the billing details and changes the card. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "billing.portal.create", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "object": { "description": "Always billing_portal_session.", "enum": [ "billing_portal_session" ], "type": "string" }, "url": { "description": "Open it to add, replace or remove the saved card and to change the billing address and tax ID. It works once, for a few minutes, and returns to the dashboard's billing page.", "type": "string" } }, "required": [ "object", "url" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Open the payment settings (Stripe)", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Open the payment settings (Stripe)", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress", "upstream_error" ] } } }, "/v1/billing/promo_codes/redeem": { "post": { "description": "Adds a promo code's credits to the account's balance, as a promo transaction in its credit history. They never expire. Each code works once per account, and once per email address of the account's owner, whatever account it is on. A code that can't be redeemed is answered invalid_input with param code and details.reason: unknown (no such code), expired (past its end, or withdrawn), used_up (redeemed as many times as it allows), already_redeemed (by this account, or by its owner's address on another) or not_eligible (an account whose owner's address is a throwaway one). The dashboard session only. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "billing.promo_codes.redeem", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The promo code, as written anywhere: case, spaces around it and a leading # don't matter.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "balance": { "description": "The account's balance with them.", "type": "integer" }, "code": { "description": "The code redeemed, in capitals.", "type": "string" }, "credits": { "description": "Credits it added. They never expire, like a pack's.", "type": "integer" }, "object": { "description": "Always promo_redemption.", "enum": [ "promo_redemption" ], "type": "string" }, "redeemed_at": { "description": "When it was redeemed, RFC 3339 UTC.", "format": "date-time", "type": "string" } }, "required": [ "object", "code", "credits", "balance", "redeemed_at" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Redeem a promo code", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Redeem a promo code", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/billing/purchases": { "get": { "description": "Every payment the account made, newest first, cursor-paged: credit packs bought at checkout, auto top-ups, and monthly plan invoices (first months, renewals, upgrades), each with what it cost, its credits, and whether it was refunded or disputed. Its receipt is GET /v1/billing/purchases/{id}/receipt. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "billing.purchases.list", "parameters": [ { "description": "Purchases per page (default 25, at most 100).", "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor of the previous page.", "in": "query", "name": "cursor", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "This page's items.", "items": { "properties": { "amount_refunded": { "description": "Refunded so far, in currency's smallest unit; 0 when nothing was.", "type": "integer" }, "amount_total": { "description": "Charged, tax included, in currency's smallest unit; null when not recorded.", "type": [ "integer", "null" ] }, "created_at": { "description": "When it was recorded, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "credits": { "description": "Credits it adds: the pack's, or the plan's for the month.", "type": "integer" }, "currency": { "description": "amount_total's currency (ISO 4217, lowercase); null when not recorded.", "type": [ "string", "null" ] }, "id": { "description": "Purchase ID: the Checkout session (cs_…) of a pack, the auto top-up (atu_…), or the plan's invoice (in_…).", "type": "string" }, "object": { "description": "Always purchase.", "enum": [ "purchase" ], "type": "string" }, "pack": { "description": "The credit pack bought (catalog pack ID); null for a plan, or when it is not recorded.", "type": [ "string", "null" ] }, "plan": { "description": "The monthly plan paid for (catalog plan ID); null for a pack, or when it is not recorded.", "type": [ "string", "null" ] }, "status": { "description": "pending (a delayed payment, such as a bank debit, is clearing: its credits are added when it does), paid, failed (the delayed payment failed: nothing was charged or added), partially_refunded, refunded, or disputed (the cardholder's bank disputed it; a dispute closed in SocialTap's favor reads paid again).", "enum": [ "pending", "paid", "failed", "partially_refunded", "refunded", "disputed" ], "type": "string" }, "type": { "description": "pack (a credit pack bought at checkout), auto_top_up (a pack auto top-up bought with the saved card) or plan (a monthly plan's invoice: its first month, a renewal or an upgrade).", "enum": [ "pack", "auto_top_up", "plan" ], "type": "string" } }, "required": [ "object", "id", "type", "pack", "plan", "credits", "status", "amount_total", "amount_refunded", "currency", "created_at" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "page": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages" ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" } }, "required": [ "data", "page", "meta" ], "type": "object" } } }, "description": "List purchases", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "List purchases", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/billing/purchases/{id}/receipt": { "get": { "description": "A fresh link to a purchase's receipt, from Stripe: a monthly plan's invoice page (with its PDF), or a pack's or auto top-up's receipt (tax and refunds included). A pending purchase has none until its payment clears, and other accounts' purchases are not_found. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "billing.purchases.receipt", "parameters": [ { "description": "Purchase ID (cs_…, atu_… or in_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "description": "The purchase ID.", "type": "string" }, "object": { "description": "Always purchase_receipt.", "enum": [ "purchase_receipt" ], "type": "string" }, "url": { "description": "Stripe's page for it: a plan's invoice (with its PDF and its receipt), or a pack's receipt, which shows the tax and any refund and can be downloaded. Ask again for a fresh link rather than storing it.", "type": "string" } }, "required": [ "object", "id", "url" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get a purchase's receipt", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get a purchase's receipt", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_error" ] } } }, "/v1/billing/subscription": { "get": { "description": "The account's monthly plan: the plan paid for now, when it renews, what it changes to at renewal, and how much of the balance is monthly credits (spent first, ended at renewal). Without a plan, status is none and the account is pay as you go. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "billing.subscription.get", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cancel_at_period_end": { "description": "Whether it ends at current_period_end instead of renewing. Monthly credits end with it; pack and top-up credits stay.", "type": "boolean" }, "current_period_end": { "description": "When this month's credits end and the plan renews, or ends: RFC 3339 UTC; null without a monthly plan.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Subscription ID (sub_…); null without a monthly plan.", "type": [ "string", "null" ] }, "monthly_credits": { "description": "Credits the plan adds at each renewal; 0 without a monthly plan.", "type": "integer" }, "monthly_credits_remaining": { "description": "How much of the balance is monthly credits: requests spend these first, and what is left of them ends at the next renewal. The rest of the balance never expires.", "type": "integer" }, "next_plan": { "description": "The plan it changes to at the next renewal, after a downgrade; null when it stays on plan.", "type": [ "string", "null" ] }, "notice": { "description": "What a person should know about the plan change just made, in a sentence to show them: its renewal is also being charged, say, or auto top-up's monthly cap is now below the top-up's price. Null otherwise, and on every read.", "type": [ "string", "null" ] }, "object": { "description": "Always subscription.", "enum": [ "subscription" ], "type": "string" }, "payment_url": { "description": "Set when a plan change could not be paid yet (the card was declined, or the bank asks the cardholder to confirm): pay here within a day and the change applies. Null otherwise.", "type": [ "string", "null" ] }, "plan": { "description": "The plan paid for now (catalog plan ID); payg without a monthly plan.", "type": "string" }, "status": { "description": "none (pay as you go), incomplete (the first payment is not through yet), active, past_due (the last renewal failed: Stripe retries it, and no new credits arrive until it is paid) or unpaid (the retries ended without payment).", "enum": [ "none", "incomplete", "active", "past_due", "unpaid" ], "type": "string" }, "top_up_pack": { "description": "The credit pack this plan's subscribers can top up with when they run out (catalog pack ID, also for auto top-up); null without a monthly plan.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "plan", "status", "next_plan", "cancel_at_period_end", "current_period_end", "monthly_credits", "monthly_credits_remaining", "top_up_pack", "payment_url", "notice" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get the monthly plan", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get the monthly plan", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } }, "patch": { "description": "Upgrades or downgrades the account's monthly plan. An upgrade starts now: the new plan's full price is charged to the saved card, a new month starts today, the plan's credits are added and the monthly credits left stay until the next renewal. A downgrade starts at the next renewal, with nothing charged now. It works in every state of the plan, and answers what the person should know in `notice`, or where to pay in `payment_url`; only an account with no card is refused, until it adds one. The dashboard session only, with no fresh sign-in: changing plan has to be as easy as subscribing was. Free.\n\n**Auth:** the dashboard session cookie.", "operationId": "billing.subscription.update", "requestBody": { "content": { "application/json": { "schema": { "properties": { "plan": { "description": "Change to this monthly plan (catalog plans). A dearer one starts now: its full price is charged to the saved card, a new month starts today, and the monthly credits left stay until the next renewal. A cheaper one starts at the next renewal, with nothing charged now.", "maxLength": 20, "type": "string" } }, "required": [ "plan" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cancel_at_period_end": { "description": "Whether it ends at current_period_end instead of renewing. Monthly credits end with it; pack and top-up credits stay.", "type": "boolean" }, "current_period_end": { "description": "When this month's credits end and the plan renews, or ends: RFC 3339 UTC; null without a monthly plan.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Subscription ID (sub_…); null without a monthly plan.", "type": [ "string", "null" ] }, "monthly_credits": { "description": "Credits the plan adds at each renewal; 0 without a monthly plan.", "type": "integer" }, "monthly_credits_remaining": { "description": "How much of the balance is monthly credits: requests spend these first, and what is left of them ends at the next renewal. The rest of the balance never expires.", "type": "integer" }, "next_plan": { "description": "The plan it changes to at the next renewal, after a downgrade; null when it stays on plan.", "type": [ "string", "null" ] }, "notice": { "description": "What a person should know about the plan change just made, in a sentence to show them: its renewal is also being charged, say, or auto top-up's monthly cap is now below the top-up's price. Null otherwise, and on every read.", "type": [ "string", "null" ] }, "object": { "description": "Always subscription.", "enum": [ "subscription" ], "type": "string" }, "payment_url": { "description": "Set when a plan change could not be paid yet (the card was declined, or the bank asks the cardholder to confirm): pay here within a day and the change applies. Null otherwise.", "type": [ "string", "null" ] }, "plan": { "description": "The plan paid for now (catalog plan ID); payg without a monthly plan.", "type": "string" }, "status": { "description": "none (pay as you go), incomplete (the first payment is not through yet), active, past_due (the last renewal failed: Stripe retries it, and no new credits arrive until it is paid) or unpaid (the retries ended without payment).", "enum": [ "none", "incomplete", "active", "past_due", "unpaid" ], "type": "string" }, "top_up_pack": { "description": "The credit pack this plan's subscribers can top up with when they run out (catalog pack ID, also for auto top-up); null without a monthly plan.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "plan", "status", "next_plan", "cancel_at_period_end", "current_period_end", "monthly_credits", "monthly_credits_remaining", "top_up_pack", "payment_url", "notice" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Change the monthly plan", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Change the monthly plan", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": false, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_error" ] } } }, "/v1/billing/subscription/cancel": { "post": { "description": "Ends the account's monthly plan at the end of the month it is paid for, with no more charges and no refund for that month; monthly credits last until then, and pack and top-up credits stay. Until then, it can be undone. The dashboard session only, with no fresh sign-in: canceling only stops charges. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "billing.subscription.cancel", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cancel_at_period_end": { "description": "true ends the plan at current_period_end, with no more charges; monthly credits last until then. false keeps it renewing.", "type": "boolean" } }, "required": [ "cancel_at_period_end" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cancel_at_period_end": { "description": "Whether it ends at current_period_end instead of renewing. Monthly credits end with it; pack and top-up credits stay.", "type": "boolean" }, "current_period_end": { "description": "When this month's credits end and the plan renews, or ends: RFC 3339 UTC; null without a monthly plan.", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Subscription ID (sub_…); null without a monthly plan.", "type": [ "string", "null" ] }, "monthly_credits": { "description": "Credits the plan adds at each renewal; 0 without a monthly plan.", "type": "integer" }, "monthly_credits_remaining": { "description": "How much of the balance is monthly credits: requests spend these first, and what is left of them ends at the next renewal. The rest of the balance never expires.", "type": "integer" }, "next_plan": { "description": "The plan it changes to at the next renewal, after a downgrade; null when it stays on plan.", "type": [ "string", "null" ] }, "notice": { "description": "What a person should know about the plan change just made, in a sentence to show them: its renewal is also being charged, say, or auto top-up's monthly cap is now below the top-up's price. Null otherwise, and on every read.", "type": [ "string", "null" ] }, "object": { "description": "Always subscription.", "enum": [ "subscription" ], "type": "string" }, "payment_url": { "description": "Set when a plan change could not be paid yet (the card was declined, or the bank asks the cardholder to confirm): pay here within a day and the change applies. Null otherwise.", "type": [ "string", "null" ] }, "plan": { "description": "The plan paid for now (catalog plan ID); payg without a monthly plan.", "type": "string" }, "status": { "description": "none (pay as you go), incomplete (the first payment is not through yet), active, past_due (the last renewal failed: Stripe retries it, and no new credits arrive until it is paid) or unpaid (the retries ended without payment).", "enum": [ "none", "incomplete", "active", "past_due", "unpaid" ], "type": "string" }, "top_up_pack": { "description": "The credit pack this plan's subscribers can top up with when they run out (catalog pack ID, also for auto top-up); null without a monthly plan.", "type": [ "string", "null" ] } }, "required": [ "object", "id", "plan", "status", "next_plan", "cancel_at_period_end", "current_period_end", "monthly_credits", "monthly_credits_remaining", "top_up_pack", "payment_url", "notice" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Cancel the monthly plan, or undo it", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Cancel the monthly plan, or undo it", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress", "upstream_error" ] } } }, "/v1/billing/subscription/checkout": { "post": { "description": "Creates a Stripe Checkout session that starts a monthly plan; open the returned url to pay. The plan's credits are added when the first payment completes, and again at each renewal, when what was left of them ends. GET /v1/billing/checkout/{id} follows it. An account already on a plan changes it with PATCH /v1/billing/subscription instead. The dashboard session only: it starts recurring charges. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "billing.subscription.checkout", "parameters": [ { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "plan": { "description": "A public monthly plan's ID (catalog plans).", "maxLength": 20, "type": "string" } }, "required": [ "plan" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "description": "Checkout session ID (cs_…); GET /v1/billing/checkout/{id} follows it.", "type": "string" }, "object": { "description": "Always checkout_session.", "enum": [ "checkout_session" ], "type": "string" }, "url": { "description": "Stripe Checkout's page: open it to pay.", "type": "string" } }, "required": [ "object", "id", "url" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Start a monthly plan (Stripe Checkout)", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "session": [] } ], "summary": "Start a monthly plan (Stripe Checkout)", "tags": [ "Billing" ], "x-socialtap-auth": { "auth": "session", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress", "upstream_error" ] } } }, "/v1/bluesky/comments": { "get": { "description": "Returns the replies to a public Bluesky post, nested ones included, from its link or at:// ID, by most liked, newest or oldest. Each reply has parent_id saying what it answers, its text with hashtags, mentions and full link URLs, publish time, languages, labels, images and video, link card, the post it quotes, exact like, reply, repost, quote and bookmark counts, and the author with their verified badge and DID.\n\nReturns `{data, page, meta}`: `data` holds up to 1000 `Comment` items (the shared schema, the same on every platform), Most liked first, the replies Bluesky folds under \"Show more replies\" last with sort=popular (the default), newest first with sort=newest, oldest first with sort=oldest. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/bluesky/comments/ (Markdown: https://socialtap.dev/docs/reference/bluesky/comments/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/bluesky/comments/index.md)", "url": "https://socialtap.dev/docs/reference/bluesky/comments/" }, "operationId": "bluesky.comments.list", "parameters": [ { "description": "The post: its link (bsky.app/profile/bsky.app/post/3l6oveex3ii2l), by the account's handle or DID, with any route under it (/liked-by, /reposted-by, /quotes), the embed page's link, or its at:// ID (at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l). A comment's id or link lists the replies to that comment.", "example": "https://bsky.app/profile/atproto.com/post/3moduzldxr22q", "in": "query", "name": "url", "required": true, "schema": { "description": "The post: its link (bsky.app/profile/bsky.app/post/3l6oveex3ii2l), by the account's handle or DID, with any route under it (/liked-by, /reposted-by, /quotes), the embed page's link, or its at:// ID (at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l). A comment's id or link lists the replies to that comment.", "examples": [ "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l" ], "maxLength": 2048, "type": "string" } }, { "description": "Order of the results. popular (default): the most liked replies first, the ones Bluesky folds under \"Show more replies\" last. newest: newest first. oldest: oldest first. Each orders the whole list, nested replies among the rest; parent_id says what each replies to.", "example": "", "in": "query", "name": "sort", "schema": { "default": "popular", "description": "Order of the results. popular (default): the most liked replies first, the ones Bluesky folds under \"Show more replies\" last. newest: newest first. oldest: oldest first. Each orders the whole list, nested replies among the rest; parent_id says what each replies to.", "enum": [ "popular", "newest", "oldest" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 1000, "in": "query", "name": "limit", "schema": { "default": 1000, "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:rnpkyqnmsw4ipey6eotbdnnf/bafkreierosmj3aqp63zskykqo7ucl6vs4adep5op27tzkr6zhoxdaqjvjy", "display_name": "Bailey Townsend 🦀", "id": "did:plc:rnpkyqnmsw4ipey6eotbdnnf", "is_verified": true, "url": "https://bsky.app/profile/pds.dad", "username": "pds.dad" }, "edited_at": null, "id": "at://did:plc:rnpkyqnmsw4ipey6eotbdnnf/app.bsky.feed.post/3modvwakvu22v", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 11, "reply_count": 0 }, "parent_id": null, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreiba2dzwa45xz6yxqu7wbzoz52ni2qshhkcihwsdzjuk2hjnsjfgse", "created_at": "2026-06-15T18:26:52Z", "embedded_record_uri": null, "hashtags": [], "indexed_at": "2026-06-15T18:26:53Z", "is_hidden": false, "is_hidden_by_post_author": false, "is_nsfw": false, "labels": [], "languages": [ "en" ], "link_card": null, "links": [], "media": [], "mentions": [], "quote_count": 0, "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "repost_count": 0, "save_count": 0 } }, "post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "published_at": "2026-06-15T18:26:52Z", "text": "Not sure if it’s already be answered, but…\n\nWhat’s the migration story looking like? One export like a .car? Then to add on if it’s single export can the import process be looked at to be a bit nicer on memory for large imports (75mb+ ball park) 👀", "unknown_fields": [], "url": "https://bsky.app/profile/pds.dad/post/3modvwakvu22v" }, { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:mmyj7mk7kh3jqhw6zs4prbuk/bafkreiebc6p2hzm26gis7zkxc6cnljx2nf5jj5bne6quy7hz4in2bcq4ju", "display_name": "Meri", "id": "did:plc:mmyj7mk7kh3jqhw6zs4prbuk", "is_verified": false, "url": "https://bsky.app/profile/meri.garden", "username": "meri.garden" }, "edited_at": null, "id": "at://did:plc:mmyj7mk7kh3jqhw6zs4prbuk/app.bsky.feed.post/3moelxyfdqk2j", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 9, "reply_count": 0 }, "parent_id": null, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreib7kgmwpcgv3szz73cdr5e4m6accssoqhhc2dmzt4fomifci3mpw4", "created_at": "2026-06-16T01:01:32Z", "embedded_record_uri": null, "hashtags": [], "indexed_at": "2026-06-16T01:01:34Z", "is_hidden": false, "is_hidden_by_post_author": false, "is_nsfw": false, "labels": [], "languages": [ "en" ], "link_card": null, "links": [], "media": [], "mentions": [], "quote_count": 0, "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "repost_count": 2, "save_count": 0 } }, "post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "published_at": "2026-06-16T01:01:32Z", "text": "I'm wondering about Bluesky group chats - will these be migrated to permissioned spaces when they are ready? And will ownership of those spaces be transferrable (seperate DID)?", "unknown_fields": [], "url": "https://bsky.app/profile/meri.garden/post/3moelxyfdqk2j" }, { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:wzjoqxvghocxiu6sn4xwtyfh/bafkreicbgmp5ojmrrpcenvqdcyq6i2df66sjhck6zos3g55yeuerf5ljaq", "display_name": "woke oak", "id": "did:plc:wzjoqxvghocxiu6sn4xwtyfh", "is_verified": false, "url": "https://bsky.app/profile/oakley.bsky.social", "username": "oakley.bsky.social" }, "edited_at": null, "id": "at://did:plc:wzjoqxvghocxiu6sn4xwtyfh/app.bsky.feed.post/3modvdlxrtk23", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 4, "reply_count": 0 }, "parent_id": null, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreif7xabmmlxz43bgd5v7id73qi7sqbgloqsueadrbo7uwgdd63uvzy", "created_at": "2026-06-15T18:16:26Z", "embedded_record_uri": null, "hashtags": [], "indexed_at": "2026-06-15T18:16:26Z", "is_hidden": false, "is_hidden_by_post_author": false, "is_nsfw": false, "labels": [], "languages": [ "en" ], "link_card": null, "links": [], "media": [], "mentions": [], "quote_count": 0, "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "repost_count": 0, "save_count": 0 } }, "post_id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "published_at": "2026-06-15T18:16:26Z", "text": "what's the rollout gonna look like? bluesky was a private beta to test the protocol with a separate federation sandbox for months before either publicly launched, will anything similar here happen? \n\ncan i have an invite?", "unknown_fields": [], "url": "https://bsky.app/profile/oakley.bsky.social/post/3modvdlxrtk23" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "bluesky", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 329, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3moduzldxr22q", "url": "https://bsky.app/profile/atproto.com/post/3moduzldxr22q" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "end" } } } }, "schema": { "$ref": "#/components/schemas/BlueskyCommentsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Replies to a post, nested ones included", "tags": [ "Bluesky" ], "x-socialtap-endpoint": "bluesky.comments", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Most liked first, the replies Bluesky folds under \"Show more replies\" last", "orders": { "newest": "newest first", "oldest": "oldest first", "popular": "Most liked first, the replies Bluesky folds under \"Show more replies\" last" }, "page_max": 1000, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "comment", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/bluesky/post": { "get": { "description": "Returns a public Bluesky post from any of its links or its at:// ID, with exact like, reply, repost, quote and bookmark counts. It also has the full text with hashtags, mentions and full link URLs, the publish time, languages, images and video with alt text, the link card, the post it quotes, the post it replies to and the thread's root, moderation labels, and the author with their verified badge and stable DID.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/bluesky/post/ (Markdown: https://socialtap.dev/docs/reference/bluesky/post/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/bluesky/post/index.md)", "url": "https://socialtap.dev/docs/reference/bluesky/post/" }, "operationId": "bluesky.post.get", "parameters": [ { "description": "The post: its link (bsky.app/profile/bsky.app/post/3l6oveex3ii2l), by the account's handle or DID, with any route under it (/liked-by, /reposted-by, /quotes), the embed page's link, or its at:// ID (at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l), which is the id every answer gives. The short key at the end of a link names no post without its account.", "example": "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l", "in": "query", "name": "url", "required": true, "schema": { "description": "The post: its link (bsky.app/profile/bsky.app/post/3l6oveex3ii2l), by the account's handle or DID, with any route under it (/liked-by, /reposted-by, /quotes), the embed page's link, or its at:// ID (at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l), which is the id every answer gives. The short key at the end of a link names no post without its account.", "examples": [ "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:z72i7hdynmk6r22z27h6tvur/bafkreihwihm6kpd6zuwhhlro75p5qks5qtrcu55jp3gddbfjsieiv7wuka", "display_name": "Bluesky", "id": "did:plc:z72i7hdynmk6r22z27h6tvur", "is_verified": true, "url": "https://bsky.app/profile/bsky.app", "username": "bsky.app" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l", "is_nsfw": false, "is_pinned": null, "is_sponsored": null, "language": "en", "media": [], "mentions": [], "metrics": { "comment_count": 8711, "like_count": 63751, "quote_count": 723, "repost_count": 9550, "save_count": 276, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreicnt42y6vo6pfpvyro234ac4o6ijug6adwwrh7awflgrqlt4zibxq", "created_at": "2024-10-17T07:06:51Z", "embedded_record_uri": null, "indexed_at": "2024-10-17T07:06:51Z", "labels": [], "languages": [ "en" ], "link_card": null, "links": [], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2024-10-17T07:06:51Z", "text": "👋 Bluesky is an open social network that gives creators independence from platforms, developers the freedom to build, and users a choice in their experience. We're so excited to have you here! \n\nWe share Bluesky updates & news from this account. A quick orientation thread: 🧵✨", "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "bluesky", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 206, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l", "url": "https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/BlueskyPostResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Exact likes, replies, reposts and quotes", "tags": [ "Bluesky" ], "x-socialtap-endpoint": "bluesky.post", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/bluesky/posts": { "get": { "description": "Returns a public Bluesky account's posts and reposts from its handle, DID or profile link, as the tabs of its profile list them. Ask for its replies too, or only posts with media or video. Each post has its link, publish time, full text with hashtags, mentions and full link URLs, images and video, link card, quote and reply, the pin, and exact like, reply, repost, quote and bookmark counts. A repost also says who reposted it and when.\n\nReturns `{data, page, meta}`: `data` holds up to 100 `Post` items (the shared schema, the same on every platform), most recent activity first: a post by when it was posted, a repost by when it was reposted. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/bluesky/posts/ (Markdown: https://socialtap.dev/docs/reference/bluesky/posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/bluesky/posts/index.md)", "url": "https://socialtap.dev/docs/reference/bluesky/posts/" }, "operationId": "bluesky.posts.list", "parameters": [ { "description": "The Bluesky account: its handle, with or without the @ (alice.bsky.social, espn.com), its DID (did:plc:z72i7hdynmk6r22z27h6tvur, did:web:didweb.watch), which is the id every answer gives, or a link to its profile.", "example": "espn.com", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Bluesky account: its handle, with or without the @ (alice.bsky.social, espn.com), its DID (did:plc:z72i7hdynmk6r22z27h6tvur, did:web:didweb.watch), which is the id every answer gives, or a link to its profile.", "examples": [ "espn.com" ], "maxLength": 2048, "type": "string" } }, { "description": "Which of the profile's tabs to list: posts (default): its posts, its own threads and its reposts, without its replies to others; replies: those too; media: its posts with images or video; video: its posts with a video.", "example": "replies", "in": "query", "name": "tab", "schema": { "description": "Which of the profile's tabs to list: posts (default): its posts, its own threads and its reposts, without its replies to others; replies: those too; media: its posts with images or video; video: its posts with a video.", "enum": [ "posts", "replies", "media", "video" ], "examples": [ "replies" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, so a recent repost of an older post is left out. The walk stops once the list is older than this.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, so a recent repost of an older post is left out. The walk stops once the list is older than this.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). The list starts at this time, so a later repost isn't listed, even of an older post, and is_pinned is null.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). The list starts at this time, so a later repost isn't listed, even of an older post, and is_pinned is null.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:x7d6j54pm22ufehkes6jo4jf/bafkreie4oxawqqsfzvk47ysr3unsnmviedzpylxmwxnpa534to2bzas4ie", "display_name": "ESPN", "id": "did:plc:x7d6j54pm22ufehkes6jo4jf", "is_verified": true, "url": "https://bsky.app/profile/espn.com", "username": "espn.com" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "at://did:plc:x7d6j54pm22ufehkes6jo4jf/app.bsky.feed.post/3muznlkmspz2x", "is_nsfw": false, "is_pinned": false, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": "https://video.bsky.app/watch/did%3Aplc%3Ax7d6j54pm22ufehkes6jo4jf/bafkreiflqivgi6afl5jv4qnmwzo3ks7jwe2dfurohsjfgafbtd5crw4gaq/thumbnail.jpg", "type": "video", "url": "https://video.bsky.app/watch/did%3Aplc%3Ax7d6j54pm22ufehkes6jo4jf/bafkreiflqivgi6afl5jv4qnmwzo3ks7jwe2dfurohsjfgafbtd5crw4gaq/playlist.m3u8", "width": null } ], "mentions": [], "metrics": { "comment_count": 15, "like_count": 103, "quote_count": 7, "repost_count": 11, "save_count": 0, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreiceaay7jrgqznvxhttsmizofewx3mj6bwebjtz76nd2wh4hix4fty", "created_at": "2026-09-08T18:27:24Z", "embedded_record_uri": null, "indexed_at": "2026-09-08T18:27:30Z", "labels": [], "languages": [], "link_card": null, "links": [], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2026-09-08T18:27:24Z", "text": "One more sleep until NFL football is BACK. 🏈", "thumbnail_url": "https://video.bsky.app/watch/did%3Aplc%3Ax7d6j54pm22ufehkes6jo4jf/bafkreiflqivgi6afl5jv4qnmwzo3ks7jwe2dfurohsjfgafbtd5crw4gaq/thumbnail.jpg", "title": null, "type": "video", "unknown_fields": [], "url": "https://bsky.app/profile/espn.com/post/3muznlkmspz2x" }, { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:x7d6j54pm22ufehkes6jo4jf/bafkreie4oxawqqsfzvk47ysr3unsnmviedzpylxmwxnpa534to2bzas4ie", "display_name": "ESPN", "id": "did:plc:x7d6j54pm22ufehkes6jo4jf", "is_verified": true, "url": "https://bsky.app/profile/espn.com", "username": "espn.com" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "at://did:plc:x7d6j54pm22ufehkes6jo4jf/app.bsky.feed.post/3mpglmolczz2w", "is_nsfw": false, "is_pinned": false, "is_sponsored": null, "language": null, "media": [], "mentions": [], "metrics": { "comment_count": 17, "like_count": 139, "quote_count": 16, "repost_count": 34, "save_count": 1, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreid2eoctnshw7unb5ozrjqsy63kpqmwwvhj2xuxsfo4z5zucfazqum", "created_at": "2026-06-29T13:25:44Z", "embedded_record_uri": null, "indexed_at": "2026-06-29T13:25:45Z", "labels": [], "languages": [], "link_card": { "description": "Former Titans and Cardinals running back Chris Johnson told \"Good Morning America\" that he was diagnosed with ALS in 2025.", "thumbnail_url": "https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:x7d6j54pm22ufehkes6jo4jf/bafkreicgzhnme4wgvolagtic3dki5icwfkmlxz23cmakg2mj2h4xkwvg2q", "title": "Former NFL RB Chris Johnson discusses ALS diagnosis", "url": "http://spr.ly/63329BDvG6W" }, "links": [], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2026-06-29T13:25:44Z", "text": "Former Tennessee Titans and Arizona Cardinals running back Chris Johnson revealed that he has been diagnosed with ALS in an interview with ABC's \"Good Morning America\".\n\nJohnson, 39, told GMA co-anchor Michael Strahan that he was diagnosed with the disease in 2025.", "thumbnail_url": "https://cdn.bsky.app/img/feed_thumbnail/plain/did:plc:x7d6j54pm22ufehkes6jo4jf/bafkreicgzhnme4wgvolagtic3dki5icwfkmlxz23cmakg2mj2h4xkwvg2q", "title": null, "type": "link", "unknown_fields": [], "url": "https://bsky.app/profile/espn.com/post/3mpglmolczz2w" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "bluesky", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 449, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "did:plc:x7d6j54pm22ufehkes6jo4jf", "url": "https://bsky.app/profile/espn.com" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/BlueskyPostsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Posts and reposts with exact counts", "tags": [ "Bluesky" ], "x-socialtap-endpoint": "bluesky.posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "most recent activity first: a post by when it was posted, a repost by when it was reposted", "page_max": 100, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/bluesky/profile": { "get": { "description": "Returns a public Bluesky profile from its handle, DID or link, with exact follower, following and post counts. It also has the stable DID and current handle, display name, bio, pronouns, avatar, banner, join date, the verified badge with who verified the account and when, its links with their titles, labels such as bot, its pinned post, and how many lists, custom feeds and starter packs it made.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/bluesky/profile/ (Markdown: https://socialtap.dev/docs/reference/bluesky/profile/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/bluesky/profile/index.md)", "url": "https://socialtap.dev/docs/reference/bluesky/profile/" }, "operationId": "bluesky.profile.get", "parameters": [ { "description": "The Bluesky account: its handle, a domain name (espn.com, alice.bsky.social), with or without the @; its DID (did:plc:z72i7hdynmk6r22z27h6tvur or did:web:…), which is the id every answer gives and survives a change of handle; or its link (https://bsky.app/profile/bsky.app), by handle or DID, with any tab under it. A word without a dot is no handle: Bluesky's own are written in full, as alice.bsky.social.", "example": "espn.com", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Bluesky account: its handle, a domain name (espn.com, alice.bsky.social), with or without the @; its DID (did:plc:z72i7hdynmk6r22z27h6tvur or did:web:…), which is the id every answer gives and survives a change of handle; or its link (https://bsky.app/profile/bsky.app), by handle or DID, with any tab under it. A word without a dot is no handle: Bluesky's own are written in full, as alice.bsky.social.", "examples": [ "bsky.app" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:x7d6j54pm22ufehkes6jo4jf/bafkreie4oxawqqsfzvk47ysr3unsnmviedzpylxmwxnpa534to2bzas4ie", "banner_url": null, "bio": "Serving sports fans. Anytime. Anywhere.", "category": null, "country_code": null, "created_at": "2024-11-25T21:49:49Z", "display_name": "ESPN", "external_links": [], "id": "did:plc:x7d6j54pm22ufehkes6jo4jf", "is_private": false, "is_verified": true, "location": null, "metrics": { "follower_count": 305103, "following_count": 32, "post_count": 872, "total_like_count": null, "total_view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "feed_count": 0, "indexed_at": "2024-12-19T20:49:48Z", "is_labeler": false, "is_trusted_verifier": false, "labels": [], "list_count": 0, "pinned_post_id": null, "pronouns": null, "starter_pack_count": 0, "verified_by": [ { "created_at": "2025-04-21T10:44:20Z", "id": "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.graph.verification/3lndppjqgb72f", "is_valid": true, "issuer": { "avatar_url": null, "display_name": "Bluesky", "id": "did:plc:z72i7hdynmk6r22z27h6tvur", "is_verified": null, "url": "https://bsky.app/profile/bsky.app", "username": "bsky.app" } } ] } }, "type": "unknown", "unknown_fields": [], "url": "https://bsky.app/profile/espn.com", "username": "espn.com" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "bluesky", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 196, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "did:plc:x7d6j54pm22ufehkes6jo4jf", "url": "https://bsky.app/profile/espn.com" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/BlueskyProfileResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Exact follower counts, bio, links and DID", "tags": [ "Bluesky" ], "x-socialtap-endpoint": "bluesky.profile", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/bluesky/search_posts": { "get": { "description": "Returns public Bluesky posts that match your words, newest or top first, filtered by date, language, author, mention, hashtag or site. Each post has its link, publish time, full text with hashtags, mentions and full link URLs, images and video, link card, quote and reply, and exact like, reply, repost, quote and bookmark counts. Page back through the newest-first results with the cursor.\n\nReturns `{data, page, meta}`: `data` holds up to 100 `Post` items (the shared schema, the same on every platform), newest first, by the time each post states, to the second with sort=newest (the default), Bluesky's Top ranking with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/bluesky/search_posts/ (Markdown: https://socialtap.dev/docs/reference/bluesky/search_posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/bluesky/search_posts/index.md)", "url": "https://socialtap.dev/docs/reference/bluesky/search_posts/" }, "operationId": "bluesky.search_posts.list", "parameters": [ { "description": "Words to find posts by, as Bluesky's search reads them: a topic, a phrase in quotes, a #hashtag or an @handle, and a leading - leaves a word out (climate change, \"coffee roaster\" -bean, #atproto). Bluesky's own from:, to:, mentions:, since:, until:, lang: and domain: operators are read as this endpoint's params.", "example": "bitcoin", "in": "query", "name": "query", "required": true, "schema": { "description": "Words to find posts by, as Bluesky's search reads them: a topic, a phrase in quotes, a #hashtag or an @handle, and a leading - leaves a word out (climate change, \"coffee roaster\" -bean, #atproto). Bluesky's own from:, to:, mentions:, since:, until:, lang: and domain: operators are read as this endpoint's params.", "examples": [ "climate change" ], "maxLength": 200, "type": "string" } }, { "description": "Order of the results. newest (default): newest first, a page after a page back through time. popular: Bluesky's Top ranking, which favours posts with engagement, one page only.", "example": "newest", "in": "query", "name": "sort", "schema": { "default": "newest", "description": "Order of the results. newest (default): newest first, a page after a page back through time. popular: Bluesky's Top ranking, which favours posts with engagement, one page only.", "enum": [ "newest", "popular" ], "type": "string" } }, { "description": "Only posts by this account: a handle, a DID or a profile link.", "example": "espn.com", "in": "query", "name": "author", "schema": { "description": "Only posts by this account: a handle, a DID or a profile link.", "examples": [ "espn.com" ], "maxLength": 300, "type": "string" } }, { "description": "Only posts that mention this account: a handle, a DID or a profile link.", "example": "nasa.gov", "in": "query", "name": "mentions", "schema": { "description": "Only posts that mention this account: a handle, a DID or a profile link.", "examples": [ "nasa.gov" ], "maxLength": 300, "type": "string" } }, { "description": "Only posts with this hashtag, with or without the #.", "example": "atproto", "in": "query", "name": "tag", "schema": { "description": "Only posts with this hashtag, with or without the #.", "examples": [ "atproto" ], "maxLength": 100, "type": "string" } }, { "description": "Only posts that link to this domain or a subdomain of it.", "example": "espn.com", "in": "query", "name": "domain", "schema": { "description": "Only posts that link to this domain or a subdomain of it.", "examples": [ "espn.com" ], "maxLength": 253, "type": "string" } }, { "description": "Only posts that link to this page: a full URL.", "example": "https://www.nytimes.com/", "in": "query", "name": "links_to", "schema": { "description": "Only posts that link to this page: a full URL.", "examples": [ "https://www.nytimes.com/" ], "maxLength": 2000, "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only posts in this language, by the tags their author set: a BCP-47 tag, of which Bluesky reads the language alone (pt-BR finds what pt finds).", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only posts in this language, by the tags their author set: a BCP-47 tag, of which Bluesky reads the language alone (pt-BR finds what pt finds).", "examples": [ "en" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. By the post's stated time, to the second.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. By the post's stated time, to the second.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). By the post's stated time, to the second.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). By the post's stated time, to the second.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:hlod3gl5ewwglnr4yarddcrk/bafkreihy5kd5vnqqs77wtxzdf5kdyq24x23vtawwb5knkz7wh5yesamsoy", "display_name": "Swiss Whale Intelligence 🇨🇭", "id": "did:plc:hlod3gl5ewwglnr4yarddcrk", "is_verified": false, "url": "https://bsky.app/profile/btcwhalealerts.com", "username": "btcwhalealerts.com" }, "coauthors": [], "duration_ms": null, "hashtags": [ "Bitcoin", "Crypto" ], "id": "at://did:plc:hlod3gl5ewwglnr4yarddcrk/app.bsky.feed.post/3mzjyfostuj2n", "is_nsfw": false, "is_pinned": null, "is_sponsored": null, "language": "en", "media": [], "mentions": [], "metrics": { "comment_count": 0, "like_count": 0, "quote_count": 0, "repost_count": 0, "save_count": 0, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreiduygaoktbbpfbii3ds5d4nkmu5c3yfjwqvlwkeqzrhoxa5gxpgvy", "created_at": "2026-11-05T04:04:24Z", "embedded_record_uri": null, "indexed_at": "2026-11-05T04:04:24Z", "labels": [], "languages": [ "en" ], "link_card": null, "links": [ "https://swisswhaleintelligence.com/tx/8b044d3165b582ac112c14b3afc7ff017dba8bd3f124b03dbbf9912a27e0bfaa" ], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2026-11-05T04:04:24Z", "text": "🐳 4,259 BTC ($343.7M) whale transfer\nPast similar activity: avg -2.2% price drop 72h after.\n\nhttps://swisswhaleintelligence.com/tx/8b044d3165b582ac112c14b3afc7ff017dba8bd3f124b03dbbf9912a27e0bfaa #Bitcoin #Crypto", "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://bsky.app/profile/btcwhalealerts.com/post/3mzjyfostuj2n" }, { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:pnmlwvud7rkanzzns5nanon6/bafkreibjn6xzku5qrjmp4s7abkf753wh5h7youodu7jgynnwtnwtbl2ciu", "display_name": "Pandavana Crypto News", "id": "did:plc:pnmlwvud7rkanzzns5nanon6", "is_verified": false, "url": "https://bsky.app/profile/pandacrypto.bsky.social", "username": "pandacrypto.bsky.social" }, "coauthors": [], "duration_ms": null, "hashtags": [ "Crypto", "Solana" ], "id": "at://did:plc:pnmlwvud7rkanzzns5nanon6/app.bsky.feed.post/3mzjyf2labq2g", "is_nsfw": false, "is_pinned": null, "is_sponsored": null, "language": null, "media": [], "mentions": [], "metrics": { "comment_count": 0, "like_count": 0, "quote_count": 0, "repost_count": 0, "save_count": 0, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreibohrvfnua3lpwuaqnnfssupil4q64mrmtzlktlqchfuqzrnubx3e", "created_at": "2026-11-05T04:04:02Z", "embedded_record_uri": null, "indexed_at": "2026-11-05T04:04:03Z", "labels": [], "languages": [], "link_card": null, "links": [], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2026-11-05T04:04:02Z", "text": "#Crypto Prices:\r\n\r\nBitcoin $80,414.50\r\nEthereum $2,418.80\r\nXRP $1.31\r\n#Solana $96.16\r\nSui $0.93\r\n\r\n\r\n", "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://bsky.app/profile/pandacrypto.bsky.social/post/3mzjyf2labq2g" }, { "approximate_fields": [], "author": { "avatar_url": "https://cdn.bsky.app/img/avatar/plain/did:plc:vjpyc66fyniyqp2v6j7mxdvm/bafkreicg6htpnqv6cih6dhdxemkzugqmg4sqpgsfys5stz74ckwocynnoi", "display_name": "miatone.bsky.social", "id": "did:plc:vjpyc66fyniyqp2v6j7mxdvm", "is_verified": false, "url": "https://bsky.app/profile/miatone.bsky.social", "username": "miatone.bsky.social" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "at://did:plc:vjpyc66fyniyqp2v6j7mxdvm/app.bsky.feed.post/3mzjya6ieog2l", "is_nsfw": false, "is_pinned": null, "is_sponsored": null, "language": null, "media": [], "mentions": [], "metrics": { "comment_count": 0, "like_count": 0, "quote_count": 0, "repost_count": 0, "save_count": 0, "share_count": null, "view_count": null }, "platform": "bluesky", "platform_specific": { "bluesky": { "bridged_from_url": null, "cid": "bafyreib4vxlqmmhsycxfkhzj27k4466dgooh2rbmiod3gqf2bey3ryiqxu", "created_at": "2026-11-05T04:01:18Z", "embedded_record_uri": null, "indexed_at": "2026-11-05T04:01:19Z", "labels": [], "languages": [], "link_card": null, "links": [], "quoted_post": null, "quoted_post_id": null, "reply_root_post_id": null, "reply_to_post_id": null, "reposted_at": null, "reposted_by": null } }, "platform_type": null, "published_at": "2026-11-05T04:01:18Z", "text": "This caught my attention today: Nearly $1 Billion in Crypto Liquidations Hit as Bitcoin Jumps 4.6%", "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://bsky.app/profile/miatone.bsky.social/post/3mzjya6ieog2l" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "bluesky", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 560, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/BlueskySearch_postsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Posts by keyword, hashtag, author or link", "tags": [ "Bluesky" ], "x-socialtap-endpoint": "bluesky.search_posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "newest first, by the time each post states, to the second", "orders": { "newest": "newest first, by the time each post states, to the second", "popular": "Bluesky's Top ranking" }, "page_max": 100, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/credit_transactions": { "get": { "description": "Every change to the balance, newest first, cursor-paged: grants (free credits), purchases, hourly usage roll-ups and adjustments. Per-request detail is in GET /v1/usage. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "credit_transactions.list", "parameters": [ { "description": "Only this kind.", "in": "query", "name": "type", "schema": { "enum": [ "grant", "promo", "purchase", "plan", "usage", "adjustment" ], "type": "string" } }, { "description": "Created at or after: RFC 3339 or a date (UTC).", "in": "query", "name": "since", "schema": { "maxLength": 40, "type": "string" } }, { "description": "Created before: RFC 3339 or a date (UTC).", "in": "query", "name": "until", "schema": { "maxLength": 40, "type": "string" } }, { "description": "Transactions per page (default 25, at most 100).", "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor of the previous page.", "in": "query", "name": "cursor", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "This page's items.", "items": { "properties": { "balance_after": { "description": "The ledger's balance after this transaction. Usage is recorded hourly, so the live balance (GET /v1/account) may be lower.", "type": "integer" }, "created_at": { "description": "When it was recorded, RFC 3339 UTC.", "format": "date-time", "type": "string" }, "credits": { "description": "Credits added (positive) or spent (negative).", "type": "integer" }, "description": { "description": "What it was, for humans.", "type": "string" }, "id": { "description": "Transaction ID (ctx_…).", "type": "string" }, "object": { "description": "Always credit_transaction.", "enum": [ "credit_transaction" ], "type": "string" }, "type": { "description": "grant: free credits (signup) or a goodwill grant; promo: a promo code's credits; purchase: a credit pack; plan: a monthly plan's credits added, or what was left of them ended at renewal; usage: credits spent, rolled up per hour; adjustment: a correction by support, unspent credits of a refunded or disputed purchase taken back, or given back when a dispute is won. New values may be added.", "enum": [ "grant", "promo", "purchase", "plan", "usage", "adjustment" ], "type": "string" } }, "required": [ "object", "id", "type", "credits", "balance_after", "description", "created_at" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "page": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages" ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" } }, "required": [ "data", "page", "meta" ], "type": "object" } } }, "description": "List credit transactions (the ledger)", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "List credit transactions (the ledger)", "tags": [ "Account" ], "x-socialtap-auth": { "auth": "key", "role": "member", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/events": { "get": { "description": "Every event of the account, newest first, whether or not a webhook endpoint received it: what webhooks would have delivered. Kept `events_retention_s` (30 days). Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "events.list", "parameters": [ { "description": "Only events of this type (an event type, or a prefix wildcard such as job.*).", "in": "query", "name": "type", "schema": { "maxLength": 64, "type": "string" } }, { "description": "Events per page (default and maximum 100).", "in": "query", "name": "limit", "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor of the previous page; omit to start from the newest.", "in": "query", "name": "cursor", "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "This page's items.", "items": { "properties": { "data": { "description": "The type's data object (small: a summary plus links)." }, "id": { "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.", "type": "string" }, "object": { "description": "Always event.", "enum": [ "event" ], "type": "string" }, "timestamp": { "description": "When it happened.", "format": "date-time", "type": "string" }, "type": { "description": "The event type (event types table); new types may be added.", "type": "string" } }, "required": [ "object", "id", "type", "timestamp", "data" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "page": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages" ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" } }, "required": [ "data", "page", "meta" ], "type": "object" } } }, "description": "List events, newest first", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "List events, newest first", "tags": [ "Events" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/events/{id}": { "get": { "description": "One event, as webhooks deliver it. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.", "operationId": "events.get", "parameters": [ { "description": "Event ID (evt_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "data": { "description": "The type's data object (small: a summary plus links)." }, "id": { "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.", "type": "string" }, "object": { "description": "Always event.", "enum": [ "event" ], "type": "string" }, "timestamp": { "description": "When it happened.", "format": "date-time", "type": "string" }, "type": { "description": "The event type (event types table); new types may be added.", "type": "string" } }, "required": [ "object", "id", "type", "timestamp", "data" ], "type": "object" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "Get an event", "headers": { "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get an event", "tags": [ "Events" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "account:read" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited" ] } } }, "/v1/events/{id}/redeliver": { "post": { "description": "Queues a new delivery of the event (same `webhook-id`, so receivers deduplicate it) to one endpoint, or to every enabled endpoint subscribed to its type. The answer lists the deliveries queued (one page). Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.", "operationId": "events.redeliver", "parameters": [ { "description": "Event ID (evt_…).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.", "in": "header", "name": "idempotency-key", "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "webhook_endpoint_id": { "description": "Deliver to this endpoint only; default: every enabled endpoint subscribed to the event's type.", "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "This page's items.", "items": { "properties": { "attempts": { "description": "Attempts made so far.", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "delivered_at": { "format": "date-time", "type": [ "string", "null" ] }, "duration_ms": { "description": "The last attempt's duration.", "type": [ "integer", "null" ] }, "error": { "description": "Why the last attempt failed when there was no response.", "type": [ "string", "null" ] }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "id": { "description": "whd_…", "type": "string" }, "next_attempt_at": { "format": "date-time", "type": [ "string", "null" ] }, "object": { "description": "Always webhook_delivery.", "enum": [ "webhook_delivery" ], "type": "string" }, "response_excerpt": { "description": "The start of the last response body.", "type": [ "string", "null" ] }, "status": { "description": "pending: an attempt is due (next_attempt_at). failed: every attempt failed, or the endpoint was disabled or deleted.", "enum": [ "pending", "succeeded", "failed" ], "type": "string" }, "status_code": { "description": "The last attempt's HTTP status; null when it got none (timeout, refused, blocked URL).", "type": [ "integer", "null" ] }, "webhook_endpoint_id": { "type": "string" } }, "required": [ "object", "id", "event_id", "event_type", "webhook_endpoint_id", "status", "attempts", "status_code", "duration_ms", "response_excerpt", "error", "created_at", "delivered_at", "next_attempt_at" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "client_request_id": { "description": "Your x-client-request-id, echoed; null when you sent none.", "type": [ "string", "null" ] }, "credits_charged": { "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).", "type": "integer" }, "credits_remaining": { "description": "Account balance; null without an account (signup) or when SocialTap could not read it.", "type": [ "integer", "null" ] }, "request_id": { "description": "Unique request ID; include it when contacting support.", "type": "string" }, "warnings": { "description": "Things to act on that did not fail the request. [] when none.", "items": { "properties": { "code": { "description": "Machine-readable warning code (see the warnings list). New codes may be added.", "type": "string" }, "doc_url": { "description": "Where to read more (the changelog entry, the endpoint's docs).", "type": "string" }, "fields": { "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.", "items": { "type": "string" }, "type": "array" }, "message": { "description": "What to do about it.", "type": "string" } }, "required": [ "code", "message", "doc_url" ], "type": "object" }, "type": "array" } }, "required": [ "request_id", "credits_charged", "credits_remaining", "client_request_id", "warnings" ], "type": "object" }, "page": { "properties": { "end_reason": { "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.", "enum": [ "end", "platform_limit", "max_pages" ], "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.", "type": "boolean" }, "next_cursor": { "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.", "type": [ "string", "null" ] }, "next_cursor_expires_at": { "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "has_more", "next_cursor", "next_cursor_expires_at", "end_reason" ], "type": "object" } }, "required": [ "data", "page", "meta" ], "type": "object" } } }, "description": "Deliver an event again", "headers": { "idempotent-replayed": { "$ref": "#/components/headers/idempotent-replayed" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "409": { "content": { "application/json": { "examples": { "idempotency_key_in_progress": { "$ref": "#/components/examples/idempotency_key_in_progress" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the seconds in the retry-after header to get that request's result.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "$ref": "#/components/examples/idempotency_key_reused" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`idempotency_key_reused`: This Idempotency-Key was already used for a different request (another route or body). Or it was used for this same request, which ran and returned a secret we no longer keep (details.reason answer_expired): running it again would create another. Use a new Idempotency-Key for a different request, and reuse a key only to retry the identical request. With reason answer_expired, check what the first request created (GET /v1/api_keys, GET /v1/webhook_endpoints) before sending it again under a new key.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Deliver an event again", "tags": [ "Events" ], "x-socialtap-auth": { "auth": "key", "role": "admin", "scope": "admin" }, "x-socialtap-pricing": { "max_credits": 0, "min_credits": 0, "prices": [], "unit": "request" }, "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "idempotency_key_in_progress" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "idempotency_key_in_progress" ] } } }, "/v1/facebook/ad": { "get": { "description": "Returns one ad from Meta's public Ad Library by its link or Library ID: its creatives, the days it ran, where it ran and who ran it. Each creative has its headline, text, link, call to action, images and videos, and the advertiser comes with its Page's likes, category, badge and linked Instagram account. Ads shown in the EU or the UK add the payer, beneficiary, targeting and reach by country, age and gender. Political and social-issue ads add Meta's impression, reach and spend ranges, and a branded content ad names its creator.\n\nReturns `{data, meta}`: `data` is a `Ad` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/ad/ (Markdown: https://socialtap.dev/docs/reference/facebook/ad/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/ad/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/ad/" }, "operationId": "facebook.ad.get", "parameters": [ { "description": "The ad's Meta Ad Library link (facebook.com/ads/library/?id=…), the official Ad Library API's ad_snapshot_url (facebook.com/ads/archive/render_ad/?id=…), or its Library ID.", "example": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=DE&id=1103375555695370&media_type=all", "in": "query", "name": "url", "required": true, "schema": { "description": "The ad's Meta Ad Library link (facebook.com/ads/library/?id=…), the official Ad Library API's ad_snapshot_url (facebook.com/ads/archive/render_ad/?id=…), or its Library ID.", "examples": [ "https://www.facebook.com/ads/library/?id=1448538159982118" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/792344054_2357663855066869_6663139051388824991_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "Esso", "id": "124748157936817", "is_verified": false, "url": "https://www.facebook.com/EssoDeutschland", "username": "EssoDeutschland" }, "approximate_fields": [ "country_codes", "first_shown_at" ], "audience_size": null, "country_codes": [ "DE" ], "creatives": [ { "body": "Tanken, Snacks oder einen Kaffee? Das alles und viel mehr erwartet dich bei Esso.", "cta_text": "Learn More", "link_description": null, "link_url": "https://www.esso.de/de-de/damit-fahren-wir-besser?utm_source=facebook&utm_medium=paidsocial&utm_campaign=masterbrand_2026_2hy&utm_term=backcourt&utm_content=1x1", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/790643179_1059949036747222_1732898320488340543_n.jpg?_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "type": "video", "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQND9e-BMjtzqCZ0FbPblGYcGQ8j6vUBXYkHq85AodwUFgS3orA-sRXh9lT5UbtsmnSpwL_ot094eYeH8PrC-ESExk25IqvuuNNAuelnG27pCQ.mp4?_nc_cat=107&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": null } ], "title": "Kraftstoff fürs Auto. Energie für dich." }, { "body": "Tanken, Snacks oder einen Kaffee? Das alles und viel mehr erwartet dich bei Esso.", "cta_text": "Learn More", "link_description": null, "link_url": "https://www.esso.de/de-de/damit-fahren-wir-besser?utm_source=facebook&utm_medium=paidsocial&utm_campaign=masterbrand_2026_2hy&utm_term=backcourt&utm_content=1x1", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/793483318_2138943053709897_6112027891760479229_n.jpg?_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "type": "video", "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQOafqMPVLeUIBX39JYn6sJ6wu5hquY_pveq5cGWgLn5xbkWjWgCf3pq3ti3P2iXiQZ-wnATW_Vp5elabdXMmVFrQaPqu88jW3VEEQj6J0hvaw.mp4?_nc_cat=103&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": null } ], "title": "Kraftstoff fürs Auto. Energie für dich." } ], "first_shown_at": "2026-09-07T07:00:00Z", "id": "1103375555695370", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": "Esso", "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Energy Company" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 73755, "beneficiary": "Esso", "collation_count": null, "collation_id": null, "cta_type": "learn_more", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": false, "is_synthetic": false, "link_caption": "esso.de", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [ { "age_max": 65, "age_min": 18, "genders": [], "locations": [ { "is_excluded": false, "name": "Germany", "type": "countries" } ], "reach": 4974088, "reach_by_country": [ { "ages": [ { "age_range": "18-24", "female": 175420, "male": 326568, "unknown": 9562 }, { "age_range": "Unknown", "female": 161, "male": 238, "unknown": 146 }, { "age_range": "65+", "female": 263221, "male": 309061, "unknown": 4425 } ], "country_code": "DE" } ], "region": "eu" } ] } }, "publisher_platforms": [ "facebook", "instagram" ], "reach": null, "spend": null, "type": "dynamic", "unknown_fields": [ "languages" ], "url": "https://www.facebook.com/ads/library/?id=1103375555695370" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 756, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "ad", "id": "1103375555695370", "url": "https://www.facebook.com/ads/library/?id=1103375555695370" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookAdResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Creatives, run dates, placements and EU reach", "tags": [ "Facebook Ad Library" ], "x-socialtap-endpoint": "facebook.ad", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/ad_transcript": { "get": { "description": "Returns the timed transcript of a video ad from Meta's public Ad Library, by its link or Library ID, transcribed from the ad's audio. You get the full text, segments with their start and end times, the spoken language and the video's length. It works on single-video ads and on dynamic ads whose variations are videos, running or not.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 2 credits + 2 per started minute of media per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/ad_transcript/ (Markdown: https://socialtap.dev/docs/reference/facebook/ad_transcript/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/ad_transcript/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/ad_transcript/" }, "operationId": "facebook.ad_transcript.get", "parameters": [ { "description": "The video ad's Meta Ad Library link (facebook.com/ads/library/?id=…), the official Ad Library API's ad_snapshot_url (facebook.com/ads/archive/render_ad/?id=…), or its Library ID.", "example": "https://www.facebook.com/ads/library/?id=1448538159982118", "in": "query", "name": "url", "required": true, "schema": { "description": "The video ad's Meta Ad Library link (facebook.com/ads/library/?id=…), the official Ad Library API's ad_snapshot_url (facebook.com/ads/archive/render_ad/?id=…), or its Library ID.", "examples": [ "https://www.facebook.com/ads/library/?id=1448538159982118" ], "maxLength": 2048, "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language spoken in the video, a hint to speech-to-text. Without lang the language is detected.", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). The language spoken in the video, a hint to speech-to-text. Without lang the language is detected.", "examples": [ "en" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "available_languages": [], "duration_ms": 45489, "id": "1448538159982118", "is_auto_generated": true, "language": "en", "platform": "facebook", "platform_specific": {}, "segments": [ { "end_ms": 1940, "start_ms": 0, "text": "Open your clothes, open your clothes." }, { "end_ms": 3900, "start_ms": 2340, "text": "I know her name is Katie, hey Katie." }, { "end_ms": 5180, "start_ms": 4200, "text": "No more green beer." } ], "source": "asr", "text": "Open your clothes, open your clothes. I know her name is Katie, hey Katie. No more green beer. You do an Irish jig. Who in here knows who St. Patrick was? Green tea shot? No, it's St. Patty's Day or having Bailey's. It's just called a mini G shot. It's Bailey's Irish cream and co…", "url": "https://www.facebook.com/ads/library/?id=1448538159982118" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "asr", "is_cached": false, "credits_charged": 4, "latency_ms": 6131, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "ad", "id": "1448538159982118", "url": "https://www.facebook.com/ads/library/?id=1448538159982118" }, "credits_remaining": 9996, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookAd_transcriptResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "no_transcript": { "$ref": "#/components/examples/no_transcript" }, "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.\n\n`no_transcript`: The video or audio exists but has no transcript: no caption track and no speech to transcribe. Do not retry. If the platform offers other languages, try one with lang.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Timed transcript of what a video ad says", "tags": [ "Facebook Ad Library" ], "x-socialtap-endpoint": "facebook.ad_transcript", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 122, "min_credits": 2, "prices": [ { "credits": 2, "label": "2 credits + 2 per started minute of media", "max": 122, "per": 2, "source": "asr", "unit": "media_minute", "unit_max": 60 } ], "unit": "request" }, "x-socialtap-resource": "transcript", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/ads": { "get": { "description": "Returns the ads a Facebook Page ran on Facebook, Instagram, Messenger, Threads and the Audience Network, from its link, name or Page ID. Each ad from Meta's public Ad Library has the days it first and last ran, whether it's still active, where it ran and its creatives: headline, text, link, call to action, images and videos. Political and social-issue ads add the payer and Meta's impression, reach and spend ranges. Filter by country, language, status, kind of creative and dates, and sort by most impressions or newest.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Ad` items (the shared schema, the same on every platform), most impressions first with sort=popular (the default), most recently started first, in Meta's recency groups with sort=newest. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/ads/ (Markdown: https://socialtap.dev/docs/reference/facebook/ads/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/ads/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/ads/" }, "operationId": "facebook.ads.list", "parameters": [ { "description": "The advertiser: its Ad Library link (facebook.com/ads/library/?view_all_page_id=…), its Facebook Page's link or name, or its Page ID.", "example": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&view_all_page_id=20531316728&search_type=page&media_type=all", "in": "query", "name": "handle", "required": true, "schema": { "description": "The advertiser: its Ad Library link (facebook.com/ads/library/?view_all_page_id=…), its Facebook Page's link or name, or its Page ID.", "examples": [ "https://www.facebook.com/ads/library/?view_all_page_id=20531316728&search_type=page" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.", "examples": [ "en" ], "type": "string" } }, { "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.", "example": "active", "in": "query", "name": "status", "schema": { "default": "all", "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.", "enum": [ "active", "inactive", "all" ], "examples": [ "active" ], "type": "string" } }, { "description": "Only ads of this kind, as the Ad Library files them: image, video, meme (an image with text in it), image_and_meme (both) or text (no image or video). All kinds when omitted.", "example": "", "in": "query", "name": "format", "schema": { "description": "Only ads of this kind, as the Ad Library files them: image, video, meme (an image with text in it), image_and_meme (both) or text (no image or video). All kinds when omitted.", "enum": [ "image", "video", "meme", "image_and_meme", "text" ], "type": "string" } }, { "description": "Order of the results. popular (default): most impressions first, the Ad Library's own order. newest: the most recently started first, in Meta's recency groups, so not strictly by date.", "example": "", "in": "query", "name": "sort", "schema": { "default": "popular", "description": "Order of the results. popular (default): most impressions first, the Ad Library's own order. newest: the most recently started first, in Meta's recency groups, so not strictly by date.", "enum": [ "popular", "newest" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/444190414_420658830784969_8688257439109167735_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…", "display_name": "Facebook", "id": "20531316728", "is_verified": null, "url": "https://www.facebook.com/facebook", "username": "facebook" }, "approximate_fields": [ "first_shown_at", "impressions", "last_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "Shop local businesses on Facebook Marketplace. Open now.", "cta_text": "Use app", "link_description": "Explore the things you love", "link_url": "http://play.google.com/store/apps/details?id=com.facebook.katana", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/441926459_1556801448238181_8589306082817029192_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/445002890_438029678859371_1806086145592848961_n.jpg?_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Shop Local on Marketplace" } ], "first_shown_at": "2024-05-30T07:00:00Z", "id": "1440659790146974", "impressions": { "lower_bound": 1000000, "upper_bound": null }, "is_active": false, "is_political": true, "languages": [], "last_shown_at": "2024-10-18T07:00:00Z", "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Internet company" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 154921706, "beneficiary": null, "collation_count": 2, "collation_id": "758420173028777", "cta_type": "use_mobile_app", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "play.google.com", "partner": null, "removal_reasons": [], "special_ad_categories": [ "political" ], "targeting": [] } }, "publisher_platforms": [ "instagram", "audience_network" ], "reach": { "lower_bound": 1000000, "upper_bound": null }, "spend": { "currency": "USD", "lower_bound": 250000, "upper_bound": 299999 }, "type": "image", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=1440659790146974" }, { "advertiser": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/763761977_897297039659054_2373641633074239910_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…", "display_name": "Facebook", "id": "20531316728", "is_verified": null, "url": "https://www.facebook.com/facebook", "username": "facebook" }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "Download Facebook and feed your passion for the outdoors with Groups.", "cta_text": "Download", "link_description": null, "link_url": "http://play.google.com/store/apps/details?id=com.facebook.katana", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/767674769_2302540540500697_7951998685481294277_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/763980980_1026739123538638_5673970590546619705_n.jpg?_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Seek Adventures With Groups" }, { "body": "Download Facebook and feed your passion for the outdoors with Groups.", "cta_text": "Download", "link_description": null, "link_url": "http://play.google.com/store/apps/details?id=com.facebook.katana", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/763895288_1853472159357870_8536681551954643843_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/764719922_1405143578194986_6948991656684682887_n.jpg?_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Seek Adventures With Groups" }, { "body": "Download Facebook and feed your passion for the outdoors with Groups.", "cta_text": "Download", "link_description": null, "link_url": "http://play.google.com/store/apps/details?id=com.facebook.katana", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/767674769_2302540540500697_7951998685481294277_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/763980980_1026739123538638_5673970590546619705_n.jpg?_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Seek Adventures With Groups" } ], "first_shown_at": "2026-10-06T07:00:00Z", "id": "2253947551834151", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Internet company" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 154921706, "beneficiary": null, "collation_count": 5, "collation_id": "1065080066014280", "cta_type": "download", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "play.google.com", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [] } }, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "dynamic", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=2253947551834151" }, { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/838939240_1390159663100311_7275738155822511390_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "Facebook", "id": "20531316728", "is_verified": null, "url": "https://www.facebook.com/facebook", "username": "facebook" }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "Discover new places with new people in Groups. Download Facebook.", "cta_text": "Download", "link_description": null, "link_url": "http://play.google.com/store/apps/details?id=com.facebook.katana", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/837303193_2201269420433134_1772812502839754095_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/838612085_1104000178892017_4856035252372138746_n.jpg?_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "See What's Out There in Groups" } ], "first_shown_at": "2026-10-06T07:00:00Z", "id": "1045014251929614", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Internet company" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 154921706, "beneficiary": null, "collation_count": null, "collation_id": null, "cta_type": "download", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "play.google.com", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [] } }, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=1045014251929614" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1708, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "20531316728", "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&media_type=all&search_type=page&view_all_page_id=20531316728" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookAdsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Active and past ads of one Page, with creatives", "tags": [ "Facebook Ad Library" ], "x-socialtap-endpoint": "facebook.ads", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "most impressions first", "orders": { "newest": "most recently started first, in Meta's recency groups", "popular": "most impressions first" }, "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/comments": { "get": { "description": "Returns the top-level comments on a public Facebook post, photo, video or reel, most relevant or newest first, a page at a time. Each comment has its text, time, permalink, exact reaction count with the reactions by type, reply count, attached photo and whether the post's author wrote it, and the commenter's ID, name, profile link, picture and verified badge. It takes every link the Facebook Post API does.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Comment` items (the shared schema, the same on every platform), Facebook's All comments view: every top-level comment, the most relevant first with sort=relevance (the default), newest first with sort=newest. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/comments/ (Markdown: https://socialtap.dev/docs/reference/facebook/comments/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/comments/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/comments/" }, "operationId": "facebook.comments.list", "parameters": [ { "description": "Facebook post, photo, video or reel URL, as the Facebook Post API takes it: //posts/, permalink.php and story.php links, /photo/?fbid= and //photos/… links, reel, watch, video.php and //videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID. A comment's link (?comment_id=) reads its post's comments.", "example": "https://www.facebook.com/cnn/posts/pfbid0zVcLXuYcv5N8D5oZn9NMU3R116cECPXJiKY6QyxiZGTA7eRDZb3zv3NkVwgC1GVdl", "in": "query", "name": "url", "required": true, "schema": { "description": "Facebook post, photo, video or reel URL, as the Facebook Post API takes it: //posts/, permalink.php and story.php links, /photo/?fbid= and //photos/… links, reel, watch, video.php and //videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID. A comment's link (?comment_id=) reads its post's comments.", "examples": [ "https://www.facebook.com/cnn/posts/pfbid0zVcLXuYcv5N8D5oZn9NMU3R116cECPXJiKY6QyxiZGTA7eRDZb3zv3NkVwgC1GVdl" ], "maxLength": 2048, "type": "string" } }, { "description": "Order of the results. relevance (default): Facebook's All comments view, the most relevant first, including the comments its default view filters out. newest: every comment, newest first.", "example": "relevance", "in": "query", "name": "sort", "schema": { "default": "relevance", "description": "Order of the results. relevance (default): Facebook's All comments view, the most relevant first, including the comments its default view filters out. newest: every comment, newest first.", "enum": [ "relevance", "newest" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/837402617_10240488748735344_2095546189445517301_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx720x720&ctp=s32x32&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "display_name": "George Sampson", "id": "pfbid0CYtKGzDDtxXk1PETorcSCFdSM2jxJF3XayHaezE6o8XMEa1APnAcVa4cHPnmyn4al", "is_verified": false, "url": null, "username": null }, "edited_at": null, "id": "1134072982431001", "is_by_post_author": null, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 39, "reply_count": 12 }, "parent_id": null, "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "male", "image_url": null, "reactions": [ { "count": 27, "type": "like" }, { "count": 11, "type": "haha" }, { "count": 1, "type": "love" } ] } }, "post_id": "1515533333772646", "published_at": "2026-10-29T19:37:25Z", "text": "Fox’s ratings are down substantially while MSNow and CNN are up.", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=1134072982431001" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t1.6435-1/38985115_2135903490004970_3576751264056213504_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx946x947&ctp=s32x32&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_s…", "display_name": "Michael Shelton", "id": "pfbid0HyC8RVyhaoZG7evfeukYuTnh5Q87tU6ACBtTFbpvvGmXLVLAN2au52Vdk3DnKndBl", "is_verified": false, "url": "https://www.facebook.com/michael.shelton.528", "username": "michael.shelton.528" }, "edited_at": null, "id": "2366768057490102", "is_by_post_author": null, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 20, "reply_count": 2 }, "parent_id": null, "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "male", "image_url": null, "reactions": [ { "count": 20, "type": "like" } ] } }, "post_id": "1515533333772646", "published_at": "2026-10-29T19:53:16Z", "text": "An equally interesting question is what will CNN look like.", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=2366768057490102" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/511906991_24085412141097078_6841766951798215929_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx648x648&ctp=s32x32&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "display_name": "Steve Jenkins", "id": "pfbid02tWsPGdCcwsR9MDGBfyqw45aVVh34i1ZxbmHZ41TniRyXx4VMoQAmgt2ikBy1fTLql", "is_verified": false, "url": "https://www.facebook.com/people/Steve-Jenkins/pfbid02tWsPGdCcwsR9MDGBfyqw45aVVh34i1ZxbmHZ41TniRyXx4VMoQAmgt2ikBy1fTLql/", "username": null }, "edited_at": null, "id": "2241840356745830", "is_by_post_author": null, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 4, "reply_count": 5 }, "parent_id": null, "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "male", "image_url": null, "reactions": [ { "count": 4, "type": "like" } ] } }, "post_id": "1515533333772646", "published_at": "2026-10-29T22:21:23Z", "text": "I have noticed that Fox is reporting more truthfully meaning showing Trump's negative numbers, etc.", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=2241840356745830" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 825, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "1515533333772646", "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookCommentsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Top-level, with exact reactions and reply counts", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.comments", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Facebook's All comments view: every top-level comment, the most relevant first", "orders": { "newest": "newest first", "relevance": "Facebook's All comments view: every top-level comment, the most relevant first" }, "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "comment", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/engagement": { "get": { "description": "Returns a public Facebook Page's or person's engagement rate and post stats, computed over its latest posts in one request. You get engagement rate per follower and per view (mean, median and spread), likes, comments and shares per post, views per video, comment-to-like ratio, posting cadence, the mix of photos, videos and reels, and the top and bottom post. The profile and each post come with it, with exact counts and each post's rate against the account's typical post. Send a name, ID or link.\n\nReturns `{data, meta}`: `data` is a `Engagement` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/engagement/ (Markdown: https://socialtap.dev/docs/reference/facebook/engagement/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/engagement/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/engagement/" }, "operationId": "facebook.engagement.get", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID or Page ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-, /pages/category/…, fb.me/.", "example": "NASA", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID or Page ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-, /pages/category/…, fb.me/.", "examples": [ "NASA" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "bottom_post_id": "1676179567210746", "id": "100044561550831", "metrics": { "comment_to_like_ratio": 0.017837, "comments_per_post": 54, "counted_post_count": 3, "engagement_rate": 0.000107, "engagement_rate_stddev": 0.00014, "formats": [ { "counted_post_count": 2, "engagement_rate": 0.000158, "interactions_per_post": 4527.5, "type": "image", "views_per_post": null }, { "counted_post_count": 1, "engagement_rate": 0.000007, "interactions_per_post": 189, "type": "text", "views_per_post": null } ], "interactions_per_post": 3081.33, "likes_per_post": 3027.33, "median_engagement_rate": 0.00001, "median_views_per_post": null, "posts_per_week": 16.03, "quotes_per_post": null, "rated_post_count": 3, "reposts_per_post": null, "sampled_post_count": 3, "saves_per_post": null, "shares_per_post": 214.33, "view_engagement_rate": null, "views_per_post": null }, "newest_post_at": "2026-11-03T19:27:52Z", "oldest_post_at": "2026-11-02T22:30:00Z", "platform": "facebook", "platform_specific": {}, "posts": [ { "engagement_rate": 0.000007, "engagement_vs_median": 0.66, "is_counted": true, "post": { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1676179567210746", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [], "mentions": [], "metrics": { "comment_count": 10, "like_count": 179, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 6, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMmlSQkFpeENQd1R1Zml6aUFWTXZRdWEzTEJuZHk2dGYzUHl2NDE1UWtaZjdGdjdneTM1U2VpRVltN3Z0UGNMcGps", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 155, "type": "like" }, { "count": 22, "type": "love" }, { "count": 1, "type": "care" } ], "shared_post": { "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/516872204_1189959146491994_4245240435554141606_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx2048x2047&ctp=s80x80&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "display_name": "Learn With NASA", "id": "100064337605401", "is_verified": true, "url": "https://www.facebook.com/LearnWithNASA", "username": "LearnWithNASA" }, "id": "1615866537234584", "url": "https://www.facebook.com/LearnWithNASA/posts/pfbid0qRf3ZGacva8hj6xVFVrBA29EF3mMnZGmcG6zYUaeLRB1yHARL2KHoPFaqH5jM72yl" }, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T19:27:52Z", "text": null, "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid02iRBAixCPwTufiziAVMvQua3LBndy6tf3Pyv415QkZf7Fv7gy35SeiEYm7vtPcLpjl" }, "view_engagement_rate": null, "views_vs_median": null }, { "engagement_rate": 0.000305, "engagement_vs_median": 30.55, "is_counted": true, "post": { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675983783896991", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An intricate cloud of white dust takes center stage in this photo, rising in a windy pillar. The background features rust-colored dust with dots of distant stars and galaxies shining through.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1385, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=dst-jpg_tt6&cstp=mx2000x1385&ctp=s2000x1385&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "width": 2000 } ], "mentions": [ "NASAWebb" ], "metrics": { "comment_count": 134, "like_count": 8634, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 606, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwZDJ3bUtXZm9Lc1Q5d0s5bndvV1c1SHpzRWd2MjhjSno5UTZuUDVBMjZCTGNrdVFlQWJCWnNQM0RuSm1pU2s3Q2w=", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 4819, "type": "like" }, { "count": 3553, "type": "love" }, { "count": 148, "type": "care" } ], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T15:00:35Z", "text": "Pspsps 🐈‍⬛\n\nThis smoky specter is the Cat’s Head Nebula, captured in intricate detail by NASA's James Webb Space Telescope. Its name comes from its shape, which resembles a cosmic kitty sitting with its back toward the viewer. What do you see?", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=dst-jpg_tt6&cstp=mx2000x1385&ctp=s2000x1385&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid0d2wmKWfoKsT9wK9nwoWW5HzsEgv28cJz9Q6nP5A26BLckuQeAbBZsP3DnJmiSk7Cl" }, "view_engagement_rate": null, "views_vs_median": null }, { "engagement_rate": 0.00001, "engagement_vs_median": 1, "is_counted": true, "post": { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675279183967451", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An image that shows the \"MAX POWER Kennedy Space Center\" app as it appears in the iOS App Store.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1294, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=dst-jpg_tt6&cstp=mx2048x1294&ctp=s2048x1294&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "width": 2048 } ], "mentions": [], "metrics": { "comment_count": 18, "like_count": 269, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 31, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMnBqYUxiZmhBbkZtckRvb254eDdHeWVwVDFIN3BGYmk5d3JwcXF1TDZvTTVnVFVKYmZCRTJCVDJYY2h0RzkzcjJs", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 231, "type": "like" }, { "count": 30, "type": "love" }, { "count": 5, "type": "care" } ], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-02T22:30:00Z", "text": "Planning your trip to MAX POWER? We've got a tool for that.\n\nEvent schedules, maps, and FAQs are at your fingertips with the MAX POWER app. It's free and available to download from official app stores on iOS and Android devices: https://go.nasa.gov/3V2iiWX", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=dst-jpg_tt6&cstp=mx2048x1294&ctp=s2048x1294&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid02pjaLbfhAnFmrDoonxx7GyepT1H7pFbi9wrpqquL6oM5gTUJbfBE2BT2XchtG93r2l" }, "view_engagement_rate": null, "views_vs_median": null } ], "profile": { "approximate_fields": [], "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png&cstp=mx800x800&ctp=s800x800&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b…", "banner_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/809146614_4484013928506139_3181913787670602881_n.png?stp=dst-jpg_tt6&cstp=mx2047x1487&ctp=s2047x1487&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "bio": "Explore the universe and discover our home planet. \nThere's space for everybody. ✨", "category": "Government organization", "country_code": null, "created_at": "2009-03-04T21:45:25Z", "display_name": "NASA - National Aeronautics and Space Administration", "external_links": [ { "title": "nasa.gov/nasa-app", "url": "https://www.nasa.gov/nasa-app/" }, { "title": "nasa.gov", "url": "https://www.nasa.gov/" } ], "id": "100044561550831", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": 28732202, "following_count": 52, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "ad_library_entity_type": null, "admin_countries": [ { "count": 15, "country": "United States" } ], "alternate_name": null, "business_hours": [], "education": [], "email": "public-inquiries@hq.nasa.gov", "gender": null, "hometown": null, "hours_status": null, "instagram_follower_count": null, "instagram_username": null, "is_deleted": null, "is_instagram_verified": null, "is_memorialized": false, "is_political_advertiser": false, "is_running_ads": false, "name_changes": [ { "changed_at": "2014-04-07T19:49:21Z", "name": "NASA - National Aeronautics and Space Administration" } ], "owner_location": "WASHINGTON DC, 20024 United States of America", "owner_name": "NATIONAL AERONAUTICS AND SPACE ADMINISTRATION", "page_id": "54971236771", "phone": null, "price_range": null, "rating": null, "recommend_percent": null, "relationship": null, "review_count": null, "services": [], "talking_about_count": null, "were_here_count": null, "work": [] } }, "type": "organization", "unknown_fields": [], "url": "https://www.facebook.com/NASA", "username": "NASA" }, "top_post_id": "1675983783896991", "unknown_fields": [], "url": "https://www.facebook.com/NASA" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 2283, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100044561550831", "url": "https://www.facebook.com/NASA" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookEngagementResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Engagement rate, cadence and top posts", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.engagement", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "request" }, "x-socialtap-resource": "engagement", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/event": { "get": { "description": "Returns a public Facebook event from its link or ID: name, description, start and end, venue, hosts, and exact going and interested counts. It also has whether it's scheduled, under way, over or canceled, its offset from UTC, whether it's online, the venue's address, city and coordinates, the cover, categories, ticket link, seller and price label, the group it was created in, and for a date of a recurring event its series and how many dates that has.\n\nReturns `{data, meta}`: `data` is a `Event` object (the shared schema, the same on every platform). Null means unknown.\n\nIn Facebook's words: `metrics.attendee_count` is going.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/event/ (Markdown: https://socialtap.dev/docs/reference/facebook/event/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/event/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/event/" }, "operationId": "facebook.event.get", "parameters": [ { "description": "The event's Facebook link (facebook.com/events//, with its slugged form /events////, a date of a series /events/// or ?event_time_id=, or the legacy event.php?eid=; m. and web. hosts too) or its numeric ID.", "example": "https://www.facebook.com/events/jannus-live/arch-enemy-the-black-dahlia-murder-wrath-across-north-america-2026/2513378022457980/", "in": "query", "name": "url", "required": true, "schema": { "description": "The event's Facebook link (facebook.com/events//, with its slugged form /events////, a date of a series /events/// or ?event_time_id=, or the legacy event.php?eid=; m. and web. hosts too) or its numeric ID.", "examples": [ "https://www.facebook.com/events/2513378022457980/" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "categories": [ "Music & audio" ], "community_id": null, "cover_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-6/701643646_1454949970006889_5222368129042891587_n.avif?stp=dst-jpg_tt6&cstp=mx2048x1152&ctp=s2048x1152&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED…", "description": "Arch Enemy & The Black Dahlia Murder will be performing at Jannus Live on Sunday, October 18th. This event is All Ages. Doors open at 5:00 PM, Show starts at 6:00 PM. All support acts are subject to change without notice. This event is rain or shine.\n\nSale Dates and Times:\n\nPubli…", "end_at": null, "hosts": [ { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/703461784_1493244248837311_492679311377568321_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1080x1080&ctp=s74x74&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_…", "display_name": "Thrown Into Exile", "id": "100044552494354", "is_verified": true, "url": "https://www.facebook.com/ThrownIntoExile", "username": "ThrownIntoExile" }, { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/481358765_1074963661337894_2872436054536647170_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1024x1024&ctp=s74x74&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "display_name": "No Clubs", "id": "100064728099080", "is_verified": false, "url": "https://www.facebook.com/Noclubsproductions", "username": "Noclubsproductions" }, { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/302197946_452479626918288_252645739401521140_n.png?stp=cp0_dst-png&cstp=mx200x200&ctp=s74x74&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7…", "display_name": "Jannus Live", "id": "100064687631616", "is_verified": false, "url": "https://www.facebook.com/jannuslive", "username": "jannuslive" } ], "id": "2513378022457980", "is_online": false, "metrics": { "attendee_count": 52 }, "name": "Arch Enemy & The Black Dahlia Murder: Wrath Across North America 2026", "parent_id": null, "place": { "address": "201 Central Ave, St Petersburg, FL 33701-3325, United States", "city": "Saint Petersburg, Florida", "country_code": null, "id": null, "latitude": 27.771757351792, "longitude": -82.636019393897, "name": "Jannus Live", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": "111326725552547", "date_text": "Sunday, October 18, 2026 at 5:00 PM EDT", "frequency": "single", "metrics": { "interested_count": 355, "response_count": 407 }, "occurrence_count": 0, "price_text": null, "ticket_provider": null } }, "start_at": "2026-10-18T21:00:00Z", "status": "ended", "ticket_url": null, "time_zone": null, "unknown_fields": [], "url": "https://www.facebook.com/events/2513378022457980/", "utc_offset_minutes": -240 }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 866, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "event", "id": "2513378022457980", "url": "https://www.facebook.com/events/2513378022457980/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookEventResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Date, venue, hosts and exact RSVP counts", "tags": [ "Facebook Events" ], "x-socialtap-endpoint": "facebook.event", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "request" }, "x-socialtap-resource": "event", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/events": { "get": { "description": "Returns the public events on a Facebook Page's or person's Events tab, upcoming or past, from a vanity name, profile ID or profile link. Each event has its name, whether it's scheduled, under way, over or canceled, its start time with its offset from UTC, whether it's online, its venue and city, its cover and who hosts it. Narrow them by date with since and until.\n\nReturns `{data, page, meta}`: `data` holds up to 8 `Event` items (the shared schema, the same on every platform), oldest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\nIn Facebook's words: `metrics.attendee_count` is going.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/events/ (Markdown: https://socialtap.dev/docs/reference/facebook/events/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/events/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/events/" }, "operationId": "facebook.events.list", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (jannuslive, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "example": "jannuslive", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (jannuslive, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "examples": [ "jannuslive" ], "maxLength": 2048, "type": "string" } }, { "description": "Which events: upcoming, soonest first (events under way included); past, latest first, as the profile's Events tab shows them.", "example": "", "in": "query", "name": "time", "schema": { "default": "upcoming", "description": "Which events: upcoming, soonest first (events under way included); past, latest first, as the profile's Events tab shows them.", "enum": [ "upcoming", "past" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only events starting at or after this time.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only events starting at or after this time.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only events starting before this time.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only events starting before this time.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 8, "in": "query", "name": "limit", "schema": { "default": 8, "maximum": 8, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent-hou1-1.xx.fbcdn.net/v/t39.30808-6/689010503_1426152826217625_6518170320015938469_n.jpg?stp=c145.0.910.628a_dst-jpg_tt6&cstp=mx910x628&ctp=s235x165&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-hou1-1.xx&_nc_g…", "description": null, "end_at": null, "hosts": [ { "avatar_url": null, "display_name": "Jannus Live", "id": "100064687631616", "is_verified": false, "url": "https://www.facebook.com/jannuslive", "username": "jannuslive" } ], "id": "1195651112570986", "is_online": false, "metrics": { "attendee_count": null }, "name": "MOVEMENTS - HAPPIER NOW USA TOUR", "parent_id": null, "place": { "address": null, "city": "St Petersburg", "country_code": null, "id": null, "latitude": null, "longitude": null, "name": "200 1st Ave N, Saint Petersburg, FL, United States, Florida 33701", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Wed, Nov 4 at 6:00 PM EST", "frequency": null, "metrics": { "interested_count": null, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-04T23:00:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "categories" ], "url": "https://www.facebook.com/events/1195651112570986/", "utc_offset_minutes": -300 }, { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent-hou1-1.xx.fbcdn.net/v/t39.99422-6/752022562_3213771052163800_3772178195491863544_n.png?stp=c189.0.1670.1152a_dst-jpg_tt6&cstp=mx1670x1152&ctp=s235x165&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-hou1-1.xx&_…", "description": null, "end_at": null, "hosts": [ { "avatar_url": null, "display_name": "Jannus Live", "id": "100064687631616", "is_verified": false, "url": "https://www.facebook.com/jannuslive", "username": "jannuslive" } ], "id": "1007777452102015", "is_online": false, "metrics": { "attendee_count": null }, "name": "TRIVIUM: CROWN IN THE GRAVE WORLD TOUR", "parent_id": null, "place": { "address": null, "city": "St Petersburg", "country_code": null, "id": "345248550607", "latitude": null, "longitude": null, "name": "Jannus Live", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Thu, Nov 5 at 5:30 PM EST", "frequency": null, "metrics": { "interested_count": null, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-05T22:30:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "categories" ], "url": "https://www.facebook.com/events/1007777452102015/", "utc_offset_minutes": -300 }, { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent-hou1-1.xx.fbcdn.net/v/t39.30808-6/725547215_1482760040559215_5316960699790543595_n.avif?stp=c34.0.1980.1365a_dst-jpg_tt6&cstp=mx1980x1365&ctp=s235x165&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-hou1-1.xx&_…", "description": null, "end_at": null, "hosts": [ { "avatar_url": null, "display_name": "Jannus Live", "id": "100064687631616", "is_verified": false, "url": "https://www.facebook.com/jannuslive", "username": "jannuslive" } ], "id": "1319224153724613", "is_online": false, "metrics": { "attendee_count": null }, "name": "Greensky Bluegrass", "parent_id": null, "place": { "address": null, "city": "St Petersburg", "country_code": null, "id": "345248550607", "latitude": null, "longitude": null, "name": "Jannus Live", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Fri, Nov 6 at 6:30 PM EST", "frequency": null, "metrics": { "interested_count": null, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-06T23:30:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "categories" ], "url": "https://www.facebook.com/events/1319224153724613/", "utc_offset_minutes": -300 } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 841, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100064687631616", "url": "https://www.facebook.com/jannuslive" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookEventsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Upcoming and past events a Page or person hosts", "tags": [ "Facebook Events" ], "x-socialtap-endpoint": "facebook.events", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "oldest first", "page_max": 8, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "event", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/group": { "get": { "description": "Returns a Facebook group's about page from its link or ID: exact member count, description, privacy, rules, posting activity and who runs it. It also has the name and vanity name, cover photo and picture, whether the group shows in search, its topics and location, when it was created and its name changes, each admin's and moderator's name, picture and profile link, and the Page it belongs to. Private groups answer too, with what their page shows logged out.\n\nReturns `{data, meta}`: `data` is a `Community` object (Facebook calls it a group) (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/group/ (Markdown: https://socialtap.dev/docs/reference/facebook/group/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/group/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/group/" }, "operationId": "facebook.group.get", "parameters": [ { "description": "The group: its link (facebook.com/groups/, any tab of it, on any facebook.com host; the legacy group.php?gid=), its share link (facebook.com/share/g/) or its bare numeric ID.", "example": "https://www.facebook.com/groups/366190054572553/", "in": "query", "name": "url", "required": true, "schema": { "description": "The group: its link (facebook.com/groups/, any tab of it, on any facebook.com host; the legacy group.php?gid=), its share link (facebook.com/share/g/) or its bare numeric ID.", "examples": [ "https://www.facebook.com/groups/366190054572553/" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t1.6435-9/121615771_3201454343306997_2348901429098757975_n.jpg?stp=c120.0.400.400a_cp0_dst-jpg_tt6&cstp=mx400x400&ctp=s110x80&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_…", "banner_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t1.6435-9/121615771_3201454343306997_2348901429098757975_n.jpg?stp=dst-jpg_tt6&cstp=mx640x400&ctp=s640x400&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss…", "categories": [ "Software & tech", "Engineering" ], "created_at": "2020-10-14T11:05:03Z", "description": "Let's share our knowledge on Python Programming", "id": "366190054572553", "is_nsfw": null, "metrics": { "member_count": 763182 }, "moderators": [ { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/297738489_149183324449711_6655284279259187616_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx720x730&ctp=p64x64&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc…", "display_name": "Nusrat Jahan", "id": "pfbid06GnASXZiYzDf35bsZJ3QLiKd5swrdR2gbc9txBtTEAZvJz1oW5bg7n1zMF1wzFJul", "is_verified": null, "url": "https://www.facebook.com/people/Nusrat-Jahan/pfbid06GnASXZiYzDf35bsZJ3QLiKd5swrdR2gbc9txBtTEAZvJz1oW5bg7n1zMF1wzFJul/", "username": null }, { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/242977119_109642788145497_5023972278328162431_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1200x1200&ctp=s64x64&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "display_name": "Thesoftwarelion", "id": "100079525026696", "is_verified": null, "url": "https://www.facebook.com/profile.php?id=100079525026696", "username": null }, { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/795255518_27959759933716428_4332290339331851799_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1568x1556&ctp=s64x64&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED…", "display_name": "Jamil Ahmed", "id": "pfbid02tVzjeEoXMnLspija9MeZZfBPwsH4T5796pNLJhq8jhk2QZ8EThUdgbsDi7uPqFMXl", "is_verified": null, "url": "https://www.facebook.com/people/Jamil-Ahmed/pfbid02tVzjeEoXMnLspija9MeZZfBPwsH4T5796pNLJhq8jhk2QZ8EThUdgbsDi7uPqFMXl/", "username": null } ], "name": null, "platform": "facebook", "platform_specific": { "facebook": { "admin_count": 3, "admin_ids": [ "pfbid06GnASXZiYzDf35bsZJ3QLiKd5swrdR2gbc9txBtTEAZvJz1oW5bg7n1zMF1wzFJul", "100079525026696", "pfbid02tVzjeEoXMnLspija9MeZZfBPwsH4T5796pNLJhq8jhk2QZ8EThUdgbsDi7uPqFMXl" ], "daily_post_count": 21, "history_summary": "Group created on October 14, 2020. Name last changed on October 16, 2020.", "is_visible": true, "locations": [], "moderator_count": 0, "monthly_post_count": 1641, "owner": null, "weekly_new_member_count": null } }, "privacy": "public", "rules": [ { "description": "We're all in this together to create a welcoming environment. Let's treat everyone with respect. Healthy debates are natural, but kindness is required.", "title": "Be Kind and Courteous" }, { "description": "Make sure everyone feels safe. Bullying of any kind isn't allowed, and degrading comments about things like race, religion, culture, sexual orientation, gender or identity will not be tolerated.", "title": "No Hate Speech or Bullying" }, { "description": "Give more than you take to this group. Self-promotion, spam and irrelevant links aren't allowed.", "title": "No Promotions or Spam" } ], "title": "Python Programming", "unknown_fields": [], "url": "https://www.facebook.com/groups/366190054572553/" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 1564, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "community", "id": "366190054572553", "url": "https://www.facebook.com/groups/366190054572553/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookGroupResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Member count, rules, admins and activity", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.group", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "request" }, "x-socialtap-resource": "community", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/group_posts": { "get": { "description": "Returns a public Facebook group's posts, a page at a time: newest first, most relevant, most recently active, or only its items for sale. Each post has its text with hashtags and mentions, photos, album, video or reel, link card or shared post, publish time, exact reaction, comment and share counts with the reactions by type, a video's views, and the member who posted it. Send the group's link, share link or ID.\n\nReturns `{data, page, meta}`: `data` holds up to 3 `Post` items (the shared schema, the same on every platform), Facebook's New posts: newest first by when a post entered the group's feed with sort=newest (the default), the group's items for sale, newest first by when each entered the group's feed with sort=listings, the posts most recently commented on or reacted to first with sort=recent_activity, Facebook's Most relevant ranking of the group's posts with sort=relevance. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/group_posts/ (Markdown: https://socialtap.dev/docs/reference/facebook/group_posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/group_posts/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/group_posts/" }, "operationId": "facebook.group_posts.list", "parameters": [ { "description": "The public group: its link (facebook.com/groups/, any tab of it, on any facebook.com host; the legacy group.php?gid=), its share link (facebook.com/share/g/) or its bare numeric ID.", "example": "https://www.facebook.com/groups/366190054572553/", "in": "query", "name": "url", "required": true, "schema": { "description": "The public group: its link (facebook.com/groups/, any tab of it, on any facebook.com host; the legacy group.php?gid=), its share link (facebook.com/share/g/) or its bare numeric ID.", "examples": [ "https://www.facebook.com/groups/366190054572553/" ], "maxLength": 2048, "type": "string" } }, { "description": "Order of the results. newest (default): the group's newest posts first (Facebook's New posts). relevance: Facebook's Most relevant ranking, the default of the group's page. recent_activity: the posts most recently commented on or reacted to first, however old (Facebook's Recent activity). listings: the group's items for sale only, newest first.", "example": "newest", "in": "query", "name": "sort", "schema": { "default": "newest", "description": "Order of the results. newest (default): the group's newest posts first (Facebook's New posts). relevance: Facebook's Most relevant ranking, the default of the group's page. recent_activity: the posts most recently commented on or reacted to first, however old (Facebook's Recent activity). listings: the group's items for sale only, newest first.", "enum": [ "newest", "relevance", "recent_activity", "listings" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 3, "in": "query", "name": "limit", "schema": { "default": 3, "maximum": 3, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/657732699_4372938149635055_8298649324198958953_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1920x1933&ctp=s80x80&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "display_name": "Gift Glory Onuoha", "id": "100007567395235", "is_verified": false, "url": "https://www.facebook.com/gift.glory.onuoha.2025", "username": "gift.glory.onuoha.2025" }, "coauthors": [], "duration_ms": null, "hashtags": [ "Python", "PythonProgramming", "CodingChallenge" ], "id": "1837548820769995", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "May be a graphic of text", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1280, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/888453030_1934834490835840_4759651598659241080_n.png?stp=dst-jpg_tt6&cstp=mx1024x1280&ctp=s1024x1280&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "width": 1024 } ], "mentions": [], "metrics": { "comment_count": 0, "like_count": 1, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 1, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwSGZWelFmaURCb0xWU2J0Zjk0enlGeE5qN3VWaExUbTQ2ZHpSUjlnNTNTRjVCOG8ydWM2Z2dHTDU4ZTZmdEZMamw=", "group": { "id": "366190054572553", "name": "Python Programming", "url": "https://www.facebook.com/groups/366190054572553/" }, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 1, "type": "like" } ], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T17:47:58Z", "text": "DEVELOPER MYSTERIES #074 🕵️\n\nOne function changes a variable. Another function reads it.\n\nNeither function receives that variable as an argument.\n\nSo how do they stay connected?\n\nThis challenge tests your understanding of Python closures and variable scope.\n\nPredict the exact out…", "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/888453030_1934834490835840_4759651598659241080_n.png?stp=dst-jpg_tt6&cstp=mx1024x1280&ctp=s1024x1280&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/groups/366190054572553/posts/1837548820769995/" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/795255518_27959759933716428_4332290339331851799_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1568x1556&ctp=s80x80&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED…", "display_name": "Jamil Ahmed", "id": "pfbid02tVzjeEoXMnLspija9MeZZfBPwsH4T5796pNLJhq8jhk2QZ8EThUdgbsDi7uPqFMXl", "is_verified": false, "url": "https://www.facebook.com/people/Jamil-Ahmed/pfbid02tVzjeEoXMnLspija9MeZZfBPwsH4T5796pNLJhq8jhk2QZ8EThUdgbsDi7uPqFMXl/", "username": null }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1837472564110954", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "May be a doodle of crowd", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 616, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-6/886519251_28601992169493198_704461445392669909_n.jpg?stp=dst-jpg_tt6&cstp=mx2000x616&ctp=s2000x616&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_n…", "width": 2000 } ], "mentions": [ "nurul.islam.971932", "arwy.mhmd.552211", "talha.qaimkhani.33" ], "metrics": { "comment_count": 1, "like_count": 0, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 0, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwc3J5VXVYQ3pFaUFQYjVDZWRjbUF3TVlTQTZqQnlZVU1Rb1JIbksxTm9aYXlSUWRQRW0ydm5lTTE3OGVlZHB5Nmw=", "group": { "id": "366190054572553", "name": "Python Programming", "url": "https://www.facebook.com/groups/366190054572553/" }, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T16:12:44Z", "text": "Let's welcome our new members!\nEmanuela Salomè,\nAdamu Abdullahi Adamu,\nNurul Islam,\nOlika Abdukerim Hassen,\nاروى محمد,\nMdAlamin Islam,\nAmos Dweh,\nElloy Neves,\nMuhammad Talha,\nAL IF,\nMaesha Jannat,\nLijalem Abera,\nMoosin Abdoo,\nTa Minh Tam,\nMorsalin Fahim,\n燈矢 轟,\nZayn Hosen,\nTasirul…", "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-6/886519251_28601992169493198_704461445392669909_n.jpg?stp=dst-jpg_tt6&cstp=mx2000x616&ctp=s2000x616&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_n…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/groups/366190054572553/posts/1837472564110954/" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/723111037_2124011641501346_211675270863137924_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx728x735&ctp=p80x80&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc…", "display_name": "Sajid Hamid", "id": "100016775924657", "is_verified": false, "url": "https://www.facebook.com/sajid.hamid.762469", "username": "sajid.hamid.762469" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1837467537444790", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "May be an image of text", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1620, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/887924411_1161885399862305_7654919970390769521_n.png?stp=dst-jpg_tt6&cstp=mx1280x1920&ctp=s1080x2048&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "width": 1080 } ], "mentions": [], "metrics": { "comment_count": 0, "like_count": 0, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 0, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMnBrODFXZ1UzUlZCUmprZmg2S1F3bVFlUllTUFQ5OURXQVZQNlRuaTZNWnJqZzJYWUtKU1NMOXpiRVM2ZkhkNVJs", "group": { "id": "366190054572553", "name": "Python Programming", "url": "https://www.facebook.com/groups/366190054572553/" }, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T16:06:16Z", "text": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/887924411_1161885399862305_7654919970390769521_n.png?stp=dst-jpg_tt6&cstp=mx1280x1920&ctp=s1080x2048&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/groups/366190054572553/posts/1837467537444790/" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1959, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "community", "id": "366190054572553", "url": "https://www.facebook.com/groups/366190054572553/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookGroup_postsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Public group posts with exact counts", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.group_posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Facebook's New posts: newest first by when a post entered the group's feed", "orders": { "listings": "the group's items for sale, newest first by when each entered the group's feed", "newest": "Facebook's New posts: newest first by when a post entered the group's feed", "recent_activity": "the posts most recently commented on or reacted to first", "relevance": "Facebook's Most relevant ranking of the group's posts" }, "page_max": 3, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/listing": { "get": { "description": "Returns a public Facebook Marketplace listing from its link or ID: title, price, condition, description, photos and the seller with their rating. It also has the struck-through earlier price, currency, category, whether it's available, pending or sold, videos, the seller's join date, the area it's in with coordinates, and pickup, shipping or Buy now. Vehicles add make, model, trim, mileage, transmission and colors, and homes their details.\n\nReturns `{data, meta}`: `data` is a `Product` object (Facebook calls it a listing) (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/listing/ (Markdown: https://socialtap.dev/docs/reference/facebook/listing/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/listing/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/listing/" }, "operationId": "facebook.listing.get", "parameters": [ { "description": "Facebook Marketplace listing URL (/marketplace/item/, also under a city's or category's path, or the older /commerce/listing/; www., m. and web. hosts, any query string), or the listing's numeric ID.", "example": "https://www.facebook.com/marketplace/item/1456476040872340/", "in": "query", "name": "url", "required": true, "schema": { "description": "Facebook Marketplace listing URL (/marketplace/item/, also under a city's or category's path, or the older /commerce/listing/; www., m. and web. hosts, any query string), or the listing's numeric ID.", "examples": [ "https://www.facebook.com/marketplace/item/1456476040872340/" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "platform_specific.facebook.latitude", "platform_specific.facebook.longitude" ], "attributes": [ { "name": "Condition", "value": "Used - like new" }, { "name": "Material", "value": "Steel" }, { "name": "Bicycle Type", "value": "Cruiser Bike" } ], "availability": "in_stock", "category": "Bicycles", "category_id": "1658310421102081", "condition": "used", "condition_label": "Used - like new", "country_code": null, "currency": "USD", "description": "Barely used, 24\" steel Huffy Bike perfect for outdoor terrain and everyday rides \n\n-Fully functional brakestyle with progressive sizing and clean seat cover \n\n-If needed, I am willing to deliver the bike to your home or flexible for an at-home pick-up", "id": "1456476040872340", "max_price": 45, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 720, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.84726-6/796968328_2328210001329072_7831806606744114668_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "width": 960 }, { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 960, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t45.5328-4/800796705_2129037657962264_2251174291161391522_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…", "width": 720 } ], "original_price": null, "platform": "facebook", "platform_specific": { "facebook": { "delivery_types": [ "in_person", "door_pickup", "door_dropoff" ], "is_buy_now_enabled": false, "is_local_pickup": true, "latitude": 40.663146972656, "location": "Rockville Centre, NY", "location_id": null, "longitude": -73.635864257812, "postal_code": null, "price_period": null, "published_at": "2026-09-09T13:45:37Z", "seller_joined_at": "2026-09-09T13:20:08Z", "seller_rating": null, "seller_rating_count": null } }, "price": 45, "seller": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/795438461_122093964159482116_3880964857956452102_n.jpg?stp=c334.0.1380.1380a_cp6_dst-jpg_tt6&cstp=mx1380x1380&ctp=s100x100&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-…", "display_name": "Meredith Hall", "id": "pfbid0bhJ8iBQwR4XVDCyEgQU4hKBvHyZPUVgJuBYVSa4henf9QvFwHycKvjgyYX3imnYCl", "is_verified": false, "url": null, "username": null }, "shipping": { "fee": null, "is_offered": false }, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.84726-6/796968328_2328210001329072_7831806606744114668_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "title": "Barely Used, \"26 Turquoise Huffy Bike", "type": "listing", "unknown_fields": [], "url": "https://www.facebook.com/marketplace/item/1456476040872340/" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 2624, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "product", "id": "1456476040872340", "url": "https://www.facebook.com/marketplace/item/1456476040872340/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookListingResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Item for sale with price, photos and seller", "tags": [ "Facebook Marketplace" ], "x-socialtap-endpoint": "facebook.listing", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/photos": { "get": { "description": "Returns the photos on a public Facebook Page's or person's Photos tab, newest first, a page at a time: its own uploads or the photos it's tagged in. Each photo has its ID and link, its full-size image with width, height and link expiry, the square crop the grid shows, and Facebook's description of what it pictures. Send a name, ID or link, and an optional time window Facebook applies itself.\n\nReturns `{data, page, meta}`: `data` holds up to 8 `Post` items (the shared schema, the same on every platform), Newest first, as the Photos tab shows them. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/photos/ (Markdown: https://socialtap.dev/docs/reference/facebook/photos/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/photos/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/photos/" }, "operationId": "facebook.photos.list", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "example": "NASA", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "examples": [ "NASA" ], "maxLength": 2048, "type": "string" } }, { "description": "Which photos: uploaded, the profile's own (the tab Facebook calls 's Photos); tagged, the ones others tagged it in (Photos of ), which people's profiles have and Pages don't: an empty list when the profile shows none.", "example": "", "in": "query", "name": "tab", "schema": { "default": "uploaded", "description": "Which photos: uploaded, the profile's own (the tab Facebook calls 's Photos); tagged, the ones others tagged it in (Photos of ), which people's profiles have and Pages don't: an empty list when the profile shows none.", "enum": [ "uploaded", "tagged" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only photos created at or after this time: Facebook's own filter, since a photo in this list carries no date.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only photos created at or after this time: Facebook's own filter, since a photo in this list carries no date.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only photos created before this time: Facebook's own filter, so the first page starts there.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only photos created before this time: Facebook's own filter, so the first page starts there.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 8, "in": "query", "name": "limit", "schema": { "default": 8, "maximum": 8, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png_s100x100&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&edm=SCRUBBED&_nc_gid=SCRUBBED&oh=SCRUBBED&oe=F2…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675983760563660", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An intricate cloud of white dust takes center stage in this photo, rising in a windy pillar. The background features rust-colored dust with dots of distant stars and galaxies shining through.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1385, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=c308.0.1385.1385a_dst-jpg_tt6&cstp=mx1385x1385&ctp=s552x414&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=dst-jpg_tt6&cstp=mx2000x1385&ctp=s2000x1385&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "width": 2000 } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": null, "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": null } }, "platform_type": "photo", "published_at": null, "text": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=c308.0.1385.1385a_dst-jpg_tt6&cstp=mx1385x1385&ctp=s552x414&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc…", "title": null, "type": "image", "unknown_fields": [ "coauthors", "hashtags", "mentions" ], "url": "https://www.facebook.com/photo/?fbid=1675983760563660" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png_s100x100&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&edm=SCRUBBED&_nc_gid=SCRUBBED&oh=SCRUBBED&oe=F2…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675279167300786", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An image that shows the \"MAX POWER Kennedy Space Center\" app as it appears in the iOS App Store.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1294, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=c377.0.1294.1294a_dst-jpg_tt6&cstp=mx1294x1294&ctp=s552x414&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=dst-jpg_tt6&cstp=mx2048x1294&ctp=s2048x1294&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "width": 2048 } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": null, "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": null } }, "platform_type": "photo", "published_at": null, "text": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=c377.0.1294.1294a_dst-jpg_tt6&cstp=mx1294x1294&ctp=s552x414&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_…", "title": null, "type": "image", "unknown_fields": [ "coauthors", "hashtags", "mentions" ], "url": "https://www.facebook.com/photo/?fbid=1675279167300786" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png_s100x100&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&edm=SCRUBBED&_nc_gid=SCRUBBED&oh=SCRUBBED&oe=F2…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1672152994280070", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "Three jet aircraft, each with a white nose and blue body, fly in a triangle formation against a clear blue sky. White trails follow each jet.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1280, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/872064392_1772088687399080_6520374397283068537_n.png?stp=c320.0.1280.1280a_dst-jpg_tt6&cstp=mx1280x1280&ctp=s552x414&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/872064392_1772088687399080_6520374397283068537_n.png?stp=dst-jpg_tt6&cstp=mx1920x1280&ctp=s1920x1280&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "width": 1920 } ], "mentions": [], "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": null, "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": null } }, "platform_type": "photo", "published_at": null, "text": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/872064392_1772088687399080_6520374397283068537_n.png?stp=c320.0.1280.1280a_dst-jpg_tt6&cstp=mx1280x1280&ctp=s552x414&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_…", "title": null, "type": "image", "unknown_fields": [ "coauthors", "hashtags", "mentions" ], "url": "https://www.facebook.com/photo/?fbid=1672152994280070" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 829, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100044561550831", "url": "https://www.facebook.com/nasa" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookPhotosResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Full-size photos, uploaded or tagged", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.photos", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Newest first, as the Photos tab shows them", "page_max": 8, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/place_events": { "get": { "description": "Returns the public Facebook events in a city from its events link or ID, for every coming date or a window such as this weekend. Each event has its name, whether it's scheduled, under way or over, its start time with its offset from UTC, whether it's online, its venue and city, cover, ticket price label, the series a recurring date belongs to, the group it was created in, and how many people are going and interested.\n\nReturns `{data, page, meta}`: `data` holds up to 12 `Event` items (the shared schema, the same on every platform), Facebook's ranking of the city's events, not by date. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\nIn Facebook's words: `metrics.attendee_count` is going.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/place_events/ (Markdown: https://socialtap.dev/docs/reference/facebook/place_events/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/place_events/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/place_events/" }, "operationId": "facebook.place_events.list", "parameters": [ { "description": "The city: its Facebook events link (facebook.com/events/explore///, with a time window after it such as /today/; m. and web. hosts too) or its numeric ID. Facebook keys a city by this ID: the Facebook Marketplace Location Search API answers it from a city's name, as id, and the Facebook Event API as platform_specific.facebook.city_id; in the /pages// link of its place.url, the ID is the number at the end.", "example": "https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547/", "in": "query", "name": "url", "required": true, "schema": { "description": "The city: its Facebook events link (facebook.com/events/explore///, with a time window after it such as /today/; m. and web. hosts too) or its numeric ID. Facebook keys a city by this ID: the Facebook Marketplace Location Search API answers it from a city's name, as id, and the Facebook Event API as platform_specific.facebook.city_id; in the /pages// link of its place.url, the ID is the number at the end.", "examples": [ "https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547/" ], "maxLength": 2048, "type": "string" } }, { "description": "Only events in this window, as Facebook's city page filters them; every coming event when omitted. Overrides a window in the link.", "example": "this_weekend", "in": "query", "name": "time", "schema": { "description": "Only events in this window, as Facebook's city page filters them; every coming event when omitted. Overrides a window in the link.", "enum": [ "today", "tomorrow", "this_weekend", "this_week", "next_week" ], "examples": [ "this_weekend" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 12, "in": "query", "name": "limit", "schema": { "default": 12, "maximum": 12, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.facebook.metrics.interested_count" ], "categories": [], "community_id": null, "cover_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-6/691737832_122221920272546827_3621567388430112740_n.jpg?stp=c0.45.1600.764a_dst-jpg_tt6&cstp=mx1600x764&ctp=s640x640&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_n…", "description": null, "end_at": null, "hosts": [], "id": "1009766568177406", "is_online": false, "metrics": { "attendee_count": 253 }, "name": "90s Day Party: St. Petersburg, FL 💿", "parent_id": null, "place": { "address": null, "city": "Saint Petersburg, Florida", "country_code": null, "id": null, "latitude": null, "longitude": null, "name": "2655 6th Ave S, St Petersburg, FL 33712-1653, United States", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": "111326725552547", "date_text": "Sat, Nov 7 at 3:00 PM EST", "frequency": null, "metrics": { "interested_count": 7500, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-07T20:00:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/1009766568177406/", "utc_offset_minutes": -300 }, { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-6/876819554_1438940761722368_3293008712652972469_n.jpg?stp=c0.29.1920.917a_dst-jpg_tt6&cstp=mx1920x917&ctp=s640x640&_nc_cat=102&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_…", "description": null, "end_at": null, "hosts": [], "id": "1117858504340275", "is_online": false, "metrics": { "attendee_count": 4 }, "name": "The Rocky Horror Spanksgiving Show!", "parent_id": null, "place": { "address": null, "city": "Saint Petersburg, Florida", "country_code": null, "id": "113001216940331", "latitude": null, "longitude": null, "name": "Green Light: Cinema, Lounge, Kitchen", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": "111326725552547", "date_text": "Sat, Nov 14 at 8:30 PM EST", "frequency": null, "metrics": { "interested_count": 79, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-15T01:30:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/1117858504340275/", "utc_offset_minutes": -300 }, { "approximate_fields": [ "platform_specific.facebook.metrics.interested_count" ], "categories": [], "community_id": null, "cover_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/851378089_1425164076476687_7376004806964005311_n.png?stp=c0.186.1080.516a_dst-jpg_tt6&cstp=mx1080x516&ctp=s640x640&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc…", "description": null, "end_at": null, "hosts": [], "id": "1488319459545073", "is_online": false, "metrics": { "attendee_count": 107 }, "name": "St. Pete Yoga Fest", "parent_id": null, "place": { "address": null, "city": "Saint Petersburg, Florida", "country_code": null, "id": null, "latitude": null, "longitude": null, "name": "The St. Pete Pier", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": "111326725552547", "date_text": "Sat, Nov 7 at 9:00 AM EST", "frequency": null, "metrics": { "interested_count": 1100, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2026-11-07T14:00:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/1488319459545073/", "utc_offset_minutes": -300 } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 793, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "place", "id": "111326725552547", "url": "https://www.facebook.com/events/explore/-/111326725552547/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookPlace_eventsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "By date window, with going and interested counts", "tags": [ "Facebook Events" ], "x-socialtap-endpoint": "facebook.place_events", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 10800, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Facebook's ranking of the city's events, not by date", "page_max": 12, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "event", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/post": { "get": { "description": "Returns a public Facebook post, photo, video or reel from its link or ID: text, author, date, and exact reaction, comment, share and view counts. It also has the reactions by type, hashtags and mentions, every photo of an album, the video file with its thumbnail, size and length, and the shared link card or reshared post.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/post/ (Markdown: https://socialtap.dev/docs/reference/facebook/post/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/post/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/post/" }, "operationId": "facebook.post.get", "parameters": [ { "description": "Facebook post, photo, video or reel URL: //posts/, permalink.php and story.php links, /photo/?fbid= and //photos/… links, reel, watch, video.php and //videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID.", "example": "https://www.facebook.com/reel/4075684206061398/", "in": "query", "name": "url", "required": true, "schema": { "description": "Facebook post, photo, video or reel URL: //posts/, permalink.php and story.php links, /photo/?fbid= and //photos/… links, reel, watch, video.php and //videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID.", "examples": [ "https://www.facebook.com/reel/4075684206061398/" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": 39381, "hashtags": [], "id": "1670768087751894", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": null, "duration_ms": 39381, "expires_at": "2026-10-25T18:00:00Z", "height": 2160, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/877658791_1832631854542515_4430770165954872904_n.jpg?stp=dst-jpg_tt6&cstp=mx1920x1080&ctp=s960x960&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "type": "video", "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQMS1Kmor5hpvEHAtxe3lVPcxOt4prhHPFgKMLcPxvBSvELFTPbkpMPfDvKx8gg5c4VOCCZrgCV0tzqv9ahLzz1s3O0N2Cdf2DaUFGeUSO0WTA.mp4?_nc_cat=106&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": 3840 } ], "mentions": [ "CanadianSpaceAgency", "ISS" ], "metrics": { "comment_count": 55, "like_count": 574, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": 52713 }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6MTY3MDc2ODA4Nzc1MTg5NA==", "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [ { "count": 476, "type": "like" }, { "count": 70, "type": "love" }, { "count": 13, "type": "care" } ], "shared_post": null, "video_id": "4075684206061398" } }, "platform_type": "reel", "published_at": "2026-10-29T11:48:37Z", "text": "NASA astronaut Anil Menon and Canadian Space Agency astronaut Joshua Kutryk are getting ready to head out of the International Space Station!\n \nAt this point, they have donned spacesuits called Extravehicular Mobility Units (EMUs), which contain all the protections and life suppo…", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/877658791_1832631854542515_4430770165954872904_n.jpg?stp=dst-jpg_tt6&cstp=mx1920x1080&ctp=s960x960&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "title": null, "type": "video", "unknown_fields": [], "url": "https://www.facebook.com/reel/4075684206061398/" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 1353, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "video", "id": "1670768087751894", "url": "https://www.facebook.com/reel/4075684206061398/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookPostResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Post, photo, video or reel with exact counts", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.post", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "request" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/posts": { "get": { "description": "Returns a public Facebook Page's or person's posts, newest first, a page at a time, from its name, ID or link. Each post has its text with hashtags and mentions, its photos, album, video or reel, its link card or the post it shares, its publish time, and exact reaction, comment and share counts with the reactions by type, plus a video's views and the author's name, picture and badge. since and until set a time window Facebook applies itself.\n\nReturns `{data, page, meta}`: `data` holds up to 3 `Post` items (the shared schema, the same on every platform), newest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/posts/ (Markdown: https://socialtap.dev/docs/reference/facebook/posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/posts/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/posts/" }, "operationId": "facebook.posts.list", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "example": "NASA", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "examples": [ "NASA" ], "maxLength": 2048, "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only posts published at or after this time. Facebook filters the timeline itself, and the walk ends at the first older post.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only posts published at or after this time. Facebook filters the timeline itself, and the walk ends at the first older post.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only posts published before this time: Facebook's own filter, so the first page starts there.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only posts published before this time: Facebook's own filter, so the first page starts there.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 3, "in": "query", "name": "limit", "schema": { "default": 3, "maximum": 3, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1676179567210746", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [], "mentions": [], "metrics": { "comment_count": 3, "like_count": 64, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 1, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMmlSQkFpeENQd1R1Zml6aUFWTXZRdWEzTEJuZHk2dGYzUHl2NDE1UWtaZjdGdjdneTM1U2VpRVltN3Z0UGNMcGps", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 60, "type": "like" }, { "count": 2, "type": "love" }, { "count": 1, "type": "care" } ], "shared_post": { "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/516872204_1189959146491994_4245240435554141606_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx2048x2047&ctp=s80x80&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "display_name": "Learn With NASA", "id": "100064337605401", "is_verified": true, "url": "https://www.facebook.com/LearnWithNASA", "username": "LearnWithNASA" }, "id": "1615866537234584", "url": "https://www.facebook.com/LearnWithNASA/posts/pfbid0qRf3ZGacva8hj6xVFVrBA29EF3mMnZGmcG6zYUaeLRB1yHARL2KHoPFaqH5jM72yl" }, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T19:27:52Z", "text": null, "thumbnail_url": null, "title": null, "type": "text", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid02iRBAixCPwTufiziAVMvQua3LBndy6tf3Pyv415QkZf7Fv7gy35SeiEYm7vtPcLpjl" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675983783896991", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An intricate cloud of white dust takes center stage in this photo, rising in a windy pillar. The background features rust-colored dust with dots of distant stars and galaxies shining through.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1385, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=dst-jpg_tt6&cstp=mx2000x1385&ctp=s2000x1385&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "width": 2000 } ], "mentions": [ "NASAWebb" ], "metrics": { "comment_count": 58, "like_count": 2431, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 185, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwZDJ3bUtXZm9Lc1Q5d0s5bndvV1c1SHpzRWd2MjhjSno5UTZuUDVBMjZCTGNrdVFlQWJCWnNQM0RuSm1pU2s3Q2w=", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 1657, "type": "like" }, { "count": 687, "type": "love" }, { "count": 42, "type": "care" } ], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-03T15:00:35Z", "text": "Pspsps 🐈‍⬛\n\nThis smoky specter is the Cat’s Head Nebula, captured in intricate detail by NASA's James Webb Space Telescope. Its name comes from its shape, which resembles a cosmic kitty sitting with its back toward the viewer. What do you see?", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/871223884_1487536193225483_3660942795677810580_n.png?stp=dst-jpg_tt6&cstp=mx2000x1385&ctp=s2000x1385&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid0d2wmKWfoKsT9wK9nwoWW5HzsEgv28cJz9Q6nP5A26BLckuQeAbBZsP3DnJmiSk7Cl" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b…", "display_name": "NASA - National Aeronautics and Space Administration", "id": "100044561550831", "is_verified": true, "url": "https://www.facebook.com/NASA", "username": "NASA" }, "coauthors": [], "duration_ms": null, "hashtags": [], "id": "1675279183967451", "is_nsfw": null, "is_pinned": null, "is_sponsored": null, "language": null, "media": [ { "alt_text": "An image that shows the \"MAX POWER Kennedy Space Center\" app as it appears in the iOS App Store.", "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": 1294, "thumbnail_url": null, "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=dst-jpg_tt6&cstp=mx2048x1294&ctp=s2048x1294&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "width": 2048 } ], "mentions": [], "metrics": { "comment_count": 18, "like_count": 248, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 29, "view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMnBqYUxiZmhBbkZtckRvb254eDdHeWVwVDFIN3BGYmk5d3JwcXF1TDZvTTVnVFVKYmZCRTJCVDJYY2h0RzkzcjJs", "group": null, "is_attachment_unavailable": false, "link": null, "listing": null, "music": null, "reactions": [ { "count": 215, "type": "like" }, { "count": 25, "type": "love" }, { "count": 5, "type": "care" } ], "shared_post": null, "video_id": null } }, "platform_type": "post", "published_at": "2026-11-02T22:30:00Z", "text": "Planning your trip to MAX POWER? We've got a tool for that.\n\nEvent schedules, maps, and FAQs are at your fingertips with the MAX POWER app. It's free and available to download from official app stores on iOS and Android devices: https://go.nasa.gov/3V2iiWX", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.99422-6/864280748_2020097565352172_6759494451320615303_n.png?stp=dst-jpg_tt6&cstp=mx2048x1294&ctp=s2048x1294&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "title": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/NASA/posts/pfbid02pjaLbfhAnFmrDoonxx7GyepT1H7pFbi9wrpqquL6oM5gTUJbfBE2BT2XchtG93r2l" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1578, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100044561550831", "url": "https://www.facebook.com/nasa" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookPostsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Newest first, with exact reactions and shares", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "newest first", "page_max": 3, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/profile": { "get": { "description": "Returns a public Facebook Page's or person's profile from its name, ID or link: name, bio, category, picture, links and exact follower count. It also has the cover, verified badge, following count and creation date. A business adds its address, phone, email, rating, reviews, price range, services and weekly opening hours. A Page adds whether it is running ads, its Ad Library Page ID, its confirmed owner, where its admins are and its past names. A person adds the work, education and places their intro shows.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/profile/ (Markdown: https://socialtap.dev/docs/reference/facebook/profile/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/profile/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/profile/" }, "operationId": "facebook.profile.get", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID or Page ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-, /pages/category/…, fb.me/.", "example": "NASA", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (NASA, case-insensitive), its numeric profile ID or Page ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-, /pages/category/…, fb.me/.", "examples": [ "NASA" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=dst-png&cstp=mx800x800&ctp=s800x800&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b28…", "banner_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.99422-6/809146614_4484013928506139_3181913787670602881_n.png?stp=dst-jpg_tt6&cstp=mx2047x1487&ctp=s2047x1487&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…", "bio": "Explore the universe and discover our home planet. \nThere's space for everybody. ✨", "category": "Government organization", "country_code": null, "created_at": "2009-03-04T21:45:25Z", "display_name": "NASA - National Aeronautics and Space Administration", "external_links": [ { "title": "nasa.gov/nasa-app", "url": "https://www.nasa.gov/nasa-app/" }, { "title": "nasa.gov", "url": "https://www.nasa.gov/" } ], "id": "100044561550831", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": 28731903, "following_count": 52, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "ad_library_entity_type": null, "admin_countries": [ { "count": 15, "country": "United States" } ], "alternate_name": null, "business_hours": [], "education": [], "email": "public-inquiries@hq.nasa.gov", "gender": null, "hometown": null, "hours_status": null, "instagram_follower_count": null, "instagram_username": null, "is_deleted": null, "is_instagram_verified": null, "is_memorialized": false, "is_political_advertiser": false, "is_running_ads": false, "name_changes": [ { "changed_at": "2014-04-07T19:49:21Z", "name": "NASA - National Aeronautics and Space Administration" } ], "owner_location": "WASHINGTON DC, 20024 United States of America", "owner_name": "NATIONAL AERONAUTICS AND SPACE ADMINISTRATION", "page_id": "54971236771", "phone": null, "price_range": null, "rating": null, "recommend_percent": null, "relationship": null, "review_count": null, "services": [], "talking_about_count": null, "were_here_count": null, "work": [] } }, "type": "organization", "unknown_fields": [], "url": "https://www.facebook.com/NASA", "username": "NASA" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1393, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100044561550831", "url": "https://www.facebook.com/NASA" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookProfileResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Exact follower count, contact info and hours", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.profile", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/reels": { "get": { "description": "Returns a public Facebook Page's or person's latest reels, newest first, a page at a time, from its Reels tab. Each reel has its caption with hashtags and mentions, video file with length and size, cover image, publish time, views, reactions, comments and shares, the sound it credits, its paid-partnership label, and its author and co-authors. Send a name, ID or link, and an optional time window.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Post` items (the shared schema, the same on every platform), newest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/reels/ (Markdown: https://socialtap.dev/docs/reference/facebook/reels/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/reels/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/reels/" }, "operationId": "facebook.reels.list", "parameters": [ { "description": "The Facebook profile (a Page's or a person's): its vanity name (natgeo, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "example": "natgeo", "in": "query", "name": "handle", "required": true, "schema": { "description": "The Facebook profile (a Page's or a person's): its vanity name (natgeo, case-insensitive), its numeric profile ID, or any link to it: facebook.com/ with any tab after it, profile.php?id=…, /people//, /p/-.", "examples": [ "natgeo" ], "maxLength": 2048, "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only reels published at or after this time. The walk ends at the first older reel.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only reels published at or after this time. The walk ends at the first older reel.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only reels published before this time. The walk starts at the newest and pages until it gets there, as far as the list goes logged out.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only reels published before this time. The walk starts at the newest and pages until it gets there, as far as the list goes logged out.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "metrics.view_count" ], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/475979419_1182307929933302_8257114326919725462_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx400x400&ctp=s80x80&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "display_name": "National Geographic", "id": "100044623170418", "is_verified": true, "url": "https://www.facebook.com/natgeo", "username": "natgeo" }, "coauthors": [], "duration_ms": 10965, "hashtags": [ "BestOfTheWorld" ], "id": "1710773677086722", "is_nsfw": null, "is_pinned": null, "is_sponsored": false, "language": null, "media": [ { "alt_text": null, "duration_ms": 10965, "expires_at": "2026-10-25T18:00:00Z", "height": 1920, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/884618825_30181052474816111_4627007225022417326_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=s960x960&_nc_cat=102&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_…", "type": "video", "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQNrV380hk7S-DTuHqiJuH0duqmGAV4F5h0pFX8Y1jzD_a9iu6MXjdSYaqruMbo4oweLTk3bOQwbcZLqDNlodHI05oDrnmF6tD5ebX_u7tp9YQ.mp4?_nc_cat=108&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": 1080 } ], "mentions": [], "metrics": { "comment_count": 7, "like_count": 262, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 6, "view_count": 20000 }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwdTR5aWlmZGRBR1hHZnVpS29yRmVpVGo1NEJlZkpxZGFiQ0ptelM3NzNKUko1UHdmOE1mcjFXc0tIVWFMOFNKaGw=", "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": "1631236835362063" } }, "platform_type": "reel", "published_at": "2026-11-03T22:10:02Z", "text": "Cascading more than 2,500 feet (762 meters), Gocta waterfall, near the village of Cocachimba in northern Peru, is one of the world’s tallest waterfalls. It's just one of the incredible sights that visitors can discover in northern Peru, a region gaining further interest thanks to…", "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/884618825_30181052474816111_4627007225022417326_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=s960x960&_nc_cat=102&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_…", "title": null, "type": "video", "unknown_fields": [ "platform_specific.facebook.reactions" ], "url": "https://www.facebook.com/reel/1631236835362063/" }, { "approximate_fields": [ "metrics.view_count" ], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/475979419_1182307929933302_8257114326919725462_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx400x400&ctp=s80x80&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "display_name": "National Geographic", "id": "100044623170418", "is_verified": true, "url": "https://www.facebook.com/natgeo", "username": "natgeo" }, "coauthors": [], "duration_ms": 32085, "hashtags": [ "BestOfTheWorld" ], "id": "1709576883873068", "is_nsfw": null, "is_pinned": null, "is_sponsored": false, "language": null, "media": [ { "alt_text": null, "duration_ms": 32085, "expires_at": "2026-10-25T18:00:00Z", "height": 1920, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t15.5256-10/886300512_29290661380565589_5039700284158011991_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=s960x960&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "type": "video", "url": "https://video-atl3-2.xx.fbcdn.net/o1/v/t2/f2/m366/AQMRYjf0DimPSWb5O4bvII4BWep8VM0GY9JergDwo_v7skKMWJyX4oGxwcjqSKqoKTVOw22I4p-nPKxCi2eM3_i6OM8Nbzr0q_-iGIozc3hkJQ.mp4?_nc_cat=102&_nc_sid=SCRUBBED&_nc_ht=video-atl3-2.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": 1080 } ], "mentions": [], "metrics": { "comment_count": 11, "like_count": 1353, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 48, "view_count": 182000 }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwNG1KVXBDMkV2aVJIc0pVVkYxQWVWVU5WY0FoaTJtN1JoNHRuTUw1TnUyV2RxYlloRE5NYXM4eG9HaTdiN2ZXeWw=", "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": "29290659273899133" } }, "platform_type": "reel", "published_at": "2026-11-02T18:00:14Z", "text": "Chase waterfalls in Cocachimba, wander the ancient walls of Kuélap, explore the streets of Chachapoyas, and venture deep into Quiocta's caverns. Northern Peru is full of places that stay with you long after you've left.\n\nCurated by Nat Geo’s team of experts and editors around the…", "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t15.5256-10/886300512_29290661380565589_5039700284158011991_n.jpg?stp=dst-jpg_tt6&cstp=mx1080x1920&ctp=s960x960&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "title": null, "type": "video", "unknown_fields": [ "platform_specific.facebook.reactions" ], "url": "https://www.facebook.com/reel/29290659273899133/" }, { "approximate_fields": [ "metrics.view_count" ], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/475979419_1182307929933302_8257114326919725462_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx400x400&ctp=s80x80&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…", "display_name": "National Geographic", "id": "100044623170418", "is_verified": true, "url": "https://www.facebook.com/natgeo", "username": "natgeo" }, "coauthors": [], "duration_ms": 90920, "hashtags": [ "DrainTheOceans" ], "id": "1708712703959486", "is_nsfw": null, "is_pinned": null, "is_sponsored": false, "language": null, "media": [ { "alt_text": null, "duration_ms": 90920, "expires_at": "2026-10-25T18:00:00Z", "height": 1920, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t15.5256-10/883629753_4647701772175040_9209268733401403077_n.jpg?stp=dst-jpg_tt6&cstp=mx405x720&ctp=s405x720&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_…", "type": "video", "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQMNqdBI936nFPwhn9KByEaD3NFWV-NUvAIKm-M1EuyRRvLTVW8QSn00axkLwpgsnt96nuvurTD_6A3i60nsQu34MUTmXoiSttQSLeeF80_kBQ.mp4?_nc_cat=106&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…", "width": 1080 } ], "mentions": [ "DisneyPlus", "hulu" ], "metrics": { "comment_count": 20, "like_count": 1957, "quote_count": null, "repost_count": null, "save_count": null, "share_count": 67, "view_count": 234000 }, "platform": "facebook", "platform_specific": { "facebook": { "feedback_id": "ZmVlZGJhY2s6cGZiaWQwMmlOMVRCcWZxQlB3YnRQaVdrTXpFUXhLVnJuV2Z2Z0NTWGRjbWEzTnNCNTNQVENIb3AyNHROdmNqaWo5dUNOYmFs", "group": null, "is_attachment_unavailable": null, "link": null, "listing": null, "music": null, "reactions": [], "shared_post": null, "video_id": "1888471619202224" } }, "platform_type": "reel", "published_at": "2026-11-01T22:00:00Z", "text": "Using ancient dinosaur bones and skin, experts were able to piece together the identity of this mysterious fossil. \n\n#DrainTheOceans is now streaming on Disney+ and Hulu.", "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t15.5256-10/883629753_4647701772175040_9209268733401403077_n.jpg?stp=dst-jpg_tt6&cstp=mx405x720&ctp=s405x720&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_…", "title": null, "type": "video", "unknown_fields": [ "platform_specific.facebook.reactions" ], "url": "https://www.facebook.com/reel/1888471619202224/" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "page", "is_cached": false, "credits_charged": 1, "latency_ms": 1880, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "100044623170418", "url": "https://www.facebook.com/natgeo" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookReelsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Newest first, with views and video files", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.reels", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "newest first", "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "post", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/replies": { "get": { "description": "Returns the replies to one comment on a public Facebook post, photo, video or reel, oldest first, replies to replies included. Each reply has its text, time, permalink, the comment it answers, exact reaction count with the reactions by type, attached photo and whether the post's author wrote it, and the replier's ID, name, profile link, picture and verified badge. Send the comment's link from the Facebook Comments API, or the post's link and the comment's ID.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Comment` items (the shared schema, the same on every platform), oldest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/replies/ (Markdown: https://socialtap.dev/docs/reference/facebook/replies/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/replies/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/replies/" }, "operationId": "facebook.replies.list", "parameters": [ { "description": "The comment's link, as the Facebook Comments API returns it in data[].url: the post, photo, video or reel link with ?comment_id= (a reply's link, with reply_comment_id too, reads the thread it is in). Or any link the Facebook Comments API takes (post, permalink.php, story.php, photo, reel, watch, video, fb.watch and share links, m., mbasic. and web. hosts, a numeric ID) with the comment_id param.", "example": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl", "in": "query", "name": "url", "required": true, "schema": { "description": "The comment's link, as the Facebook Comments API returns it in data[].url: the post, photo, video or reel link with ?comment_id= (a reply's link, with reply_comment_id too, reads the thread it is in). Or any link the Facebook Comments API takes (post, permalink.php, story.php, photo, reel, watch, video, fb.watch and share links, m., mbasic. and web. hosts, a numeric ID) with the comment_id param.", "examples": [ "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=1134072982431001" ], "maxLength": 2048, "type": "string" } }, { "description": "ID of the top-level comment whose replies to list (data[].id from the Facebook Comments API). Required unless url is a comment's link.", "example": "2241840356745830", "in": "query", "name": "comment_id", "schema": { "description": "ID of the top-level comment whose replies to list (data[].id from the Facebook Comments API). Required unless url is a comment's link.", "examples": [ "1134072982431001" ], "maxLength": 25, "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/468351006_10159593503532255_6774442294622346739_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx488x488&ctp=s32x32&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_…", "display_name": "Joe Krozel", "id": "pfbid02adNe4WrmH1JqGH4w8KfHniEngAHQXky7jRYawTwtdhGRAdoBdb1kRtdzy6iNRJbBl", "is_verified": false, "url": "https://www.facebook.com/joe.krozel", "username": "joe.krozel" }, "edited_at": null, "id": "2219135261976665", "is_by_post_author": null, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 1, "reply_count": 1 }, "parent_id": "2241840356745830", "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "male", "image_url": null, "reactions": [ { "count": 1, "type": "haha" } ] } }, "post_id": "1515533333772646", "published_at": "2026-10-29T22:42:30Z", "text": "Steve Jenkins Hey loser, Republicans don't take polls, so the polls underreport their support. Fox is just passing it on as it is received. Blue wave is fictitious.", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=2241840356745830&reply_comment_id=2219135261976665" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/453750901_122190017804061302_7467119486547392352_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx849x850&ctp=s32x32&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&…", "display_name": "Jenna Redstone", "id": "61551839077397", "is_verified": false, "url": "https://www.facebook.com/marion.weiler.2023", "username": "marion.weiler.2023" }, "edited_at": null, "id": "1995314554488520", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 1, "reply_count": 2 }, "parent_id": "2241840356745830", "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "female", "image_url": null, "reactions": [ { "count": 1, "type": "haha" } ] } }, "post_id": "1515533333772646", "published_at": "2026-10-30T08:40:18Z", "text": "Steve Jenkins They always have been more truthful.", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=2241840356745830&reply_comment_id=1995314554488520" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/511906991_24085412141097078_6841766951798215929_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx648x648&ctp=s32x32&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_…", "display_name": "Steve Jenkins", "id": "pfbid02tWsPGdCcwsR9MDGBfyqw45aVVh34i1ZxbmHZ41TniRyXx4VMoQAmgt2ikBy1fTLql", "is_verified": false, "url": "https://www.facebook.com/people/Steve-Jenkins/pfbid02tWsPGdCcwsR9MDGBfyqw45aVVh34i1ZxbmHZ41TniRyXx4VMoQAmgt2ikBy1fTLql/", "username": null }, "edited_at": null, "id": "1118282917795771", "is_by_post_author": null, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 0, "reply_count": 0 }, "parent_id": "1995314554488520", "platform": "facebook", "platform_specific": { "facebook": { "author_gender": "male", "image_url": null, "reactions": [] } }, "post_id": "1515533333772646", "published_at": "2026-10-30T13:00:28Z", "text": "Jenna Redstone Right, that's why they had to pay out 700+ million dollars for lying, you Maga cultists are funny as hell..", "unknown_fields": [], "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl?comment_id=2241840356745830&reply_comment_id=1118282917795771" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1166, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "1515533333772646", "url": "https://www.facebook.com/cnn/posts/pfbid034UhZgwWAxAbbbqcVT6TLJQz9aGu17AWYtaZib2nUzN6ueQKyvyoBSJ1Ao4R7Aibzl" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "end" } } } }, "schema": { "$ref": "#/components/schemas/FacebookRepliesResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Thread under a comment, both levels", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.replies", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "oldest first", "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "comment", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_ads": { "get": { "description": "Searches Meta's public Ad Library by keyword and returns the matching ads from Facebook, Instagram, Messenger, Threads and the Audience Network. Each ad has its advertiser, the days it first and last ran, whether it's still active, where it ran and its creatives: headline, text, link, call to action, images and videos. Political and social-issue ads add the payer and Meta's impression, reach and spend ranges. Filter by country, language, status and dates. Ads come most impressions first, the Ad Library's own order.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Ad` items (the shared schema, the same on every platform), most impressions first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_ads/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_ads/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_ads/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_ads/" }, "operationId": "facebook.search_ads.list", "parameters": [ { "description": "Keywords matched against the ad's text, in any order. Wrap the query in double quotes (\"cold brew\") to match an exact phrase.", "example": "coffee", "in": "query", "name": "query", "required": true, "schema": { "description": "Keywords matched against the ad's text, in any order. Wrap the query in double quotes (\"cold brew\") to match an exact phrase.", "examples": [ "coffee" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.", "example": "en", "in": "query", "name": "lang", "schema": { "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.", "examples": [ "en" ], "type": "string" } }, { "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.", "example": "active", "in": "query", "name": "status", "schema": { "default": "all", "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.", "enum": [ "active", "inactive", "all" ], "examples": [ "active" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "advertiser": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/739782028_1533198008291919_1079542453788497101_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/profile.php?id=61588018263996", "username": null }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "My aunt called me a creep for putting a camera in Nana’s living room.\n\nNana called me practical.\n\nThen the camera caught something worse than a fall.\n\nI need to be clear about one thing before anyone decides what kind of grandson I am.\n\nNana asked for the camera.\n\nNot me.\n\nNot my…", "cta_text": "Learn more", "link_description": null, "link_url": "https://shop.pipitea.com/hbt/kd/sp-nm", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742001725_2100792434176297_9060645049521596104_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742501415_1706621370582971_4085631001896338504_n.jpg?_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-07-18T07:00:00Z", "id": "2619351891814847", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Community Center" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 4072, "beneficiary": null, "collation_count": 1, "collation_id": "2362783507580471", "cta_type": "learn_more", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "shop.pipitea.com", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [] } }, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=2619351891814847" }, { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712623693_1599994994434095_1320701223312676781_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/profile.php?id=61588018263996", "username": null }, "approximate_fields": [ "first_shown_at", "last_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…", "cta_text": "Learn more", "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…", "link_url": "https://shop.pipitea.com/hbt/kd/sp", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/711729685_1717035472767079_186136568392095276_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/713729791_868879862958547_7409366389733397444_n.jpg?_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-06-01T07:00:00Z", "id": "1923645134954720", "impressions": null, "is_active": false, "is_political": false, "languages": [], "last_shown_at": "2026-10-30T07:00:00Z", "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Community Center" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 4072, "beneficiary": null, "collation_count": 1, "collation_id": "1304791095118481", "cta_type": "learn_more", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "shop.pipitea.com", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [] } }, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=1923645134954720" }, { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712025330_1303417705276292_736671271727941526_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/profile.php?id=61588018263996", "username": null }, "approximate_fields": [ "first_shown_at", "last_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…", "cta_text": "Learn more", "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…", "link_url": "https://shop.pipitea.com/hbt/kd/sp", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/711737708_4485707625086258_2353150069319301753_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/710755472_911440771966686_1736050619245168045_n.jpg?_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-06-01T07:00:00Z", "id": "2140497416496021", "impressions": null, "is_active": false, "is_political": false, "languages": [], "last_shown_at": "2026-10-30T07:00:00Z", "paid_by": null, "platform": "facebook", "platform_specific": { "facebook": { "advertiser_categories": [ "Community Center" ], "advertiser_instagram": null, "advertiser_instagram_follower_count": null, "advertiser_like_count": 4072, "beneficiary": null, "collation_count": 1, "collation_id": "884617784669236", "cta_type": "learn_more", "impression_shares": null, "is_advertiser_deleted": false, "is_removed": null, "is_synthetic": false, "link_caption": "shop.pipitea.com", "partner": null, "removal_reasons": [], "special_ad_categories": [], "targeting": [] } }, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [ "country_codes", "languages", "platform_specific.facebook.removal_reasons" ], "url": "https://www.facebook.com/ads/library/?id=2140497416496021" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1482, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_adsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Ads by keyword, with creatives and run dates", "tags": [ "Facebook Ad Library" ], "x-socialtap-endpoint": "facebook.search_ads", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 3600, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "most impressions first", "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_advertisers": { "get": { "description": "Returns the advertisers in Meta's public Ad Library that match a name, username or Page ID, as its search box suggests them. Each has its Page ID (the ID its ads are filed under), name, username, picture, category, country, verified badge and exact follower count, plus the Instagram account Meta links to it with that account's exact followers and badge. Send a country to rank the matches for it.\n\nReturns `{data, page, meta}`: `data` holds up to 15 `Profile` items (Facebook calls it a advertiser) (the shared schema, the same on every platform), the search box's own order. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_advertisers/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_advertisers/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_advertisers/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_advertisers/" }, "operationId": "facebook.search_advertisers.list", "parameters": [ { "description": "An advertiser's name or part of it, its Facebook username or its Page ID (never its profile ID), as typed into the Ad Library's search box, in any language (baileys, コカ・コーラ, 20531316728).", "example": "baileys", "in": "query", "name": "query", "required": true, "schema": { "description": "An advertiser's name or part of it, its Facebook username or its Page ID (never its profile ID), as typed into the Ad Library's search box, in any language (baileys, コカ・コーラ, 20531316728).", "examples": [ "baileys" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The country to search from: Meta ranks the matches for it, and an advertiser from elsewhere can still appear. An ISO 3166-1 alpha-2 code such as US. Every country when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). The country to search from: Meta ranks the matches for it, and an advertiser from elsewhere can still appear. An ISO 3166-1 alpha-2 code such as US. Every country when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 15, "in": "query", "name": "limit", "schema": { "default": 15, "maximum": 15, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/443711959_876169351217288_8358221437311147045_n.jpg?stp=dst-jpg_s200x200_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…", "banner_url": null, "bio": null, "category": "Wine/spirits", "country_code": null, "created_at": null, "display_name": "Baileys", "external_links": [], "id": "73939360594", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": 4664402, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "ad_library_entity_type": "PERSON_PROFILE", "admin_countries": [], "alternate_name": null, "business_hours": [], "education": [], "email": null, "gender": null, "hometown": null, "hours_status": null, "instagram_follower_count": 248872, "instagram_username": "baileysofficial", "is_deleted": false, "is_instagram_verified": true, "is_memorialized": null, "is_political_advertiser": null, "is_running_ads": null, "name_changes": [], "owner_location": null, "owner_name": null, "page_id": "73939360594", "phone": null, "price_range": null, "rating": null, "recommend_percent": null, "relationship": null, "review_count": null, "services": [], "talking_about_count": null, "were_here_count": null, "work": [] } }, "type": "unknown", "unknown_fields": [ "external_links", "platform_specific.facebook.services", "platform_specific.facebook.business_hours" ], "url": "https://www.facebook.com/Baileys", "username": "Baileys" }, { "approximate_fields": [], "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/445756898_874337388053755_8139191371735594555_n.jpg?stp=dst-jpg_s200x200_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…", "banner_url": null, "bio": null, "category": "Wine/spirits", "country_code": "GB", "created_at": null, "display_name": "Baileys", "external_links": [], "id": "151277918233754", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": 4664402, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "ad_library_entity_type": "PERSON_PROFILE", "admin_countries": [], "alternate_name": null, "business_hours": [], "education": [], "email": null, "gender": null, "hometown": null, "hours_status": null, "instagram_follower_count": null, "instagram_username": null, "is_deleted": false, "is_instagram_verified": null, "is_memorialized": null, "is_political_advertiser": null, "is_running_ads": null, "name_changes": [], "owner_location": null, "owner_name": null, "page_id": "151277918233754", "phone": null, "price_range": null, "rating": null, "recommend_percent": null, "relationship": null, "review_count": null, "services": [], "talking_about_count": null, "were_here_count": null, "work": [] } }, "type": "unknown", "unknown_fields": [ "external_links", "platform_specific.facebook.services", "platform_specific.facebook.business_hours" ], "url": "https://www.facebook.com/BaileysGB", "username": "BaileysGB" }, { "approximate_fields": [], "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/884884889_1163136826368298_466053757919124974_n.avif?stp=dst-avif_s200x200&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…", "banner_url": null, "bio": null, "category": "Wine/spirits", "country_code": "US", "created_at": null, "display_name": "Baileys", "external_links": [], "id": "109408419132021", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": 4664402, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "platform": "facebook", "platform_specific": { "facebook": { "ad_library_entity_type": "PERSON_PROFILE", "admin_countries": [], "alternate_name": null, "business_hours": [], "education": [], "email": null, "gender": null, "hometown": null, "hours_status": null, "instagram_follower_count": 149344, "instagram_username": "baileysus", "is_deleted": false, "is_instagram_verified": true, "is_memorialized": null, "is_political_advertiser": null, "is_running_ads": null, "name_changes": [], "owner_location": null, "owner_name": null, "page_id": "109408419132021", "phone": null, "price_range": null, "rating": null, "recommend_percent": null, "relationship": null, "review_count": null, "services": [], "talking_about_count": null, "were_here_count": null, "work": [] } }, "type": "unknown", "unknown_fields": [ "external_links", "platform_specific.facebook.services", "platform_specific.facebook.business_hours" ], "url": "https://www.facebook.com/baileysus", "username": "baileysus" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 434, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "platform_limit" } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_advertisersResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Advertisers by name, with Page IDs", "tags": [ "Facebook Ad Library" ], "x-socialtap-endpoint": "facebook.search_advertisers", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the search box's own order", "page_max": 15, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_events": { "get": { "description": "Searches public Facebook events by keyword, anywhere or in one place, and returns them in Facebook's own ranking. Each result has the event's ID, link and name, its start, venue and cover, whether it's online, its status, and how many people are interested and going. Narrow by date with since and until. When Facebook refuses the query, results come from the search's page and are thin: mostly the ID, link, name and a picture.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Event` items (the shared schema, the same on every platform), Facebook's ranking of the results, not by date. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\nIn Facebook's words: `metrics.attendee_count` is going.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_events/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_events/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_events/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_events/" }, "operationId": "facebook.search_events.list", "parameters": [ { "description": "The words to search events for, as in Facebook's event search: names, artists, topics, places.", "example": "jazz", "in": "query", "name": "query", "required": true, "schema": { "description": "The words to search events for, as in Facebook's event search: names, artists, topics, places.", "examples": [ "jazz" ], "maxLength": 500, "type": "string" } }, { "description": "Only events in this place: its Facebook events link (facebook.com/events/explore///) or its numeric ID, the one the Facebook Marketplace Location Search API answers as id and the Facebook City Events API takes. Omitted, Facebook searches everywhere.", "example": "108424279189115", "in": "query", "name": "location", "schema": { "description": "Only events in this place: its Facebook events link (facebook.com/events/explore///) or its numeric ID, the one the Facebook Marketplace Location Search API answers as id and the Facebook City Events API takes. Omitted, Facebook searches everywhere.", "examples": [ "108424279189115" ], "maxLength": 2048, "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 20, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent.ftol2-1.fna.fbcdn.net/v/t39.30808-6/737325123_4499264600219134_9055237808772320460_n.jpg?stp=c0.138.1254.836a_dst-jpg_tt6&cstp=mx1254x836&ctp=s1254x836&_nc_cat=101&_nc_map=urlgen_bucketless&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&…", "description": null, "end_at": null, "hosts": [], "id": "935939818906345", "is_online": false, "metrics": { "attendee_count": 1 }, "name": "JAZZ fest «Blue Note»", "parent_id": null, "place": { "address": null, "city": null, "country_code": null, "id": null, "latitude": null, "longitude": null, "name": "Тверская Область", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Tue, Jun 1, 2027 - Jun 15, 2027", "frequency": null, "metrics": { "interested_count": 3, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2027-05-31T21:00:00Z", "status": "scheduled", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/935939818906345/", "utc_offset_minutes": null }, { "approximate_fields": [], "categories": [], "community_id": null, "cover_url": "https://scontent.ftol2-1.fna.fbcdn.net/v/t39.30808-6/583712862_1185733750330218_7695504167411277837_n.jpg?stp=c160.0.1728.1152a_dst-jpg_tt6&cstp=mx1728x1152&ctp=s1728x1152&_nc_cat=106&_nc_map=urlgen_bucketless&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=…", "description": null, "end_at": null, "hosts": [], "id": "733095653165588", "is_online": false, "metrics": { "attendee_count": null }, "name": "Jazz Jam", "parent_id": null, "place": { "address": null, "city": null, "country_code": null, "id": "602685513168965", "latitude": null, "longitude": null, "name": "Funk 'n Waffles Syracuse", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Sun, Nov 8 at 3:00 PM EST and 7 more", "frequency": null, "metrics": { "interested_count": 403, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2025-11-23T20:00:00Z", "status": "ongoing", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/733095653165588/", "utc_offset_minutes": -300 }, { "approximate_fields": [ "platform_specific.facebook.metrics.interested_count" ], "categories": [], "community_id": null, "cover_url": "https://scontent.ftol2-1.fna.fbcdn.net/v/t39.30808-6/866591974_1157426943381928_6760248865572493930_n.jpg?stp=c206.0.1508.1005a_dst-jpg_tt6&cstp=mx1508x1005&ctp=s1508x1005&_nc_cat=107&_nc_map=urlgen_bucketless&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=…", "description": null, "end_at": null, "hosts": [], "id": "769677042050918", "is_online": false, "metrics": { "attendee_count": 1 }, "name": "Sunday Jazz Service", "parent_id": null, "place": { "address": null, "city": null, "country_code": null, "id": null, "latitude": null, "longitude": null, "name": "Eliaskirken, Vesterbrogade 49, 1620 Copenhagen, Denmark", "url": null }, "platform": "facebook", "platform_specific": { "facebook": { "city_id": null, "date_text": "Sun, Nov 8 at 1:00 PM CET and 2 more", "frequency": null, "metrics": { "interested_count": 1400, "response_count": null }, "occurrence_count": null, "price_text": null, "ticket_provider": null } }, "start_at": "2025-11-02T12:00:00Z", "status": "ongoing", "ticket_url": null, "time_zone": null, "unknown_fields": [ "hosts", "categories" ], "url": "https://www.facebook.com/events/769677042050918/", "utc_offset_minutes": 60 } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1374, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_eventsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Events by keyword, anywhere or in one city", "tags": [ "Facebook Events" ], "x-socialtap-endpoint": "facebook.search_events", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 1800, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Facebook's ranking of the results, not by date", "page_max": 20, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "event", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_groups": { "get": { "description": "Returns the Facebook groups a web search finds for a topic, place or name, with each group's link, vanity name, title and description. Its privacy is included when the search index shows it. Add fill=true for each group's full, live record in the same response: ID, exact member count, privacy, rules, admins and activity. Page through the results with the cursor.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Web result` items (the shared schema, the same on every platform), the search engine's ranking (most relevant first). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit + 1 per result filled in per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_groups/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_groups/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_groups/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_groups/" }, "operationId": "facebook.search_groups.list", "parameters": [ { "description": "Words to find Facebook groups by, as a web search reads them: a topic, a place, a group's name (gardening, buy and sell houston, \"addicted to gardening\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and an operator that narrows to a page's title, text or link (intitle:, inurl:, intext:, url:) reads as its words.", "example": "gardening", "in": "query", "name": "query", "required": true, "schema": { "description": "Words to find Facebook groups by, as a web search reads them: a topic, a place, a group's name (gardening, buy and sell houston, \"addicted to gardening\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and an operator that narrows to a page's title, text or link (intitle:, inurl:, intext:, url:) reads as its words.", "examples": [ "gardening" ], "maxLength": 200, "type": "string" } }, { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "example": "true", "in": "query", "name": "fill", "schema": { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "enum": [ "true", "false" ], "examples": [ "true" ], "type": "string" } }, { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "example": "BR", "in": "query", "name": "country", "schema": { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "examples": [ "BR" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "community.title", "community.description" ], "community": { "avatar_url": null, "description": "Visit harvestsavvy.com to learn Everything Gardening! This online community is for all plant lovers, gardening and farming enthusiasts focused on sharing...", "id": null, "metrics": { "member_count": null }, "name": "youreverythinggardening", "privacy": null, "title": "Everything Gardening", "url": "https://www.facebook.com/groups/youreverythinggardening/" }, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/groups/youreverythinggardening/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 0, "post": null, "profile": null, "snippet": "Visit harvestsavvy.com to learn Everything Gardening! This online community is for all plant lovers, gardening and farming enthusiasts focused on sharing...", "sound": null, "title": "Everything Gardening - Facebook", "type": "community", "unknown_fields": [], "url": "https://www.facebook.com/groups/youreverythinggardening/" }, { "approximate_fields": [ "community.title", "community.description" ], "community": { "avatar_url": null, "description": "We provide some information about plant guides, lawn cares, and gardening tools to better help your organic garden grow 🌻 Note: Please keep in mind that this is a Facebook page for a group of people interested in gardening and landscaping.", "id": null, "metrics": { "member_count": null }, "name": null, "privacy": null, "title": "Gardening", "url": "https://www.facebook.com/groups/2541811060/" }, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/groups/2541811060/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 1, "post": null, "profile": null, "snippet": "We provide some information about plant guides, lawn cares, and gardening tools to better help your organic garden grow 🌻 Note: Please keep in mind that this is a Facebook page for a group of people interested in gardening and landscaping.", "sound": null, "title": "Gardening - Facebook", "type": "community", "unknown_fields": [], "url": "https://www.facebook.com/groups/2541811060/" }, { "approximate_fields": [ "community.title", "community.description" ], "community": { "avatar_url": null, "description": "With the gardening season upon us now, we are looking to take on more garden maintenance customers for this season There are only very limited slots available, with that being said we are also looking to take on one off jobs throughout the season. This can be from full garden tid…", "id": null, "metrics": { "member_count": null }, "name": null, "privacy": null, "title": "SM GARDENING", "url": "https://www.facebook.com/groups/543243157060853/" }, "details": null, "hashtag": null, "matched_url": "https://business.facebook.com/groups/543243157060853/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 2, "post": null, "profile": null, "snippet": "With the gardening season upon us now, we are looking to take on more garden maintenance customers for this season There are only very limited slots available, with that being said we are also looking to take on one off jobs throughout the season. This can be from full garden tid…", "sound": null, "title": "SM GARDENING | Facebook", "type": "community", "unknown_fields": [], "url": "https://www.facebook.com/groups/543243157060853/" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "web_search", "is_cached": false, "credits_charged": 1, "latency_ms": 1127, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_groupsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Groups by topic, place or name", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.search_groups", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the search engine's ranking (most relevant first)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 51, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit + 1 per result filled in", "max": 51, "per": 1, "source": "", "unit": "filled_result", "unit_max": 50 } ], "unit": "page" }, "x-socialtap-resource": "web_result", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_listings": { "get": { "description": "Searches public Facebook Marketplace listings by keyword around a place, given as coordinates or a Marketplace location. Each result has its title, price with the struck-through earlier one, currency, availability, main photo, seller, city, category, the day it was listed and delivery options, and vehicles their mileage. Filter by radius, price, condition, days listed, availability, delivery method and category, and sort by relevance, newest, distance or price.\n\nReturns `{data, page, meta}`: `data` holds up to 30 `Product` items (Facebook calls it a listing) (the shared schema, the same on every platform), Marketplace's Suggested order with sort=relevance (the default), the closest to the place first with sort=nearest, the latest listed first, by the day: later pages can hold newer listings with sort=newest, the lowest price first with sort=price_asc, the highest price first with sort=price_desc. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_listings/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_listings/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_listings/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_listings/" }, "operationId": "facebook.search_listings.list", "parameters": [ { "description": "Keywords to search listings for. Marketplace also returns close matches.", "example": "couch", "in": "query", "name": "query", "required": true, "schema": { "description": "Keywords to search listings for. Marketplace also returns close matches.", "examples": [ "couch" ], "maxLength": 200, "type": "string" } }, { "description": "Latitude of the place to search around (WGS 84 degrees), with lng; or use location.", "example": "30.2677", "in": "query", "name": "lat", "schema": { "description": "Latitude of the place to search around (WGS 84 degrees), with lng; or use location.", "examples": [ 30.2677 ], "format": "double", "maximum": 90, "minimum": -90, "type": "number" } }, { "description": "Longitude of the place to search around (WGS 84 degrees), with lat; or use location.", "example": "-97.7475", "in": "query", "name": "lng", "schema": { "description": "Longitude of the place to search around (WGS 84 degrees), with lat; or use location.", "examples": [ -97.7475 ], "format": "double", "maximum": 180, "minimum": -180, "type": "number" } }, { "description": "The place to search around, instead of lat and lng: a Marketplace place ID (platform_specific.facebook.location_id of a listing there, such as 106224666074625), the city name in Marketplace's links (austin, nyc, paris) or such a link (https://www.facebook.com/marketplace/austin/). An unknown one returns not_found.", "example": "austin", "in": "query", "name": "location", "schema": { "description": "The place to search around, instead of lat and lng: a Marketplace place ID (platform_specific.facebook.location_id of a listing there, such as 106224666074625), the city name in Marketplace's links (austin, nyc, paris) or such a link (https://www.facebook.com/marketplace/austin/). An unknown one returns not_found.", "examples": [ "austin" ], "maxLength": 300, "type": "string" } }, { "description": "How far around the place to search, in kilometers (default 65). Marketplace widens a search with few results near the place.", "example": "", "in": "query", "name": "radius_km", "schema": { "description": "How far around the place to search, in kilometers (default 65). Marketplace widens a search with few results near the place.", "format": "int64", "maximum": 805, "minimum": 1, "type": "integer" } }, { "description": "Only listings at this price or above, in major units of the local currency.", "example": "", "in": "query", "name": "min_price", "schema": { "description": "Only listings at this price or above, in major units of the local currency.", "format": "double", "maximum": 2147483647, "minimum": 0, "type": "number" } }, { "description": "Only listings at this price or below, in major units of the local currency. Omitted or 0 means no upper bound, so it cannot select only free listings.", "example": "", "in": "query", "name": "max_price", "schema": { "description": "Only listings at this price or below, in major units of the local currency. Omitted or 0 means no upper bound, so it cannot select only free listings.", "format": "double", "maximum": 2147483647, "minimum": 0, "type": "number" } }, { "description": "Order of the results. relevance (default): Marketplace's Suggested order. newest: the latest listed first. nearest: the closest to the place first. price_asc, price_desc: the lowest or the highest price first.", "example": "", "in": "query", "name": "sort", "schema": { "default": "relevance", "description": "Order of the results. relevance (default): Marketplace's Suggested order. newest: the latest listed first. nearest: the closest to the place first. price_asc, price_desc: the lowest or the highest price first.", "enum": [ "relevance", "newest", "nearest", "price_asc", "price_desc" ], "type": "string" } }, { "description": "The window the ranking counts over, in days back from the platform's latest update (each endpoint lists its own). Only listings Marketplace counts as listed in the last 1, 7 or 30 days, in whole calendar days (today counts, so 1 can include yesterday's). All dates when omitted.", "example": "7", "in": "query", "name": "period", "schema": { "description": "The window the ranking counts over, in days back from the platform's latest update (each endpoint lists its own). Only listings Marketplace counts as listed in the last 1, 7 or 30 days, in whole calendar days (today counts, so 1 can include yesterday's). All dates when omitted.", "enum": [ "1", "7", "30" ], "examples": [ "7" ], "type": "string" } }, { "description": "Only listings in these conditions, comma-separated: new, used_like_new, used_good, used_fair. All when omitted.", "example": "new,used_good", "in": "query", "name": "condition", "schema": { "description": "Only listings in these conditions, comma-separated: new, used_like_new, used_good, used_fair. All when omitted.", "examples": [ "new,used_good" ], "maxLength": 60, "type": "string" } }, { "description": "available (default): listings for sale now. sold: listings marked sold or with a sale pending.", "example": "", "in": "query", "name": "availability", "schema": { "description": "available (default): listings for sale now. sold: listings marked sold or with a sale pending.", "enum": [ "available", "sold" ], "type": "string" } }, { "description": "all (default), only listings the buyer can pick up (local_pickup), or only those the seller ships (shipping), which can come from far away.", "example": "", "in": "query", "name": "delivery_method", "schema": { "description": "all (default), only listings the buyer can pick up (local_pickup), or only those the seller ships (shipping), which can come from far away.", "enum": [ "all", "local_pickup", "shipping" ], "type": "string" } }, { "description": "Only listings in this Marketplace category (data[].category_id of a listing, such as 1658310421102081 for Bicycles).", "example": "", "in": "query", "name": "category_id", "schema": { "description": "Only listings in this Marketplace category (data[].category_id of a listing, such as 1658310421102081 for Bicycles).", "maxLength": 25, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 30, "in": "query", "name": "limit", "schema": { "default": 30, "maximum": 30, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "attributes": [], "availability": "in_stock", "category": null, "category_id": "1583634935226685", "condition": null, "condition_label": null, "country_code": null, "currency": "USD", "description": null, "id": "2453157098823358", "max_price": 150, "media": [], "original_price": 199, "platform": "facebook", "platform_specific": { "facebook": { "delivery_types": [ "in_person" ], "is_buy_now_enabled": null, "is_local_pickup": true, "latitude": null, "location": "Austin, TX", "location_id": "106224666074625", "longitude": null, "postal_code": null, "price_period": null, "published_at": "2026-08-08T23:19:48Z", "seller_joined_at": null, "seller_rating": null, "seller_rating_count": null } }, "price": 150, "seller": { "avatar_url": null, "display_name": "Emma Lacayo", "id": "pfbid028Sb5xn7vbqx7e9FMM94r2aYCMPpRvZ3tqQrtarsZFL3C4J9qjTrG5yKqfHATwFV7l", "is_verified": null, "url": null, "username": null }, "shipping": { "fee": null, "is_offered": false }, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.84726-6/770825152_1048174351401284_1140858447926294965_n.jpg?stp=c0.87.526.526a_dst-jpg_p526x395_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7…", "title": "Couch", "type": "listing", "unknown_fields": [ "attributes", "media" ], "url": "https://www.facebook.com/marketplace/item/2453157098823358/" }, { "approximate_fields": [], "attributes": [], "availability": "in_stock", "category": null, "category_id": "1583634935226685", "condition": null, "condition_label": null, "country_code": null, "currency": "USD", "description": null, "id": "2058904701477440", "max_price": 0, "media": [], "original_price": 50, "platform": "facebook", "platform_specific": { "facebook": { "delivery_types": [ "in_person" ], "is_buy_now_enabled": null, "is_local_pickup": true, "latitude": null, "location": "Austin, TX", "location_id": "106224666074625", "longitude": null, "postal_code": null, "price_period": null, "published_at": "2026-10-30T22:41:54Z", "seller_joined_at": null, "seller_rating": null, "seller_rating_count": null } }, "price": 0, "seller": { "avatar_url": null, "display_name": "Joseph Nelson", "id": "pfbid02LXiNxAkFuVeVVp6m2pNoHNMKLHXNfewhx35WhL5p3DJTrxZEnmKBiEUGxhHqnexl", "is_verified": null, "url": null, "username": null }, "shipping": { "fee": null, "is_offered": false }, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.84726-6/865992404_2598858703877779_3582095600555384707_n.jpg?stp=c123.0.540.540a_dst-jpg_p180x540_tt6&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=…", "title": "Sectional couch", "type": "listing", "unknown_fields": [ "attributes", "media" ], "url": "https://www.facebook.com/marketplace/item/2058904701477440/" }, { "approximate_fields": [], "attributes": [], "availability": "in_stock", "category": null, "category_id": "1583634935226685", "condition": null, "condition_label": null, "country_code": null, "currency": "USD", "description": null, "id": "1074423591747937", "max_price": 300, "media": [], "original_price": null, "platform": "facebook", "platform_specific": { "facebook": { "delivery_types": [ "in_person", "public_meetup" ], "is_buy_now_enabled": null, "is_local_pickup": true, "latitude": null, "location": "Austin, TX", "location_id": "106224666074625", "longitude": null, "postal_code": null, "price_period": null, "published_at": "2026-08-31T16:04:49Z", "seller_joined_at": null, "seller_rating": null, "seller_rating_count": null } }, "price": 300, "seller": { "avatar_url": null, "display_name": "Jayden Collon", "id": "pfbid0k18cWpao4WmR78cmx1CL23UERiW9rwJXQ3xLJgMu1ktX7xtacBKxFb8EakqyUA9ul", "is_verified": null, "url": null, "username": null }, "shipping": { "fee": null, "is_offered": false }, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.84726-6/789581205_1093657659864910_5715105961279626720_n.jpg?stp=c0.87.526.526a_dst-jpg_p526x395_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7…", "title": "grey sofa/loveseat,couch with hidden compartments and can oull out to make longer", "type": "listing", "unknown_fields": [ "attributes", "media" ], "url": "https://www.facebook.com/marketplace/item/1074423591747937/" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 1593, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_listingsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Listings by keyword and location, with prices", "tags": [ "Facebook Marketplace" ], "x-socialtap-endpoint": "facebook.search_listings", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 10800, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Marketplace's Suggested order", "orders": { "nearest": "the closest to the place first", "newest": "the latest listed first, by the day: later pages can hold newer listings", "price_asc": "the lowest price first", "price_desc": "the highest price first", "relevance": "Marketplace's Suggested order" }, "page_max": 30, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" }, { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "page" } ], "unit": "page" }, "x-socialtap-resource": "product", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_places": { "get": { "description": "Returns the places Facebook Marketplace's location picker offers for a city, neighborhood or postal code, with the ID a Marketplace search takes. Each place has its name, coordinates, the city and postal code Facebook gives it, the area line the picker shows, whether Facebook calls it a city, and its check-in count. Filter to one country, or rank around coordinates to tell places of the same name apart.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Place` items (the shared schema, the same on every platform), most relevant first, as Marketplace's location picker ranks them. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_places/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_places/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_places/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_places/" }, "operationId": "facebook.search_places.list", "parameters": [ { "description": "What to look for, as typed into Marketplace's location picker: a city, neighborhood or postal code. Matched by name, case-insensitive; a place ID matches nothing.", "example": "Austin", "in": "query", "name": "query", "required": true, "schema": { "description": "What to look for, as typed into Marketplace's location picker: a city, neighborhood or postal code. Matched by name, case-insensitive; a place ID matches nothing.", "examples": [ "Austin" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only places in this country: an ISO 3166-1 alpha-2 code such as US. Every country when omitted; Facebook ignores a code it does not know.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only places in this country: an ISO 3166-1 alpha-2 code such as US. Every country when omitted; Facebook ignores a code it does not know.", "examples": [ "US" ], "type": "string" } }, { "description": "Latitude (WGS 84 degrees) to rank places near, with lng: of two Springfields, the closer comes first.", "example": "42.1", "in": "query", "name": "lat", "schema": { "description": "Latitude (WGS 84 degrees) to rank places near, with lng: of two Springfields, the closer comes first.", "examples": [ 42.1 ], "format": "double", "maximum": 90, "minimum": -90, "type": "number" } }, { "description": "Longitude (WGS 84 degrees) to rank places near, with lat.", "example": "-72.59", "in": "query", "name": "lng", "schema": { "description": "Longitude (WGS 84 degrees) to rank places near, with lat.", "examples": [ -72.59 ], "format": "double", "maximum": 180, "minimum": -180, "type": "number" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 10, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "account": null, "address": "Austin, IL", "approximate_fields": [ "platform_specific.facebook.checkin_count" ], "category": null, "city": "Chicago", "country_code": null, "description": null, "id": "108120015875983", "images": [], "latitude": 41.894086, "longitude": -87.763202, "metrics": { "image_count": null, "post_count": null, "review_count": null }, "name": "Austin", "phone": null, "platform": "facebook", "platform_specific": { "facebook": { "checkin_count": 25676 } }, "postal_code": "60644-1112", "price_range": null, "type": "area", "unknown_fields": [ "images" ], "url": "https://www.facebook.com/marketplace/108120015875983/", "website_url": null }, { "account": null, "address": "Austin, GA", "approximate_fields": [ "platform_specific.facebook.checkin_count" ], "category": null, "city": "Marietta", "country_code": null, "description": null, "id": "312180006098697", "images": [], "latitude": 33.955058, "longitude": -84.529634, "metrics": { "image_count": null, "post_count": null, "review_count": null }, "name": "Austin", "phone": null, "platform": "facebook", "platform_specific": { "facebook": { "checkin_count": 162 } }, "postal_code": "30060-1862", "price_range": null, "type": "area", "unknown_fields": [ "images" ], "url": "https://www.facebook.com/marketplace/312180006098697/", "website_url": null }, { "account": null, "address": null, "approximate_fields": [], "category": "City", "city": "Austin", "country_code": null, "description": null, "id": "106224666074625", "images": [], "latitude": 30.2677, "longitude": -97.7475, "metrics": { "image_count": null, "post_count": null, "review_count": null }, "name": "Austin, Texas", "phone": null, "platform": "facebook", "platform_specific": { "facebook": { "checkin_count": null } }, "postal_code": "78701", "price_range": null, "type": "area", "unknown_fields": [ "images" ], "url": "https://www.facebook.com/marketplace/106224666074625/", "website_url": null } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 297, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "platform_limit" } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_placesResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Location IDs for a city or postal code", "tags": [ "Facebook Marketplace" ], "x-socialtap-endpoint": "facebook.search_places", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "most relevant first, as Marketplace's location picker ranks them", "page_max": 10, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "place", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_posts": { "get": { "description": "Returns public Facebook posts that a web search finds for your keywords, with each post's link, account, date and opening text. Add fill=true to get each post's full, live Facebook record in the same response: post ID, text, media, exact reaction, comment and share counts and publish time. media=video finds videos instead. Page through the results with the cursor.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Web result` items (the shared schema, the same on every platform), the search engine's ranking (most relevant first). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit + 1 per result filled in per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_posts/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_posts/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_posts/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_posts/" }, "operationId": "facebook.search_posts.list", "parameters": [ { "description": "Words to find Facebook posts by, as a web search reads them: a topic, a product, a brand or a place (coffee roaster, electric vehicle charging, \"nancy grace roman\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and an operator that narrows to a page's title, text or link (intitle:, inurl:, intext:, url:) reads as its words.", "example": "coffee roaster", "in": "query", "name": "query", "required": true, "schema": { "description": "Words to find Facebook posts by, as a web search reads them: a topic, a product, a brand or a place (coffee roaster, electric vehicle charging, \"nancy grace roman\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and an operator that narrows to a page's title, text or link (intitle:, inurl:, intext:, url:) reads as its words.", "examples": [ "coffee roaster" ], "maxLength": 200, "type": "string" } }, { "description": "video: only the videos of Pages and profiles (facebook.com//videos/…), found the same way, so fill=true gets each video's post record with its views. All posts when omitted.", "example": "", "in": "query", "name": "media", "schema": { "description": "video: only the videos of Pages and profiles (facebook.com//videos/…), found the same way, so fill=true gets each video's post record with its views. All posts when omitted.", "enum": [ "video" ], "type": "string" } }, { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "example": "true", "in": "query", "name": "fill", "schema": { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "enum": [ "true", "false" ], "examples": [ "true" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "example": "BR", "in": "query", "name": "country", "schema": { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "examples": [ "BR" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/arcaderoasters/posts/welcome-to-the-roasting-part-of-arcade-coffee-roasters-all-our-coffee-is-freshly/877760954366326/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 0, "post": { "author": { "avatar_url": null, "display_name": "Arcade Coffee Roasters", "id": null, "is_verified": null, "url": "https://www.facebook.com/arcaderoasters", "username": "arcaderoasters" }, "id": null, "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "published_at": null, "text": null, "thumbnail_url": null, "title": null, "url": "https://www.facebook.com/arcaderoasters/posts/877760954366326" }, "profile": null, "snippet": "Arcade Coffee Roasters. 2,569 likes · 25 talking about this · 79 were here. Arcade Coffee Roasters is a Specialty Coffee Company located in the Inland Empire.", "sound": null, "title": "Arcade Coffee Roasters | Facebook", "type": "post", "unknown_fields": [], "url": "https://www.facebook.com/arcaderoasters/posts/877760954366326" }, { "approximate_fields": [], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/reddoorroaster/posts/740482067782696/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 1, "post": { "author": { "avatar_url": null, "display_name": "Red Door Coffee Roaster", "id": null, "is_verified": null, "url": "https://www.facebook.com/reddoorroaster", "username": "reddoorroaster" }, "id": null, "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "published_at": null, "text": null, "thumbnail_url": null, "title": null, "url": "https://www.facebook.com/reddoorroaster/posts/740482067782696" }, "profile": null, "snippet": "Red Door Coffee Roaster, Center Valley. 624 likes · 1 talking about this · 19 were here. Micro-roaster of fine coffees � NEW! Coffee Shop: Located at the Trolley Barn Public Market 116 E Broad...", "sound": null, "title": "Red Door Coffee Roaster | Center Valley PA | Facebook", "type": "post", "unknown_fields": [], "url": "https://www.facebook.com/reddoorroaster/posts/740482067782696" }, { "approximate_fields": [], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/DalianAmazonCoffeeRoaster/posts/dl-a721-sbb-1kg-coffee-roaster/973590226143545/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": null, "like_count": null, "place": null, "talking_about_count": null, "were_here_count": null } }, "position": 2, "post": { "author": { "avatar_url": null, "display_name": "Coffee Roaster", "id": null, "is_verified": null, "url": "https://www.facebook.com/DalianAmazonCoffeeRoaster", "username": "DalianAmazonCoffeeRoaster" }, "id": null, "metrics": { "comment_count": null, "like_count": null, "quote_count": null, "repost_count": null, "save_count": null, "share_count": null, "view_count": null }, "published_at": null, "text": null, "thumbnail_url": null, "title": null, "url": "https://www.facebook.com/DalianAmazonCoffeeRoaster/posts/973590226143545" }, "profile": null, "snippet": "Coffee Roaster, Dalian. 326 likes. Dalian Amazon Coffee Co.,Ltd, a professional Coffee Roaster 's manufacturer, Nine years' Alibaba Gol", "sound": null, "title": "Coffee Roaster | Dalian | Facebook", "type": "post", "unknown_fields": [], "url": "https://www.facebook.com/DalianAmazonCoffeeRoaster/posts/973590226143545" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "web_search", "is_cached": false, "credits_charged": 1, "latency_ms": 1131, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_postsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Public posts and videos by keyword", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.search_posts", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the search engine's ranking (most relevant first)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 51, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit + 1 per result filled in", "max": 51, "per": 1, "source": "", "unit": "filled_result", "unit_max": 50 } ], "unit": "page" }, "x-socialtap-resource": "web_result", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/search_profiles": { "get": { "description": "Returns the Facebook Pages and people a web search finds for a name, a business type or a place, with each one's username and profile link. Each also has what the search index shows of it: name, a Page's about text, followers, likes, check-ins and city. Add fill=true for each account's full, live Facebook profile in the same response: ID, exact counts, verified badge, picture and contact details. account_type narrows the results to Pages or to people.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Web result` items (the shared schema, the same on every platform), the search engine's ranking (most relevant first). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit + 1 per result filled in per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/search_profiles/ (Markdown: https://socialtap.dev/docs/reference/facebook/search_profiles/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/search_profiles/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/search_profiles/" }, "operationId": "facebook.search_profiles.list", "parameters": [ { "description": "Words to find Facebook accounts by, as a web search reads them: a Page's or a person's name, a business type and a place (coffee roaster, yoga studio austin, john smith, \"national geographic\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and intitle:, inurl: and intext: count as plain words.", "example": "coffee roaster", "in": "query", "name": "query", "required": true, "schema": { "description": "Words to find Facebook accounts by, as a web search reads them: a Page's or a person's name, a business type and a place (coffee roaster, yoga studio austin, john smith, \"national geographic\"). Quotes keep a phrase together and a leading - leaves a word out; site: is set by the endpoint, and intitle:, inurl: and intext: count as plain words.", "examples": [ "coffee roaster" ], "maxLength": 200, "type": "string" } }, { "description": "Only accounts of this kind: page (a Page, or a person in professional mode, as Facebook describes both alike) or person. Both when omitted, which finds mostly Pages: use person to find people.", "example": "person", "in": "query", "name": "account_type", "schema": { "description": "Only accounts of this kind: page (a Page, or a person in professional mode, as Facebook describes both alike) or person. Both when omitted, which finds mostly Pages: use person to find people.", "enum": [ "page", "person" ], "examples": [ "person" ], "type": "string" } }, { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "example": "true", "in": "query", "name": "fill", "schema": { "description": "true also fetches each result's item from the platform: its full, current record in details (exact counts, its ID), as the platform's own endpoint for that kind returns it. Priced per result filled; a result the platform no longer serves stays unfilled and costs nothing more.", "enum": [ "true", "false" ], "examples": [ "true" ], "type": "string" } }, { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "example": "BR", "in": "query", "name": "country", "schema": { "description": "Favor this country's results: the search engine ranks the pages for it, and pages from elsewhere still appear. Without it, the search engine's ranking for the US. One of AR, AT, AU, BE, BR, CA, CH, CL, CN, DE, DK, ES, FI, FR, GB, GR, HK, ID, IN, IT, JP, KR, MX, MY, NL, NO, NZ, PH, PL, PT, RU, SA, SE, SG, TR, TW, US, ZA (case-insensitive): the countries search engines rank for.", "examples": [ "BR" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 50, "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 50, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [ "platform_specific.facebook.place", "platform_specific.facebook.talking_about_count", "platform_specific.facebook.were_here_count" ], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/coffeeroasterlnk/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": "page", "like_count": null, "place": "Lincoln", "talking_about_count": 159, "were_here_count": 449 } }, "position": 0, "post": null, "profile": { "avatar_url": null, "bio": "Serving fresh roasted coffee to Lincoln and beyond since 1995. 🖤 Locally owned. Community loved.", "display_name": "The Coffee Roaster", "id": null, "is_verified": null, "metrics": { "follower_count": 4063, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "url": "https://www.facebook.com/coffeeroasterlnk", "username": "coffeeroasterlnk" }, "snippet": "The Coffee Roaster, Lincoln. 4,063 followers · 159 talking about this · 449 were here. Serving fresh roasted coffee to Lincoln and beyond since 1995. 🖤 Locally owned. Community loved.", "sound": null, "title": "The Coffee Roaster | Lincoln NE | Facebook", "type": "profile", "unknown_fields": [], "url": "https://www.facebook.com/coffeeroasterlnk" }, { "approximate_fields": [ "platform_specific.facebook.place", "platform_specific.facebook.talking_about_count", "platform_specific.facebook.were_here_count" ], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/thecoffeeroastercy/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": "page", "like_count": null, "place": "Paralimni", "talking_about_count": 16, "were_here_count": 122 } }, "position": 1, "post": null, "profile": { "avatar_url": null, "bio": "The Coffee Roasters has been importing speciality coffee since 2007. In 2020 we started an artisan roastery", "display_name": "The Coffee Roaster", "id": null, "is_verified": null, "metrics": { "follower_count": 1225, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "url": "https://www.facebook.com/thecoffeeroastercy", "username": "thecoffeeroastercy" }, "snippet": "The Coffee Roaster, Paralimni. 1,225 followers · 16 talking about this · 122 were here. The Coffee Roasters has been importing speciality coffee since 2007. In 2020 we started an artisan roastery...", "sound": null, "title": "The Coffee Roaster | Paralimni | Facebook", "type": "profile", "unknown_fields": [], "url": "https://www.facebook.com/thecoffeeroastercy" }, { "approximate_fields": [ "platform_specific.facebook.talking_about_count", "platform_specific.facebook.were_here_count", "profile.metrics.follower_count" ], "community": null, "details": null, "hashtag": null, "matched_url": "https://www.facebook.com/thecoffeeroaster/", "place": null, "platform": "facebook", "platform_specific": { "facebook": { "account_type": "page", "like_count": null, "place": null, "talking_about_count": 39, "were_here_count": 63 } }, "position": 2, "post": null, "profile": { "avatar_url": null, "bio": "The Coffee Roaster Group operates TCR Cafe @ NUS AS8, TCR Academy and baking unit The Baker's Gallery", "display_name": "The Coffee Roaster", "id": null, "is_verified": null, "metrics": { "follower_count": 2865, "following_count": null, "post_count": null, "total_like_count": null, "total_view_count": null }, "url": "https://www.facebook.com/thecoffeeroaster", "username": "thecoffeeroaster" }, "snippet": "The Coffee Roaster. 2,865 followers · 39 talking about this · 63 were here. The Coffee Roaster Group operates TCR Cafe @ NUS AS8, TCR Academy and baking unit The Baker's Gallery", "sound": null, "title": "The Coffee Roaster (@thecoffeeroaster)", "type": "profile", "unknown_fields": [], "url": "https://www.facebook.com/thecoffeeroaster" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "web_search", "is_cached": false, "credits_charged": 1, "latency_ms": 1267, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/FacebookSearch_profilesResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Pages and people by name, niche or place", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.search_profiles", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the search engine's ranking (most relevant first)", "page_max": 50, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 51, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit + 1 per result filled in", "max": 51, "per": 1, "source": "", "unit": "filled_result", "unit_max": 50 } ], "unit": "page" }, "x-socialtap-resource": "web_result", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/facebook/transcript": { "get": { "description": "Returns the timed transcript of a public Facebook video or reel from its link or ID, from its captions or, when it has none, its audio. Captions are the uploaded track first, then Facebook's auto-generated one, and a video without either is transcribed with speech-to-text. Each segment has its start and end time, and text holds the whole transcript.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/facebook/transcript/ (Markdown: https://socialtap.dev/docs/reference/facebook/transcript/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/facebook/transcript/index.md)", "url": "https://socialtap.dev/docs/reference/facebook/transcript/" }, "operationId": "facebook.transcript.get", "parameters": [ { "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.", "example": "https://www.facebook.com/reel/1803909017420449/", "in": "query", "name": "url", "required": true, "schema": { "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.", "examples": [ "https://www.facebook.com/reel/1803909017420449" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "available_languages": [ "en-US" ], "duration_ms": 59861, "id": "1803909017420449", "is_auto_generated": false, "language": "en-US", "platform": "facebook", "platform_specific": {}, "segments": [ { "end_ms": 4000, "start_ms": 33, "text": "But the standard that we should continuously aspire to exceed," }, { "end_ms": 7166, "start_ms": 4000, "text": "which is why we are bringing that intensity, that discipline, that" }, { "end_ms": 11400, "start_ms": 7166, "text": "engineering ownership back to NASA, because great nations do not remain great" } ], "source": "captions", "text": "But the standard that we should continuously aspire to exceed, which is why we are bringing that intensity, that discipline, that engineering ownership back to NASA, because great nations do not remain great by being caretakers of history, but by continuously making history. We h…", "url": "https://www.facebook.com/reel/1803909017420449/" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "captions", "is_cached": false, "credits_charged": 1, "latency_ms": 713, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "video", "id": "1803909017420449", "url": "https://www.facebook.com/reel/1803909017420449/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/FacebookTranscriptResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "no_transcript": { "$ref": "#/components/examples/no_transcript" }, "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.\n\n`no_transcript`: The video or audio exists but has no transcript: no caption track and no speech to transcribe. Do not retry. If the platform offers other languages, try one with lang.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Timed transcript of a video or reel", "tags": [ "Facebook" ], "x-socialtap-endpoint": "facebook.transcript", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 122, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "captions" }, { "credits": 2, "label": "2 credits + 2 per started minute of media", "max": 122, "per": 2, "source": "asr", "unit": "media_minute", "unit_max": 60 } ], "unit": "request" }, "x-socialtap-resource": "transcript", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/ad": { "get": { "description": "Returns one ad from Google's public Ads Transparency Center by its link or creative ID, with its advertiser, creative and where and when it ran. You also get whether the advertiser verified its identity, who paid, the format, each variation's image (or a local text ad's headline, description and link), the first and last day shown, the countries and the topic Google labels it with. Ads shown in Europe and election ads add Google's impressions per country and per service and the kinds of audience criteria used. Election ads also add their spend range and age, gender and location targeting.\n\nReturns `{data, meta}`: `data` is a `Ad` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/ad/ (Markdown: https://socialtap.dev/docs/reference/google/ad/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/ad/index.md)", "url": "https://socialtap.dev/docs/reference/google/ad/" }, "operationId": "google.ad.get", "parameters": [ { "description": "The ad's Google Ads Transparency Center link (adstransparency.google.com/advertiser/AR…/creative/CR…), its old political ads report link, or its creative ID (CR…).", "example": "https://adstransparency.google.com/advertiser/AR07541154843046445057/creative/CR17778900238552006657?region=US&topic=political", "in": "query", "name": "url", "required": true, "schema": { "description": "The ad's Google Ads Transparency Center link (adstransparency.google.com/advertiser/AR…/creative/CR…), its old political ads report link, or its creative ID (CR…).", "examples": [ "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR07443539616616939521?region=US" ], "maxLength": 2048, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "advertiser": { "avatar_url": null, "display_name": "Republican National Committee", "id": "AR07541154843046445057", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR07541154843046445057", "username": null }, "approximate_fields": [ "platform_specific.google.regions[].first_shown_at", "platform_specific.google.regions[].last_shown_at" ], "audience_size": null, "country_codes": [ "US" ], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/18242167605449878359", "width": null } ], "title": null } ], "first_shown_at": "2026-06-05T21:52:15Z", "id": "CR17778900238552006657", "impressions": { "lower_bound": 500000, "upper_bound": 600000 }, "is_active": null, "is_political": true, "languages": [], "last_shown_at": "2026-06-24T19:04:54Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 20, "is_synthetic": false, "product_category": null, "regions": [ { "country_code": "US", "first_shown_at": "2026-06-05T00:00:00Z", "impressions": { "lower_bound": 500000, "upper_bound": 600000 }, "last_shown_at": "2026-06-24T00:00:00Z", "services": [] } ], "targeting": { "age_ranges": [ "25-34", "35-44", "45-54" ], "criteria": [], "excluded_age_ranges": [ "18-24" ], "excluded_genders": [], "excluded_locations": [ { "country_code": "SC", "criterion_id": "2690", "full_name": "Seychelles", "name": "Seychelles" }, { "country_code": "CV", "criterion_id": "2132", "full_name": "Cabo Verde", "name": "Cabo Verde" }, { "country_code": "CH", "criterion_id": "2756", "full_name": "Switzerland", "name": "Switzerland" } ], "genders": [ "male", "female", "unknown" ], "locations": [ { "country_code": "US", "criterion_id": "2840", "full_name": "United States", "name": "United States" } ] }, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": { "currency": "USD", "lower_bound": 5000, "upper_bound": 6000 }, "type": "image", "unknown_fields": [ "languages", "publisher_platforms" ], "url": "https://adstransparency.google.com/advertiser/AR07541154843046445057/creative/CR17778900238552006657" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 420, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "ad", "id": "CR17778900238552006657", "url": "https://adstransparency.google.com/advertiser/AR07541154843046445057/creative/CR17778900238552006657" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/GoogleAdResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Advertiser, creative and where and when it ran", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.ad", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/ads": { "get": { "description": "Returns the ads one advertiser ran on Google Search, YouTube, Maps, Play and Shopping, from the Ads Transparency Center, by advertiser ID or link. Each ad has its format, image, first and last day shown and days shown, with the advertiser's name and verification. Filter by country, format, service and dates, or list only election ads, which add their countries and Google's impressions and spend ranges and sort by impressions or spend. Ads come most recently shown first.\n\nReturns `{data, page, meta}`: `data` holds up to 40 `Ad` items (the shared schema, the same on every platform), last shown, most recent first with sort=newest (the default), last shown, least recent first (topic=political) with sort=oldest, most impressions first (topic=political) with sort=popular, most spent first (topic=political) with sort=spend. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/ads/ (Markdown: https://socialtap.dev/docs/reference/google/ads/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/ads/index.md)", "url": "https://socialtap.dev/docs/reference/google/ads/" }, "operationId": "google.ads.list", "parameters": [ { "description": "The advertiser: its Ads Transparency Center ID (AR…) or its page link (adstransparency.google.com/advertiser/AR…), in any case.", "example": "https://adstransparency.google.com/advertiser/AR01614014350098432001?region=US", "in": "query", "name": "handle", "required": true, "schema": { "description": "The advertiser: its Ads Transparency Center ID (AR…) or its page link (adstransparency.google.com/advertiser/AR…), in any case.", "examples": [ "AR01614014350098432001" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads shown in this country. All countries when omitted; required with topic=political.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads shown in this country. All countries when omitted; required with topic=political.", "examples": [ "US" ], "type": "string" } }, { "description": "political: only the advertiser's election ads (the center's Political ads view), with their impressions and spend; needs country. Default: all.", "example": "", "in": "query", "name": "topic", "schema": { "default": "all", "description": "political: only the advertiser's election ads (the center's Political ads view), with their impressions and spend; needs country. Default: all.", "enum": [ "all", "political" ], "type": "string" } }, { "description": "Only ads of this format. All formats when omitted.", "example": "", "in": "query", "name": "format", "schema": { "description": "Only ads of this format. All formats when omitted.", "enum": [ "text", "image", "video" ], "type": "string" } }, { "description": "Only ads shown on this Google service. All services when omitted.", "example": "", "in": "query", "name": "service", "schema": { "description": "Only ads shown on this Google service. All services when omitted.", "enum": [ "google_search", "google_maps", "google_play", "google_shopping", "youtube" ], "type": "string" } }, { "description": "Order of the results. newest: most recently shown first (the center's order). With topic=political also oldest (least recently shown first), popular (most impressions first) and spend (most spent first).", "example": "", "in": "query", "name": "sort", "schema": { "default": "newest", "description": "Order of the results. newest: most recently shown first (the center's order). With topic=political also oldest (least recently shown first), popular (most impressions first) and spend (most spent first).", "enum": [ "newest", "oldest", "popular", "spend" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they were shown during the window: an ad last shown (last_shown_at) before since is left out.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they were shown during the window: an ad last shown (last_shown_at) before since is left out.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they were shown during the window: an ad first shown (first_shown_at) at or after until is left out.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they were shown during the window: an ad first shown (first_shown_at) at or after until is left out.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 40, "in": "query", "name": "limit", "schema": { "default": 40, "maximum": 40, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [ "creatives" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/6465019125132301667", "width": null } ], "title": null } ], "first_shown_at": "2026-10-14T00:57:35Z", "id": "CR04589531176955281409", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T00:48:22Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 21, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "text", "unknown_fields": [ "country_codes", "languages", "platform_specific.google.regions" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR04589531176955281409" }, { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [ "creatives" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/8703432262747982451", "width": null } ], "title": null } ], "first_shown_at": "2024-08-27T09:13:20Z", "id": "CR10993845259498160129", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T00:45:16Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 485, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "text", "unknown_fields": [ "country_codes", "languages", "platform_specific.google.regions" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10993845259498160129" }, { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [], "audience_size": null, "country_codes": [], "creatives": [], "first_shown_at": "2026-08-11T21:42:51Z", "id": "CR06360865746699943937", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T00:37:13Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 84, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "image", "unknown_fields": [ "country_codes", "creatives", "languages" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR06360865746699943937" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 278, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "AR01614014350098432001", "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/GoogleAdsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Advertiser's ads by format, service and date", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.ads", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "free_filtered_pages": true, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "last shown, most recent first", "orders": { "newest": "last shown, most recent first", "oldest": "last shown, least recent first (topic=political)", "popular": "most impressions first (topic=political)", "spend": "most spent first (topic=political)" }, "page_max": 40, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/advertiser": { "get": { "description": "Returns one Google Ads Transparency Center advertiser by its ID or page link: name, legal name, country, verification and how many ads it has shown. The ad count is Google's range, overall or in one country, with when an ad was last shown. An election advertiser adds its election ad count, the countries it is verified for and its registrations with election regulators, such as a US FEC committee ID.\n\nReturns `{data, meta}`: `data` is a `Profile` object (Google calls it a advertiser) (the shared schema, the same on every platform). Null means unknown.\n\nIn Google's words: `metrics.post_count` is ads.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/advertiser/ (Markdown: https://socialtap.dev/docs/reference/google/advertiser/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/advertiser/index.md)", "url": "https://socialtap.dev/docs/reference/google/advertiser/" }, "operationId": "google.advertiser.get", "parameters": [ { "description": "The advertiser: its Ads Transparency Center ID (AR…) or its page link (adstransparency.google.com/advertiser/AR…), in any case.", "example": "https://adstransparency.google.com/advertiser/AR01614014350098432001?region=US", "in": "query", "name": "handle", "required": true, "schema": { "description": "The advertiser: its Ads Transparency Center ID (AR…) or its page link (adstransparency.google.com/advertiser/AR…), in any case.", "examples": [ "AR01614014350098432001" ], "maxLength": 2048, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Count only the ads shown in this country. Every country when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Count only the ads shown in this country. Every country when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [ "metrics.post_count" ], "avatar_url": null, "banner_url": null, "bio": null, "category": null, "country_code": "CA", "created_at": null, "display_name": "lululemon athletica canada inc.", "external_links": [], "id": "AR01614014350098432001", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": 10000, "total_like_count": null, "total_view_count": null }, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 10000, "upper_bound": 20000 }, "election": null, "is_election_advertiser": false, "last_shown_at": "2026-11-03T00:48:22Z", "legal_name": "lululemon athletica canada inc." } }, "type": "unknown", "unknown_fields": [ "external_links" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 220, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "profile", "id": "AR01614014350098432001", "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/GoogleAdvertiserResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Identity, verification and ad count", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.advertiser", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "request" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/search_ads": { "get": { "description": "Returns the ads that lead to a website, from every advertiser that runs them, in Google's Ads Transparency Center, by domain or any link to it. Each ad has its advertiser (ID, name and verification), format, image and first and last day shown, across Google Search, YouTube, Maps, Play and Shopping. Filter by country, format, service and dates, or list only election ads, which add their countries and Google's impressions and spend ranges and sort by impressions or spend. Ads come most recently shown first.\n\nReturns `{data, page, meta}`: `data` holds up to 40 `Ad` items (the shared schema, the same on every platform), last shown, most recent first with sort=newest (the default), last shown, least recent first (topic=political) with sort=oldest, most impressions first (topic=political) with sort=popular, most spent first (topic=political) with sort=spend. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/search_ads/ (Markdown: https://socialtap.dev/docs/reference/google/search_ads/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/search_ads/index.md)", "url": "https://socialtap.dev/docs/reference/google/search_ads/" }, "operationId": "google.search_ads.list", "parameters": [ { "description": "The website: its domain (lululemon.com), any link to it (https://www.lululemon.com/en-us/…), or an Ads Transparency Center domain search link (adstransparency.google.com/?domain=…). Google files ads under the registrable domain, so www. and subdomains search it (shop.lululemon.com is lululemon.com).", "example": "lululemon.com", "in": "query", "name": "query", "required": true, "schema": { "description": "The website: its domain (lululemon.com), any link to it (https://www.lululemon.com/en-us/…), or an Ads Transparency Center domain search link (adstransparency.google.com/?domain=…). Google files ads under the registrable domain, so www. and subdomains search it (shop.lululemon.com is lululemon.com).", "examples": [ "lululemon.com" ], "format": "domain", "maxLength": 500, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads shown in this country. All countries when omitted; required with topic=political.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads shown in this country. All countries when omitted; required with topic=political.", "examples": [ "US" ], "type": "string" } }, { "description": "political: only the election ads that lead to the website (the center's Political ads view), with their impressions and spend; needs country. Default: all.", "example": "", "in": "query", "name": "topic", "schema": { "default": "all", "description": "political: only the election ads that lead to the website (the center's Political ads view), with their impressions and spend; needs country. Default: all.", "enum": [ "all", "political" ], "type": "string" } }, { "description": "Only ads of this format. All formats when omitted.", "example": "", "in": "query", "name": "format", "schema": { "description": "Only ads of this format. All formats when omitted.", "enum": [ "text", "image", "video" ], "type": "string" } }, { "description": "Only ads shown on this Google service. All services when omitted.", "example": "", "in": "query", "name": "service", "schema": { "description": "Only ads shown on this Google service. All services when omitted.", "enum": [ "google_search", "google_maps", "google_play", "google_shopping", "youtube" ], "type": "string" } }, { "description": "Order of the results. newest: most recently shown first (the center's order). With topic=political also oldest (least recently shown first), popular (most impressions first) and spend (most spent first).", "example": "", "in": "query", "name": "sort", "schema": { "default": "newest", "description": "Order of the results. newest: most recently shown first (the center's order). With topic=political also oldest (least recently shown first), popular (most impressions first) and spend (most spent first).", "enum": [ "newest", "oldest", "popular", "spend" ], "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they were shown during the window: an ad last shown (last_shown_at) before since is left out.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they were shown during the window: an ad last shown (last_shown_at) before since is left out.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they were shown during the window: an ad first shown (first_shown_at) at or after until is left out.", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they were shown during the window: an ad first shown (first_shown_at) at or after until is left out.", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 40, "in": "query", "name": "limit", "schema": { "default": 40, "maximum": 40, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [ "creatives" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/989267650108216441", "width": null } ], "title": null } ], "first_shown_at": "2026-10-16T07:13:50Z", "id": "CR01602111080165801985", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T01:13:20Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 18, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "text", "unknown_fields": [ "country_codes", "languages", "platform_specific.google.regions" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR01602111080165801985" }, { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [ "creatives" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/6465019125132301667", "width": null } ], "title": null } ], "first_shown_at": "2026-10-14T00:57:35Z", "id": "CR04589531176955281409", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T00:48:22Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 21, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "text", "unknown_fields": [ "country_codes", "languages", "platform_specific.google.regions" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR04589531176955281409" }, { "advertiser": { "avatar_url": null, "display_name": "lululemon athletica canada inc.", "id": "AR01614014350098432001", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001", "username": null }, "approximate_fields": [ "creatives" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": null, "cta_text": null, "link_description": null, "link_url": null, "media": [ { "alt_text": null, "duration_ms": null, "expires_at": null, "height": null, "thumbnail_url": null, "type": "image", "url": "https://tpc.googlesyndication.com/archive/simgad/8703432262747982451", "width": null } ], "title": null } ], "first_shown_at": "2024-08-27T09:13:20Z", "id": "CR10993845259498160129", "impressions": null, "is_active": null, "is_political": null, "languages": [], "last_shown_at": "2026-11-03T00:45:16Z", "paid_by": null, "platform": "google", "platform_specific": { "google": { "days_shown": 485, "is_synthetic": null, "product_category": null, "regions": [], "targeting": null, "topic": null } }, "publisher_platforms": [], "reach": null, "spend": null, "type": "text", "unknown_fields": [ "country_codes", "languages", "platform_specific.google.regions" ], "url": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10993845259498160129" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 281, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/GoogleSearch_adsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Ads that lead to a website, from any advertiser", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.search_ads", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "free_filtered_pages": true, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "last shown, most recent first", "orders": { "newest": "last shown, most recent first", "oldest": "last shown, least recent first (topic=political)", "popular": "most impressions first (topic=political)", "spend": "most spent first (topic=political)" }, "page_max": 40, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "ad", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/search_advertisers": { "get": { "description": "Returns the Google Ads Transparency Center advertisers whose name matches a query, every match rather than the search box's first ten. Each advertiser has its AR ID (the one its ads and page use), name, country, verification and ad count as Google's range. Filter to advertisers whose ads ran in one country, with their counts there, and sort by Google's order or most ads first.\n\nReturns `{data, page, meta}`: `data` holds up to 100 `Profile` items (Google calls it a advertiser) (the shared schema, the same on every platform), Google's order, as the center's search box lists the matches with sort=relevance (the default), most ads first, by the center's ad counts (the upper bound, then the lower), Google's order among equals with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\nIn Google's words: `metrics.post_count` is ads.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/search_advertisers/ (Markdown: https://socialtap.dev/docs/reference/google/search_advertisers/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/search_advertisers/index.md)", "url": "https://socialtap.dev/docs/reference/google/search_advertisers/" }, "operationId": "google.search_advertisers.list", "parameters": [ { "description": "An advertiser's name, or a part of it, as typed into the Ads Transparency Center's search box, in any language (nike, lululemon athletica, トヨタ). Case and punctuation do not matter.", "example": "lululemon", "in": "query", "name": "query", "required": true, "schema": { "description": "An advertiser's name, or a part of it, as typed into the Ads Transparency Center's search box, in any language (nike, lululemon athletica, トヨタ). Case and punctuation do not matter.", "examples": [ "lululemon" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only advertisers whose ads were shown in this country, with their ad counts there. Every country when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only advertisers whose ads were shown in this country, with their ad counts there. Every country when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Order of the results. relevance (default): Google's order, as the center's search box lists them. popular: most ads first, by Google's ad counts.", "example": "", "in": "query", "name": "sort", "schema": { "default": "relevance", "description": "Order of the results. relevance (default): Google's order, as the center's search box lists them. popular: most ads first, by Google's ad counts.", "enum": [ "relevance", "popular" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 100, "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "avatar_url": null, "banner_url": null, "bio": null, "category": null, "country_code": "MX", "created_at": null, "display_name": "LULULEMON MEXICO", "external_links": [], "id": "AR02903092099014459393", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": 16, "total_like_count": null, "total_view_count": null }, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 16, "upper_bound": 16 }, "election": null, "is_election_advertiser": null, "last_shown_at": null, "legal_name": null } }, "type": "unknown", "unknown_fields": [ "external_links" ], "url": "https://adstransparency.google.com/advertiser/AR02903092099014459393", "username": null }, { "approximate_fields": [ "metrics.post_count" ], "avatar_url": null, "banner_url": null, "bio": null, "category": null, "country_code": "HK", "created_at": null, "display_name": "lululemon HK Limited", "external_links": [], "id": "AR01382517811867287553", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": 4000, "total_like_count": null, "total_view_count": null }, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 4000, "upper_bound": 5000 }, "election": null, "is_election_advertiser": null, "last_shown_at": null, "legal_name": null } }, "type": "unknown", "unknown_fields": [ "external_links" ], "url": "https://adstransparency.google.com/advertiser/AR01382517811867287553", "username": null }, { "approximate_fields": [], "avatar_url": null, "banner_url": null, "bio": null, "category": null, "country_code": "QA", "created_at": null, "display_name": "LULULEMON ATHLETICA TRADING", "external_links": [], "id": "AR06362141867382931457", "is_private": null, "is_verified": true, "location": null, "metrics": { "follower_count": null, "following_count": null, "post_count": 55, "total_like_count": null, "total_view_count": null }, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 55, "upper_bound": 55 }, "election": null, "is_election_advertiser": null, "last_shown_at": null, "legal_name": null } }, "type": "unknown", "unknown_fields": [ "external_links" ], "url": "https://adstransparency.google.com/advertiser/AR06362141867382931457", "username": null } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 234, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": false, "next_cursor": null, "next_cursor_expires_at": null, "end_reason": "end" } } } }, "schema": { "$ref": "#/components/schemas/GoogleSearch_advertisersResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Advertisers by name, with IDs and ad counts", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.search_advertisers", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "Google's order, as the center's search box lists the matches", "orders": { "popular": "most ads first, by the center's ad counts (the upper bound, then the lower), Google's order among equals", "relevance": "Google's order, as the center's search box lists the matches" }, "page_max": 100, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "profile", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/google/search_suggestions": { "get": { "description": "Returns what the Google Ads Transparency Center search box suggests for a query, in its order: matching advertisers, then websites with ads. Each advertiser has its AR ID, name, country, verification badge and ad count as Google's range, and each website its bare domain, ready for the Google Ads Transparency Center Ads by Website API. Filter to one country, and page past what the box shows.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Suggestion` items (the shared schema, the same on every platform), the center's search box order: on each page its advertisers, then its websites. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/google/search_suggestions/ (Markdown: https://socialtap.dev/docs/reference/google/search_suggestions/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/google/search_suggestions/index.md)", "url": "https://socialtap.dev/docs/reference/google/search_suggestions/" }, "operationId": "google.search_suggestions.list", "parameters": [ { "description": "What to search for, as typed into the Ads Transparency Center's search box: an advertiser's name or a website's domain, or a part of either, in any language (lululemon, nike.com, トヨタ). Case does not matter.", "example": "Lululemon", "in": "query", "name": "query", "required": true, "schema": { "description": "What to search for, as typed into the Ads Transparency Center's search box: an advertiser's name or a website's domain, or a part of either, in any language (lululemon, nike.com, トヨタ). Case does not matter.", "examples": [ "lululemon" ], "maxLength": 200, "type": "string" } }, { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only advertisers and websites whose ads were shown in this country, with the advertisers' ad counts there. Every country when omitted.", "example": "US", "in": "query", "name": "country", "schema": { "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only advertisers and websites whose ads were shown in this country, with the advertisers' ad counts there. Every country when omitted.", "examples": [ "US" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 20, "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 20, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "hashtag": null, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 16, "upper_bound": 16 }, "country_code": "MX" } }, "position": 0, "profile": { "avatar_url": null, "display_name": "LULULEMON MEXICO", "id": "AR02903092099014459393", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR02903092099014459393", "username": null }, "text": "LULULEMON MEXICO", "type": "profile", "unknown_fields": [], "url": "https://adstransparency.google.com/advertiser/AR02903092099014459393" }, { "approximate_fields": [], "hashtag": null, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 4000, "upper_bound": 5000 }, "country_code": "HK" } }, "position": 1, "profile": { "avatar_url": null, "display_name": "lululemon HK Limited", "id": "AR01382517811867287553", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR01382517811867287553", "username": null }, "text": "lululemon HK Limited", "type": "profile", "unknown_fields": [], "url": "https://adstransparency.google.com/advertiser/AR01382517811867287553" }, { "approximate_fields": [], "hashtag": null, "platform": "google", "platform_specific": { "google": { "ads": { "lower_bound": 55, "upper_bound": 55 }, "country_code": "QA" } }, "position": 2, "profile": { "avatar_url": null, "display_name": "LULULEMON ATHLETICA TRADING", "id": "AR06362141867382931457", "is_verified": true, "url": "https://adstransparency.google.com/advertiser/AR06362141867382931457", "username": null }, "text": "LULULEMON ATHLETICA TRADING", "type": "profile", "unknown_fields": [], "url": "https://adstransparency.google.com/advertiser/AR06362141867382931457" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "google", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 197, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/GoogleSearch_suggestionsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Advertisers and websites suggested for a query", "tags": [ "Google Ads Transparency Center" ], "x-socialtap-endpoint": "google.search_suggestions", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "the center's search box order: on each page its advertisers, then its websites", "page_max": 20, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "api" } ], "unit": "page" }, "x-socialtap-resource": "suggestion", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/instagram/comment": { "get": { "description": "Returns one public top-level comment on an Instagram post, reel or carousel, from its link or the post's link and comment_id. You get its text, exact like count, posting time, the GIF when it is one, whether the post's author wrote it, and the commenter's username, ID, picture and verified badge.\n\nReturns `{data, meta}`: `data` is a `Comment` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/instagram/comment/ (Markdown: https://socialtap.dev/docs/reference/instagram/comment/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/instagram/comment/index.md)", "url": "https://socialtap.dev/docs/reference/instagram/comment/" }, "operationId": "instagram.comment.get", "parameters": [ { "description": "The comment's permalink (instagram.com/p//c//, also on /reel/, /reels/, /tv/ and //p/ links, m.instagram.com and instagr.am, and a reply's /c//r//), or the post the comment is on: a post, reel or carousel link, a share link (instagram.com/share/…), a raw shortcode or a numeric media ID. Tracking params are ignored.", "example": "https://www.instagram.com/natgeo/p/DeuOR-CjKE9/", "in": "query", "name": "url", "required": true, "schema": { "description": "The comment's permalink (instagram.com/p//c//, also on /reel/, /reels/, /tv/ and //p/ links, m.instagram.com and instagr.am, and a reply's /c//r//), or the post the comment is on: a post, reel or carousel link, a share link (instagram.com/share/…), a raw shortcode or a numeric media ID. Tracking params are ignored.", "examples": [ "https://www.instagram.com/p/DeuOR-CjKE9/c/18172542484466705/" ], "maxLength": 2048, "type": "string" } }, { "description": "ID of the comment (the id of a comment from the comments endpoint). Required unless url is a comment's permalink; when both are given they must name the same comment.", "example": "18201877798382683", "in": "query", "name": "comment_id", "schema": { "description": "ID of the comment (the id of a comment from the comments endpoint). Required unless url is a comment's permalink; when both are given they must name the same comment.", "examples": [ "18172542484466705" ], "maxLength": 32, "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/487214600_1013796433961568_4617588958569444737_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=111&ig_cache_key=GAhOCh1gIlLgCpoDAIE1TFqx_BRAbkULAAAB1501500j-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCR…", "display_name": null, "id": "2736561256", "is_verified": true, "url": "https://www.instagram.com/tropiclifepr/", "username": "tropiclifepr" }, "edited_at": null, "id": "18201877798382683", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 1, "reply_count": null }, "parent_id": null, "platform": "instagram", "platform_specific": { "instagram": { "gif_url": null } }, "post_id": "DeuOR-CjKE9", "published_at": "2026-10-28T13:22:42Z", "text": "Puerto Rico 🇵🇷 🇵🇷 🇵🇷 🇵🇷", "unknown_fields": [], "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18201877798382683/" }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "instagram", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 629, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "18201877798382683", "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18201877798382683/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } } }, "schema": { "$ref": "#/components/schemas/InstagramCommentResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "Text, exact likes and author, from its link", "tags": [ "Instagram" ], "x-socialtap-endpoint": "instagram.comment", "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "request" }, "x-socialtap-resource": "comment", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/instagram/comments": { "get": { "description": "Returns the top-level comments on a public Instagram post, reel or carousel, newest first, a page at a time, from its link or shortcode. Each has its text, posting time, like count, whether the post's author wrote it, and the commenter's username, ID, picture and verified badge.\n\nReturns `{data, page, meta}`: `data` holds up to 24 `Comment` items (the shared schema, the same on every platform), newest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/instagram/comments/ (Markdown: https://socialtap.dev/docs/reference/instagram/comments/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/instagram/comments/index.md)", "url": "https://socialtap.dev/docs/reference/instagram/comments/" }, "operationId": "instagram.comments.list", "parameters": [ { "description": "Instagram post, reel or carousel URL (instagram.com/p/…, /reel/…, /reels/…, /tv/…, //p/…, m.instagram.com, instagr.am, instagram.com/share/… links), a raw shortcode or a numeric media ID (4012207125530714429, or with its _ suffix). Tracking params and img_index are ignored.", "example": "https://www.instagram.com/natgeo/p/DeuOR-CjKE9/", "in": "query", "name": "url", "required": true, "schema": { "description": "Instagram post, reel or carousel URL (instagram.com/p/…, /reel/…, /reels/…, /tv/…, //p/…, m.instagram.com, instagr.am, instagram.com/share/… links), a raw shortcode or a numeric media ID (4012207125530714429, or with its _ suffix). Tracking params and img_index are ignored.", "examples": [ "https://www.instagram.com/p/DeuOR-CjKE9/" ], "maxLength": 2048, "type": "string" } }, { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "example": "2026-10-01", "in": "query", "name": "since", "schema": { "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.", "examples": [ "2026-10-01" ], "type": "string" } }, { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "example": "2026-10-08", "in": "query", "name": "until", "schema": { "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).", "examples": [ "2026-10-08" ], "type": "string" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.", "example": 24, "in": "query", "name": "limit", "schema": { "default": 24, "maximum": 24, "minimum": 1, "type": "integer" } }, { "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": [ { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/659026685_17991098504947880_2935590941239143385_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid…", "display_name": null, "id": "58470243879", "is_verified": false, "url": "https://www.instagram.com/dovistravels/", "username": "dovistravels" }, "edited_at": null, "id": "18172542484466705", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 0, "reply_count": null }, "parent_id": null, "platform": "instagram", "platform_specific": { "instagram": { "gif_url": null } }, "post_id": "DeuOR-CjKE9", "published_at": "2026-11-02T11:55:16Z", "text": "So many incredible destinations 👏", "unknown_fields": [], "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18172542484466705/" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-19/881214533_18154592410588913_31986000253115770_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_gid=S…", "display_name": null, "id": "17581364912", "is_verified": false, "url": "https://www.instagram.com/monique.meier1506/", "username": "monique.meier1506" }, "edited_at": null, "id": "18137851468639974", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 0, "reply_count": null }, "parent_id": null, "platform": "instagram", "platform_specific": { "instagram": { "gif_url": null } }, "post_id": "DeuOR-CjKE9", "published_at": "2026-11-02T07:10:11Z", "text": "😍😍😍", "unknown_fields": [], "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18137851468639974/" }, { "approximate_fields": [], "author": { "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/642971158_18042956444535313_7384894640051603948_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid…", "display_name": null, "id": "46021735312", "is_verified": false, "url": "https://www.instagram.com/penguin.8656465/", "username": "penguin.8656465" }, "edited_at": null, "id": "18036657161665725", "is_by_post_author": false, "is_edited": null, "is_liked_by_author": null, "is_pinned": null, "metrics": { "like_count": 0, "reply_count": null }, "parent_id": null, "platform": "instagram", "platform_specific": { "instagram": { "gif_url": null } }, "post_id": "DeuOR-CjKE9", "published_at": "2026-11-02T01:39:04Z", "text": "Such stunning destinations! That scenery is truly breathtaking.", "unknown_fields": [], "url": "https://www.instagram.com/p/DeuOR-CjKE9/c/18036657161665725/" } ], "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "instagram", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 656, "fetched_at": "2026-10-25T12:00:00Z", "input": { "kind": "post", "id": "DeuOR-CjKE9", "url": "https://www.instagram.com/p/DeuOR-CjKE9/" }, "credits_remaining": 9999, "client_request_id": null, "warnings": [] }, "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null } } } }, "schema": { "$ref": "#/components/schemas/InstagramCommentsResponse" } } }, "description": "OK", "headers": { "age": { "$ref": "#/components/headers/age" }, "allow": { "$ref": "#/components/headers/allow" }, "deprecation": { "$ref": "#/components/headers/deprecation" }, "link": { "$ref": "#/components/headers/link" }, "ratelimit": { "$ref": "#/components/headers/ratelimit" }, "ratelimit-policy": { "$ref": "#/components/headers/ratelimit-policy" }, "sunset": { "$ref": "#/components/headers/sunset" }, "x-client-request-id": { "$ref": "#/components/headers/x-client-request-id" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "202": { "$ref": "#/components/responses/AsyncAccepted" }, "400": { "content": { "application/json": { "examples": { "invalid_cursor": { "$ref": "#/components/examples/invalid_cursor" }, "invalid_input": { "$ref": "#/components/examples/invalid_input" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`invalid_input`: A parameter is missing or malformed, or the link is not one this endpoint takes. Fix the parameter named in param as the message says. For a link of the wrong kind, call an endpoint listed in details.endpoints, when there is one.\n\n`invalid_cursor`: The cursor is malformed or expired, belongs to another endpoint, or came with other parameters than the request that returned it. Repeat the original request without cursor to start the list again.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "$ref": "#/components/examples/unauthorized" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`unauthorized`: The x-api-key header is missing, or its key is unknown or revoked. On the dashboard's routes: the session cookie is missing or expired. Send a valid API key in the x-api-key header. No key yet? A person gets one at details.signup_url; an AI agent follows details.agent_auth_url.", "headers": { "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "402": { "content": { "application/json": { "examples": { "insufficient_credits": { "$ref": "#/components/examples/insufficient_credits" }, "spend_limit_reached": { "$ref": "#/components/examples/spend_limit_reached" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`insufficient_credits`: The account does not have enough credits for this request. Have a person buy credits at details.purchase_url (or make them a checkout link with details.checkout), then repeat the request. Do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for this period. The account may still have credits. Wait until details.resets_at, or raise the key's spend limit (PATCH /v1/api_keys/{id}). Do not retry automatically.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "403": { "content": { "application/json": { "examples": { "forbidden": { "$ref": "#/components/examples/forbidden" }, "private_or_unavailable": { "$ref": "#/components/examples/private_or_unavailable" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`forbidden`: The API key is valid but may not make this request, and details.reason says why: the account is suspended, the key lacks the route's scope, waits for its owner to confirm it by email, has expired, or was used from an IP outside its allowlist, or a rotated key's previous secret was used for a call that needs the admin scope. A running job stops with it too when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item: a private item is private_or_unavailable, also 403, so branch on the code. Act on details.reason. suspended: contact support. scope: use a key with details.required_scope. previous_secret: use the new secret. key_pending: have the owner open the emailed link. key_expired or key_revoked: create a new key. ip_not_allowed: call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. Only public items can be fetched. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "404": { "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/not_found" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`not_found`: The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). Check the link or ID. Do not retry.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "$ref": "#/components/examples/rate_limited" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`rate_limited`: The account passed its runaway-protection ceiling: a high per-account limit that stops a broken client loop (plans have no rate limit). Requests without an API key (signup, the MCP server's tool listing and find_endpoint) are limited per IP address instead. It also stops an account whose failed requests in the last hour cost far more than its successful ones paid for: failures are free within a limit (the message says so), and successes raise it. Wait the seconds in the retry-after header, then retry. If your steady traffic needs more, ask support to raise the ceiling; without an API key, send one.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "500": { "content": { "application/json": { "examples": { "internal": { "$ref": "#/components/examples/internal" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`internal`: An unexpected error on SocialTap's side. Retry with backoff. If it keeps happening, contact support with the request_id.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "502": { "content": { "application/json": { "examples": { "upstream_error": { "$ref": "#/components/examples/upstream_error" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_error`: The platform failed, or answered with something we could not read. Retry with backoff. Failed requests are free.", "headers": { "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } }, "503": { "content": { "application/json": { "examples": { "overloaded": { "$ref": "#/components/examples/overloaded" }, "upstream_blocked": { "$ref": "#/components/examples/upstream_blocked" } }, "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "`upstream_blocked`: The platform refused every attempt, our own retries included. Retry later with backoff. Failed requests are free.\n\n`overloaded`: SocialTap was at capacity, or paused by its operators, and did not start the request. Nothing was fetched or charged. Retry after the seconds in the retry-after header. Failed requests are free.", "headers": { "retry-after": { "$ref": "#/components/headers/retry-after" }, "x-credits-charged": { "$ref": "#/components/headers/x-credits-charged" }, "x-credits-remaining": { "$ref": "#/components/headers/x-credits-remaining" }, "x-request-id": { "$ref": "#/components/headers/x-request-id" } } } }, "summary": "On a post or reel, newest first, with likes", "tags": [ "Instagram" ], "x-socialtap-endpoint": "instagram.comments", "x-socialtap-pagination": { "cursor_expires_at": "page.next_cursor_expires_at", "cursor_param": "cursor", "cursor_ttl_s": 86400, "has_more": "page.has_more", "limit_param": "limit", "next_cursor": "page.next_cursor", "order": "newest first", "page_max": 24, "style": "cursor" }, "x-socialtap-pricing": { "cache_hits_free": true, "failed_requests_free": true, "max_credits": 1, "min_credits": 1, "prices": [ { "credits": 1, "label": "1 credit", "max": 1, "per": 0, "source": "" } ], "unit": "page" }, "x-socialtap-resource": "comment", "x-socialtap-retry": { "failed_requests_free": true, "idempotent": true, "retry_after_codes": [ "rate_limited", "overloaded" ], "retry_after_header": "retry-after", "retryable_codes": [ "rate_limited", "upstream_blocked", "upstream_error", "overloaded", "internal" ] } } }, "/v1/instagram/embed": { "get": { "description": "Returns Instagram's own embed code for a public post, reel or profile, from its link. You get the HTML snippet, with or without the caption and the embed.js tag, at the width you choose, plus the iframe link it loads, the caption or profile title, the author and the thumbnail with its size.\n\nReturns `{data, meta}`: `data` is a `Embed` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://socialtap.dev/docs/reference/instagram/embed/ (Markdown: https://socialtap.dev/docs/reference/instagram/embed/index.md).", "externalDocs": { "description": "Endpoint docs (Markdown: https://socialtap.dev/docs/reference/instagram/embed/index.md)", "url": "https://socialtap.dev/docs/reference/instagram/embed/" }, "operationId": "instagram.embed.get", "parameters": [ { "description": "Instagram post, reel or profile link (instagram.com/p/…, /reel/…, /reels/…, /tv/…, //p/…, share links, m.instagram.com, instagr.am, instagram.com//) or a post's raw shortcode. A username needs its profile link: a bare string is read as a shortcode.", "example": "https://www.instagram.com/p/DeuOR-CjKE9/", "in": "query", "name": "url", "required": true, "schema": { "description": "Instagram post, reel or profile link (instagram.com/p/…, /reel/…, /reels/…, /tv/…, //p/…, share links, m.instagram.com, instagr.am, instagram.com//) or a post's raw shortcode. A username needs its profile link: a bare string is read as a shortcode.", "examples": [ "https://www.instagram.com/p/DeuOR-CjKE9/" ], "maxLength": 2048, "type": "string" } }, { "description": "Widest the embed may be laid out, in pixels (default and most: 658; a wider value is laid out at 658). Instagram's embeds are responsive below it.", "example": "", "in": "query", "name": "max_width", "schema": { "description": "Widest the embed may be laid out, in pixels (default and most: 658; a wider value is laid out at 658). Instagram's embeds are responsive below it.", "format": "int64", "minimum": 320, "type": "integer" } }, { "description": "Embed a post without its caption (Instagram's hidecaption). Profiles have none: ignored for a profile link.", "example": "", "in": "query", "name": "hide_caption", "schema": { "description": "Embed a post without its caption (Instagram's hidecaption). Profiles have none: ignored for a profile link.", "type": "boolean" } }, { "description": "Leave Instagram's embed.js script tag out of html, for a page that loads it once itself (then call window.instgrm.Embeds.process() after inserting the markup).", "example": "", "in": "query", "name": "omit_script", "schema": { "description": "Leave Instagram's embed.js script tag out of html, for a page that loads it once itself (then call window.instgrm.Embeds.process() after inserting the markup).", "type": "boolean" } }, { "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.", "in": "query", "name": "max_age", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.", "example": "respond-async", "in": "header", "name": "prefer", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "description": "Long arrays and strings are shortened for display; real responses are complete.", "summary": "A real response (recorded fixture)", "value": { "data": { "author": { "avatar_url": null, "display_name": "National Geographic", "id": "787132", "is_verified": null, "url": "https://www.instagram.com/natgeo/", "username": "natgeo" }, "embed_url": "https://www.instagram.com/p/DeuOR-CjKE9/embed/captioned/", "height": null, "html": "