Requests

Every endpoint follows the same conventions, so once you have called one you can call them all.

One identifying parameter

Each endpoint takes exactly one parameter that says what to fetch, named for what you have in hand:

• url for an item and an item's lists (a video's transcript, a post's comments): a canonical link, a short or share link, a mobile link or the platform's own ID.
• handle for a profile and a profile's lists: a profile link, @handle, a username or the platform's own ID.
• query for searches (endpoints named search_…).

Each endpoint page lists the kinds of link its parameter takes. A link of another kind, or from another platform, fails with invalid_input at no charge, and the error names the endpoint that takes it: error.details says what the link is (url_kind, url_platform) and which endpoints take it (endpoints). For a link that only points elsewhere (a share link, an embedded player), it also says where the link leads (resolved_url). A search's query takes words, never a link: a link pasted as the whole query fails the same way, naming the endpoint that takes it. An endpoint about a web page itself (how often a platform's users shared it) takes any web page's link, on that platform or off it, exactly as written: only a value that is no http(s):// link fails. The links SocialTap recognizes:

The response says what your input resolved to in meta.input: the kind of item, its ID on the platform and its canonical URL. A short link shows the item it pointed to, so you can check you fetched what you meant.

Shared parameters

Parameters that mean the same thing on every endpoint have one name, one format and one validation. An endpoint offers the ones that apply to it (its page lists them), and never under another name: the last column lists names other APIs use that are answered with a suggestion instead.

Every endpoint also accepts the common parameters (max_age, fields; see Credits and caching), and list endpoints limit and cursor (see Pagination).

Unknown parameters are rejected

A parameter the endpoint does not accept fails with invalid_input, free, before anything is fetched. A typo can't silently change nothing, and junk parameters can't make a request look new to the cache. The error names the parameter in error.param, the one you most likely meant in details.suggestion (username is answered with handle, lnag with lang), and every accepted parameter in details.accepted_params.

Selecting fields

fields returns only the fields you name, to cut payloads and tokens: comma-separated paths in the notation of the resource's schema (id,text, metrics.view_count, segments[].text; a parent path such as metrics keeps the whole object). It applies to the item, or to each item of a list page; page and meta always come back whole. Fields you leave out are absent, so null still only ever means unknown. An unknown path fails with invalid_input and lists every valid path in details.fields.

Selection happens after the cache: it changes neither the price nor whether a request is a cache hit, and requests that differ only in fields share one cached result.

Live or cached

Every request reads the platform live unless you opt into the cache with max_age (see Credits and caching). The standard cache-control: max-age=N request header works too; when you send both, max_age wins. A result is kept for at most 7 days, so a larger value counts as that.

Request IDs and tracing

Every response carries our x-request-id; quote it when you contact support. You can also send your own ID for the request in x-client-request-id (1 to 128 printable ASCII characters): it is echoed back in the same header and in meta.client_request_id, and logged with ours, so a request whose response never reached you can still be found. A malformed one fails with invalid_input before anything runs. A W3C traceparent is accepted too: its trace ID is recorded with the request so your trace can be matched to ours (SocialTap starts its own trace; a malformed traceparent is ignored).

Rate limit headers

Plans don't limit request rate, but every account has a high runaway-protection ceiling (see Rate limits). Every response states it in the standard IETF fields: ratelimit-policy is the ceiling as it is enforced: a bucket of q requests that refills in w seconds ("account";q=2000;w=2 for a ceiling of 1,000 requests per second, which admits a burst of 2,000 at once), and ratelimit what is left of it ("account";r=1997;t=1: requests you may send at once now, and seconds until the bucket is full again). Above it, requests fail with rate_limited and a retry-after.

Warnings

meta.warnings lists things to act on that did not fail the request, such as an endpoint that will be retired. It is always present, and empty when there is nothing to say. Each warning has a code, a message and a doc_url: