API reference · SocialTap docs

Base URL

Every endpoint is served over HTTPS from one base URL:

Base URL

https://staging-fly.socialtap.dev

Authentication

Send your API key in the x-api-key header with every request; keys starting with st_test_ are test keys that answer recorded responses for free. Authentication

Header

x-api-key: <your key>

Endpoints

Data endpoints are GET requests with query parameters. Each returns {data, meta}, or {data, page, meta} for lists, where data follows one of 5 schemas, the same on every platform: ads, comments, posts, profiles, transcripts.

Facebook

Instagram

Rumble

Threads

GETThreads Profile API/v1/threads/profile

TikTok

YouTube

Conventions

data follows the resource's shared schema; null means unknown, never 0 or "". Errors are non-2xx responses with this body: branch on error.code, never on the message (error codes).

Error body

{
  "error": {
    "code": "<code>",
    "message": "…",
    "request_id": "…",
    "status": "…",
    "retryable": "…",
    "param": "…",
    "remediation": "…",
    "doc_url": "…",
    "details": "…",
    "charged": "…"
  }
}

The `meta` object

Field	Type	Description
`meta.request_id`	`string`	Unique request ID; include it when contacting support.
`meta.platform`	`string`	Platform ID of the endpoint (youtube, tiktok, …).
`meta.source`	`string`	Which upstream strategy produced the data.
`meta.is_cached`	`boolean`	True when served from the cache (free); see max_age.
`meta.credits_charged`	`integer`	Credits charged for this request (0 for errors and cache hits).
`meta.latency_ms`	`integer`	Time SocialTap spent on the request, in milliseconds.
`meta.fetched_at`	`string` (date-time)	When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).
`meta.input`	`object` or `null`	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.
`meta.input.kind`	`string`	What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.
`meta.input.id`	`string` or `null`	Platform-native ID of the item; null when it is only known after the fetch and the request failed.
`meta.input.url`	`string` or `null`	Canonical URL of the item; null when unknown.
`meta.credits_remaining`	`integer` or `null`	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.
`meta.client_request_id`	`string` or `null`	Your x-client-request-id, echoed; null when you sent none.
`meta.warnings`	`object[]`	Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.
`meta.warnings[].code`	`string`	Machine-readable warning code (see the warnings list). New codes may be added.
`meta.warnings[].message`	`string`	What to do about it.
`meta.warnings[].doc_url`	`string`	Where to read more (the changelog entry, the endpoint's docs).
`meta.warnings[].fields`	`string[]`	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.
`meta.mode`	`string` or `null`	live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added. One of `live`, `test`

request_idstring

Unique request ID; include it when contacting support.

platformstring

Platform ID of the endpoint (youtube, tiktok, …).

sourcestring

Which upstream strategy produced the data.

is_cachedboolean

True when served from the cache (free); see max_age.

credits_chargedinteger

Credits charged for this request (0 for errors and cache hits).

latency_msinteger

Time SocialTap spent on the request, in milliseconds.

fetched_atstring date-time

When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).

inputobjectnullable

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.

Show 3 child fields

kindstring

What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.

idstringnullable

Platform-native ID of the item; null when it is only known after the fetch and the request failed.

urlstringnullable

Canonical URL of the item; null when unknown.

credits_remainingintegernullable

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.

client_request_idstringnullable

Your x-client-request-id, echoed; null when you sent none.

warningsobject[]

Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.

Show 4 child fields

codestring

Machine-readable warning code (see the warnings list). New codes may be added.

messagestring

What to do about it.

doc_urlstring

Where to read more (the changelog entry, the endpoint's docs).

fieldsstring[]

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.

modestringnullable

live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.

One oflivetest

List endpoints

Repeat the same request with cursor set to page.next_cursor while page.has_more is true (pagination guide).

Name	Type	Description	Example
`limit` optional	`integer` min 1	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.	—
`cursor` optional	`string`	page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.	—

limitintegermin 1

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.

cursorstring

page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.

Field	Type	Description
`page.has_more`	`boolean`	True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.
`page.next_cursor`	`string` or `null`	Pass as cursor, with the same other parameters, to get the next page; null at the end.
`page.next_cursor_expires_at`	`string` (date-time) or `null`	When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.
`page.end_reason`	`string` or `null`	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. One of `end`, `platform_limit`, `max_pages`

has_moreboolean

True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.

next_cursorstringnullable

Pass as cursor, with the same other parameters, to get the next page; null at the end.

next_cursor_expires_atstring date-timenullable

When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.

end_reasonstringnullable

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.

One ofendplatform_limitmax_pages

Parameters every endpoint accepts

Name	Type	Description	Example
`max_age` optional	`integer` min 0	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.	—
`fields` optional	`string`	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.	—

max_ageintegermin 0

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.

fieldsstring

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.

Request headers

Header	Type	Description
`x-api-key`	`string`	Your API key.
`authorization`	`string`	Bearer <your API key>: the same key as x-api-key, in the form most HTTP and MCP clients send (x-api-key wins when both are sent).
`x-client-request-id`	`string`	Your own ID for the request (1–128 printable ASCII characters): echoed back and logged with ours, so support can find a request whose response never reached you.
`traceparent`	`string`	W3C Trace Context of your trace: recorded with the request (its trace ID) so a trace can be matched to ours; SocialTap starts its own trace.
`idempotency-key`	`string`	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.
`prefer`	`string`	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.
`cache-control`	`string`	max-age=N accepts a cached response up to N seconds old, like the max_age parameter (max_age wins when both are sent). Other directives are ignored.

Response headers

Header	Type	Description
`x-request-id`	`string`	Unique request ID; include it when contacting support.
`x-credits-charged`	`int`	Credits charged for this request (0 for errors and cache hits).
`x-credits-remaining`	`int`	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.
`retry-after`	`int`	Seconds to wait before retrying; sent only with the codes whose retry_after is set in the error codes list (never on credit errors).
`allow`	`string`	Methods the endpoint accepts (method_not_allowed only).
`age`	`int`	Seconds since the data was fetched (cache hits only).
`x-client-request-id`	`string`	Your x-client-request-id, echoed (also meta.client_request_id).
`ratelimit-policy`	`string`	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=<requests>;w=<seconds>. Not a plan limit.
`ratelimit`	`string`	What is left of the ceiling (IETF RateLimit field): "account";r=<requests that may be sent at once now>;t=<seconds until the bucket is full again>.
`deprecation`	`string`	RFC 9745: the endpoint is deprecated, as of this date (@<unix seconds>; may be in the future). Also in meta.warnings.
`sunset`	`string`	RFC 8594: when a deprecated endpoint stops answering (HTTP-date); from then on it answers endpoint_retired.
`link`	`string`	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.
`location`	`string`	On 202 answers: the job's URL (GET it, free, for its status).
`preference-applied`	`string`	RFC 7240: respond-async when Prefer: respond-async turned the request into a job (202).
`idempotent-replayed`	`bool`	true when the answer replays an earlier request with the same Idempotency-Key (it shows the resource's current state).

Account, billing, jobs and webhooks

The operations SocialTap serves itself. Their JSON answers are {data, meta} (plus page on cursor-paged lists); every one is free unless it says otherwise.

Status

GETLive health of every endpoint/status.json

Account

Signup

API keys

Billing

POSTBuy a credit pack (Stripe Checkout)/v1/billing/checkout

Docs

POSTSend feedback on a docs page/v1/docs_feedback

Events

Jobs

Webhooks

Their `meta`

Field	Type	Description
`meta.client_request_id`	`string` or `null`	Your x-client-request-id, echoed; null when you sent none.
`meta.credits_charged`	`integer`	Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).
`meta.credits_remaining`	`integer` or `null`	Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.
`meta.mode`	`string` or `null`	Mode of the credential that made the request: live, or test for a test key; null without one (signup). One of `live`, `test`
`meta.request_id`	`string`	Unique request ID; include it when contacting support.
`meta.warnings`	`object[]`	Things to act on that did not fail the request. [] when none.
`meta.warnings[].code`	`string`	Machine-readable warning code (see the warnings list). New codes may be added.
`meta.warnings[].doc_url`	`string`	Where to read more (the changelog entry, the endpoint's docs).
`meta.warnings[].fields?`	`string[]`	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.
`meta.warnings[].message`	`string`	What to do about it.

meta

Show 6 child fields

client_request_idstringnullable

Your x-client-request-id, echoed; null when you sent none.

credits_chargedinteger

Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).

credits_remainingintegernullable

Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.

modestringnullable

Mode of the credential that made the request: live, or test for a test key; null without one (signup).

One oflivetest

request_idstring

Unique request ID; include it when contacting support.

warningsobject[]

Things to act on that did not fail the request. [] when none.

Show 4 child fields

codestring

Machine-readable warning code (see the warnings list). New codes may be added.

doc_urlstring

Where to read more (the changelog entry, the endpoint's docs).

fields?string[]

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.

messagestring

What to do about it.

Base URL

Authentication

Endpoints

Facebook

Instagram

Rumble

Threads

TikTok

YouTube

Conventions

The meta object

List endpoints

Parameters every endpoint accepts

Request headers

Response headers

Account, billing, jobs and webhooks

Status

Account

Signup

API keys

Billing

Docs

Events

Jobs

Webhooks

Their meta

The `meta` object

Their `meta`