Send your API key in the x-api-key header of every request:
curl -H "x-api-key: $SOCIALTAP_API_KEY" "https://staging-fly.socialtap.dev/v1/tiktok/profile?..."authorization: Bearer <key> works too (what most HTTP and MCP clients send); when both are sent,
x-api-key wins.
Keys, scopes and modes
Get a key on the signup page; AI agents can sign up through the API (see account and API keys). Keys starting with
st_live_ are live: real requests, billed. Keys starting with st_test_ are test keys: every
endpoint answers from recorded responses, free (see test mode). Each key has scopes (what it may call) and can
have a spend limit, an expiry and an IP allowlist; a key that may not make a request gets forbidden (HTTP
403) with the reason. Manage keys in the dashboard or with the API keys routes.
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). |
x-credits-charged and x-credits-remaining are on every response to an authenticated request,
successful or not: errors show a charge of 0 and your unchanged balance. A request rejected for its key has neither,
because there is no account to report on.
Missing or invalid keys
A request without a key, or with an unknown or revoked one, fails with unauthorized (HTTP
401), carries no credit headers and costs nothing.
Rate limits
Plans do not limit request rate: you pay for credits (see Pricing), and you can send requests as fast and as many in parallel as your balance covers.
Each account has a high safety ceiling on requests per second that only stops runaway clients, such as a retry loop
without backoff. Above it, requests fail with rate_limited (HTTP 429) and cost nothing;
wait the number of seconds in the retry-after header, then retry. If your sustained traffic needs more,
ask support and the ceiling is raised for your account.