# Requests

Docs

How every endpoint takes its input, the parameter names shared by all of them, and how unknown or mistyped parameters are answered.

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`](https://staging.socialtap.dev/docs/errors/index.md#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`). The links SocialTap recognizes:

| Platform | Kind of link | Example |
| --- | --- | --- |
| Facebook | video | `https://www.facebook.com/reel/1803909017420449` |
|  | hashtag | `https://www.facebook.com/hashtag/cooking` |
|  | post | `https://www.facebook.com/NASA/posts/pfbid02abc` |
|  | profile | `https://www.facebook.com/NASA` |
| Instagram | video | `https://www.instagram.com/reel/De1S3KpCXf0/` |
|  | post | `https://www.instagram.com/p/C0AbCdEfGhI/` |
|  | hashtag | `https://www.instagram.com/explore/tags/cooking/` |
|  | profile | `https://www.instagram.com/natgeo/` |
| TikTok | video | `https://www.tiktok.com/@scout2015/video/6718335390845095173` |
|  | post | `https://www.tiktok.com/@nasa/photo/7310000000000000000` |
|  | hashtag | `https://www.tiktok.com/tag/cooking` |
|  | profile | `https://www.tiktok.com/@scout2015` |
| YouTube | video | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
|  | video | `https://www.youtube.com/shorts/dQw4w9WgXcQ` |
|  | video | `https://youtu.be/dQw4w9WgXcQ` |
|  | playlist | `https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI` |
|  | hashtag | `https://www.youtube.com/hashtag/cooking` |
|  | profile | `https://www.youtube.com/@RickAstleyYT` |

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.

| Parameter | Type | Values | Meaning | Not |
| --- | --- | --- | --- | --- |
| `lang` | `string`<br>bcp47 | — | Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). | `hl`, `lang_code`, `language`, `language_code`, `locale` |
| `country` | `string`<br>iso3166-1-alpha-2 | — | Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). | `country_code`, `geo`, `gl`, `market`, `region` |
| `sort` | `string` | `relevance`, `newest`, `oldest`, `popular`<br>each endpoint offers a subset | Order of the results. | `order`, `order_by`, `orderby`, `sort_by`, `sortby` |
| `since` | `string`<br>date-time | — | 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.<br>Only on lists ordered by time. | `after`, `date_from`, `from`, `from_date`, `min_date`, `start`, `start_date`, `start_time` |
| `until` | `string`<br>date-time | — | Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).<br>Only on lists ordered by time. | `before`, `date_to`, `end`, `end_date`, `end_time`, `max_date`, `to`, `to_date` |

Every endpoint also accepts the common parameters (max_age, fields; see [Credits and caching](https://staging.socialtap.dev/docs/credits/index.md#param-max_age)), and list endpoints limit and cursor (see [Pagination](https://staging.socialtap.dev/docs/pagination/index.md)).

## Unknown parameters are rejected

A parameter the endpoint does not accept fails with [`invalid_input`](https://staging.socialtap.dev/docs/errors/index.md#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](https://staging.socialtap.dev/resources/index.md) (`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`](https://staging.socialtap.dev/docs/errors/index.md#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.

## Freshness

Responses are fetched fresh unless you opt into the cache with max_age (see [Credits and caching](https://staging.socialtap.dev/docs/credits/index.md#param-max_age)). The standard `cache-control: max-age=N` request header works too; when you send both, max_age wins. Values above the longest a result is kept are reduced to it.

## 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`](https://staging.socialtap.dev/docs/errors/index.md#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](https://staging.socialtap.dev/docs/authentication/index.md#rate-limits)). Every response states it in the standard IETF fields: `ratelimit-policy` is the ceiling in requests per second (`"account";q=1000;w=1`), and `ratelimit` what is left of it (`"account";r=997;t=1`: remaining requests, and seconds until the full ceiling is available again). Above it, requests fail with [`rate_limited`](https://staging.socialtap.dev/docs/errors/index.md#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`:

| Warning | Meaning |
| --- | --- |
| `deprecated_endpoint` | The endpoint is deprecated: it stops answering on its sunset date, after which it returns endpoint_retired. The message names the date and the replacement. |

---

[HTML version](https://staging.socialtap.dev/docs/requests/) · [Docs index for AI agents](https://staging.socialtap.dev/llms.txt) · [All docs in one file](https://staging.socialtap.dev/llms-full.txt)