# Introduction

Overview

One API key, one JSON schema per kind of data, every platform. Each operation has its own page: parameters, the response field by field, prices, errors and a real example.

> [!TIP]
>
> Building with an AI agent? Point it at [llms.txt](https://staging-fly.socialtap.dev/llms.txt), the [OpenAPI spec](https://staging-fly.socialtap.dev/openapi.json) or [catalog.json](https://staging-fly.socialtap.dev/catalog.json); every page here is also Markdown (the page menu, top right).

## 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](https://staging-fly.socialtap.dev/docs/test-mode/index.md) that answer recorded responses for free. [Authentication](https://staging-fly.socialtap.dev/docs/authentication/index.md)

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](https://staging-fly.socialtap.dev/resources/ad/index.md), [comments](https://staging-fly.socialtap.dev/resources/comment/index.md), [posts](https://staging-fly.socialtap.dev/resources/post/index.md), [profiles](https://staging-fly.socialtap.dev/resources/profile/index.md), [transcripts](https://staging-fly.socialtap.dev/resources/transcript/index.md).

### Facebook

- [GETFacebook Post API`/v1/facebook/post`](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md)
- [GETFacebook Ad Library Search API`/v1/facebook/search_ads`](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md)
- [GETFacebook Video Transcript API`/v1/facebook/transcript`](https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md)

### Instagram

- [GETInstagram Post API`/v1/instagram/post`](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md)
- [GETInstagram Posts API`/v1/instagram/posts`](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md)
- [GETInstagram Profile API`/v1/instagram/profile`](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md)
- [GETInstagram Reels Transcript API`/v1/instagram/transcript`](https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md)

### Rumble

- [GETRumble Comments API`/v1/rumble/comments`](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md)
- [GETRumble Video API`/v1/rumble/post`](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md)
- [GETRumble Channel Videos API`/v1/rumble/posts`](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md)
- [GETRumble Channel API`/v1/rumble/profile`](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md)
- [GETRumble Search API`/v1/rumble/search_posts`](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md)
- [GETRumble Transcript API`/v1/rumble/transcript`](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md)

### Threads

- [GETThreads Profile API`/v1/threads/profile`](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md)

### TikTok

- [GETTikTok Comments API`/v1/tiktok/comments`](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md)
- [GETTikTok Post API`/v1/tiktok/post`](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md)
- [GETTikTok Posts API`/v1/tiktok/posts`](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md)
- [GETTikTok Profile API`/v1/tiktok/profile`](https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md)
- [GETTikTok Transcript API`/v1/tiktok/transcript`](https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md)

### YouTube

- [GETYouTube Comments API`/v1/youtube/comments`](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md)
- [GETYouTube Video API`/v1/youtube/post`](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md)
- [GETYouTube Channel Videos API`/v1/youtube/posts`](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md)
- [GETYouTube Channel API`/v1/youtube/profile`](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md)
- [GETYouTube Transcript API`/v1/youtube/transcript`](https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md)

## 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](https://staging-fly.socialtap.dev/docs/errors/index.md)).

Error body:

```json
{
  "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.<br>One of `live`, `test` |

### List endpoints

Repeat the same request with `cursor` set to `page.next_cursor` while `page.has_more` is true ([pagination guide](https://staging-fly.socialtap.dev/docs/pagination/index.md)).

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `limit` optional | `integer`<br>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. | — |

| 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.<br>One of `end`, `platform_limit`, `max_pages` |

### Parameters every endpoint accepts

| Name | Type | Description | Example |
| --- | --- | --- | --- |
| `max_age` optional | `integer`<br>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. | — |

### 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`](https://staging-fly.socialtap.dev/docs/reference/status/get/index.md)

### Account

- [GETGet the account, balance and calling key`/v1/account`](https://staging-fly.socialtap.dev/docs/reference/account/get/index.md)
- [PATCHUpdate account settings`/v1/account`](https://staging-fly.socialtap.dev/docs/reference/account/update/index.md)
- [GETList credit transactions (the ledger)`/v1/credit_transactions`](https://staging-fly.socialtap.dev/docs/reference/account/credit-transactions-list/index.md)
- [GETUsage report: requests and credits over time`/v1/usage`](https://staging-fly.socialtap.dev/docs/reference/account/usage-list/index.md)

### Signup

- [POSTSign up as an agent: a test key now, live on confirm`/v1/agent_signup`](https://staging-fly.socialtap.dev/docs/reference/signup/agent-signup-create/index.md)
- [GETList sign-in and security events`/v1/security_events`](https://staging-fly.socialtap.dev/docs/reference/signup/security-events-list/index.md)
- [DELETESign out`/v1/session`](https://staging-fly.socialtap.dev/docs/reference/signup/session-delete/index.md)
- [GETGet the dashboard session`/v1/session`](https://staging-fly.socialtap.dev/docs/reference/signup/session-get/index.md)
- [POSTStart the dashboard: set up the account`/v1/session`](https://staging-fly.socialtap.dev/docs/reference/signup/session-create/index.md)

### API keys

- [GETList API keys`/v1/api_keys`](https://staging-fly.socialtap.dev/docs/reference/api-keys/list/index.md)
- [POSTCreate an API key`/v1/api_keys`](https://staging-fly.socialtap.dev/docs/reference/api-keys/create/index.md)
- [DELETERevoke an API key`/v1/api_keys/{id}`](https://staging-fly.socialtap.dev/docs/reference/api-keys/revoke/index.md)
- [GETGet an API key`/v1/api_keys/{id}`](https://staging-fly.socialtap.dev/docs/reference/api-keys/get/index.md)
- [PATCHUpdate an API key`/v1/api_keys/{id}`](https://staging-fly.socialtap.dev/docs/reference/api-keys/update/index.md)

### Billing

- [POSTBuy a credit pack (Stripe Checkout)`/v1/billing/checkout`](https://staging-fly.socialtap.dev/docs/reference/billing/checkout-create/index.md)

### Docs

- [POSTSend feedback on a docs page`/v1/docs_feedback`](https://staging-fly.socialtap.dev/docs/reference/docs/docs-feedback-create/index.md)

### Events

- [GETList events, newest first`/v1/events`](https://staging-fly.socialtap.dev/docs/reference/events/list/index.md)
- [GETGet an event`/v1/events/{id}`](https://staging-fly.socialtap.dev/docs/reference/events/get/index.md)
- [POSTDeliver an event again`/v1/events/{id}/redeliver`](https://staging-fly.socialtap.dev/docs/reference/events/redeliver/index.md)

### Jobs

- [GETList jobs, newest first`/v1/jobs`](https://staging-fly.socialtap.dev/docs/reference/jobs/list/index.md)
- [POSTRun many requests (or one long one) as a job`/v1/jobs`](https://staging-fly.socialtap.dev/docs/reference/jobs/create/index.md)
- [GETGet a job (free to poll)`/v1/jobs/{id}`](https://staging-fly.socialtap.dev/docs/reference/jobs/get/index.md)
- [POSTCancel a job`/v1/jobs/{id}/cancel`](https://staging-fly.socialtap.dev/docs/reference/jobs/cancel/index.md)
- [GETList a job's results as they complete`/v1/jobs/{id}/results`](https://staging-fly.socialtap.dev/docs/reference/jobs/results-list/index.md)
- [GETDownload every result of a job (JSON Lines)`/v1/jobs/{id}/results.jsonl`](https://staging-fly.socialtap.dev/docs/reference/jobs/results-download/index.md)

### Webhooks

- [GETList webhook endpoints`/v1/webhook_endpoints`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-list/index.md)
- [POSTRegister a webhook endpoint`/v1/webhook_endpoints`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-create/index.md)
- [DELETEDelete a webhook endpoint`/v1/webhook_endpoints/{id}`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-delete/index.md)
- [GETGet a webhook endpoint`/v1/webhook_endpoints/{id}`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-get/index.md)
- [PATCHUpdate a webhook endpoint`/v1/webhook_endpoints/{id}`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-update/index.md)
- [GETList an endpoint's delivery attempts`/v1/webhook_endpoints/{id}/deliveries`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-deliveries-list/index.md)
- [POSTRotate a webhook endpoint's signing secret`/v1/webhook_endpoints/{id}/rotate_secret`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-rotate-secret/index.md)
- [POSTSend a webhook.test event to an endpoint`/v1/webhook_endpoints/{id}/test`](https://staging-fly.socialtap.dev/docs/reference/webhooks/webhook-endpoints-test/index.md)

### 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).<br>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. |

---

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