# SocialTap

> Public social media data. One API, one schema.

SocialTap returns public social media data from the major platforms, normalized into one JSON schema per resource. One API key, one credit balance, and you only pay for requests that succeed. Available now: ads on Facebook; comments on Rumble, TikTok and YouTube; posts on Facebook, Instagram, Rumble, TikTok and YouTube; profiles on Instagram, Rumble, Threads, TikTok and YouTube; transcripts on Facebook, Instagram, Rumble, TikTok and YouTube.

**Instructions for AI agents**

1. **Authenticate.** Send the API key in the `x-api-key` header of every request to `https://staging-fly.socialtap.dev`. Read it from an environment variable such as `SOCIALTAP_API_KEY`, never hard-code it, and call the API from server-side code only. Without a key, ask the user for one (keys: https://staging-fly.socialtap.dev/signup/); never invent one.
2. **No key yet?** `POST https://staging-fly.socialtap.dev/v1/agent_signup` with `{"email": "<your user's email>"}` returns a test key that works at once and a live key that stays pending until your user confirms the emailed link (it spends nothing until then). Ask the user for their email address first, build with the test key, and tell them to confirm. Details: [account and keys](https://staging-fly.socialtap.dev/docs/account/index.md).
3. **Pick an endpoint.** Every endpoint is `GET https://staging-fly.socialtap.dev/v1/<platform>/<name>` with query parameters; the endpoint list ([all endpoints](https://staging-fly.socialtap.dev/apis/index.md), or [catalog.json](https://staging-fly.socialtap.dev/catalog.json) for machines) gives each one's parameters and price per successful request. Read the endpoint's Markdown docs page before writing code, and don't rely on memory: endpoints and parameters change. Every endpoint of one kind of data (ads, comments, posts, profiles and transcripts) returns the same schema on every platform; `null` means unknown, never 0 or "".
4. **Read the response.** A success is HTTP 200 with `{data, meta}`: `meta.credits_charged` is what the request cost, `meta.credits_remaining` the balance left, `meta.request_id` identifies the request for support.
5. **Paginate.** List endpoints return `{data, page, meta}`. While `page.has_more` is true, repeat the same request with `cursor` set to `page.next_cursor`, keeping every other parameter. An empty page with `page.has_more` true is not the end. Cursors expire (`page.next_cursor_expires_at`): don't store them. Leave `limit` out: a smaller page costs the same.
6. **Handle errors.** Errors are non-2xx responses with `{"error": {code, message, request_id, status, retryable, param, remediation, doc_url, details, charged}}`. Branch on `error.code`, never on `error.message`. Retry only when `error.retryable` is true, with exponential backoff, first waiting the seconds in the `retry-after` header (also `error.details.retry_after`) when it is sent; otherwise do what `error.remediation` says. `insufficient_credits` means the balance is too low: stop and tell the user. Every code is documented at `https://staging-fly.socialtap.dev/docs/errors/#<code>` (`error.doc_url`). Failed requests cost nothing.
7. **Spend credits deliberately.** Each endpoint states its price per successful request (per page for lists); fetch only what the task needs. Add `max_age=<seconds>` to accept a stored response up to that old: cache hits are free.
8. **Test first.** Keys starting with `st_test_` are test keys: they answer every endpoint from recorded responses, free and deterministic. Build and test the integration with one, then switch to a live key. Magic inputs make an endpoint return any error code it can return ([test mode](https://staging-fly.socialtap.dev/docs/test-mode/index.md)), so test your error handling too.
9. **Many items or long lists.** Use background jobs, `POST /v1/jobs`, instead of a loop of single requests: one job runs many requests and walks whole lists.
10. **Notifications.** Instead of polling, register a webhook endpoint with `POST /v1/webhook_endpoints`: deliveries are signed (Standard Webhooks); verify the signature on the raw body before trusting one.
11. **Retry POSTs safely.** Send a new `idempotency-key` (a UUID) with every POST and reuse it when you retry: the work runs once, and a retry answers with the current state.
12. **Balance.** `GET /v1/account` returns the balance, free.
13. **MCP.** Agents with MCP can use the remote server at `https://staging-fly.socialtap.dev/mcp` (Streamable HTTP, the same API key as `authorization: Bearer <key>` or in the `x-api-key` header), with the tools `get_post`, `get_profile`, `get_transcript`, `list_comments`, `list_posts`, `search`, `find_endpoint`, `search_docs`, `read_doc`, `get_account`, `create_job`, `get_job` and `list_job_results`; see [the agent guide](https://staging-fly.socialtap.dev/docs/agents/index.md).
14. **Verify.** Before building on an endpoint, run its example request (on its docs page) and check that `data` is not empty. Report the endpoint, `meta.credits_charged` and any `error.code` you saw.

Every page below is Markdown (the `index.md` twin of each HTML page; HTML pages also answer `Accept: text/markdown`). All of them in one file: https://staging-fly.socialtap.dev/llms-full.txt.

## Docs

- [Quickstart](https://staging-fly.socialtap.dev/docs/index.md): Make your first request in a minute: one API key, one HTTP call, one JSON shape for every platform.
- [Authentication](https://staging-fly.socialtap.dev/docs/authentication/index.md): Authenticate every request with your API key in a header. One key works for every endpoint and platform.
- [Credits and caching](https://staging-fly.socialtap.dev/docs/credits/index.md): How requests are priced, reserved and charged, how to read what you paid, and how to get free cache hits.
- [Test mode](https://staging-fly.socialtap.dev/docs/test-mode/index.md): Test keys answer every endpoint from recorded responses, free and deterministic, and magic inputs trigger every error code, so you can build and test an integration without spending credits.
- [Requests](https://staging-fly.socialtap.dev/docs/requests/index.md): How every endpoint takes its input, the parameter names shared by all of them, and how unknown or mistyped parameters are answered.
- [Errors](https://staging-fly.socialtap.dev/docs/errors/index.md): Every error code, its HTTP status, whether a later retry can succeed, and what to do about it.
- [Pagination](https://staging-fly.socialtap.dev/docs/pagination/index.md): How list endpoints return items in pages, how to fetch the next page with a cursor, and how pages are priced.
- [Idempotency](https://staging-fly.socialtap.dev/docs/idempotency/index.md): Retry any POST safely with an Idempotency-Key: the same key and body never repeat the work, and a replay shows the current state.
- [Build with AI agents](https://staging-fly.socialtap.dev/docs/agents/index.md): Everything a coding agent needs to integrate the API correctly on the first try: a prompt to paste, the rules to follow, an Agent Skill and Markdown docs.
- [Account, API keys and signup](https://staging-fly.socialtap.dev/docs/account/index.md): Sign up, manage API keys (scopes, spend limits, expiry, IP allowlists, live and test modes), read usage and the credit ledger, and get balance alerts.
- [Jobs and batches](https://staging-fly.socialtap.dev/docs/jobs/index.md): Run many requests, or one long list walk, in the background: same prices and caches as single requests, with results you can stream, download or receive by webhook.
- [Webhooks](https://staging-fly.socialtap.dev/docs/webhooks/index.md): Receive signed notifications when jobs end or credits run low: Standard Webhooks signatures, retries for days, delivery logs and secret rotation.
- [Events](https://staging-fly.socialtap.dev/docs/events/index.md): Every event type, its data, and how to list and replay events: what webhooks deliver, kept for a month.
- [API reference](https://staging-fly.socialtap.dev/docs/reference/index.md): the conventions every operation shares and every operation by group; each operation's own page has its parameters, response schema, errors, prices and examples
- [Pricing](https://staging-fly.socialtap.dev/pricing/index.md): credit packs and the price of every endpoint, also as JSON at https://staging-fly.socialtap.dev/pricing.json
- [Changelog](https://staging-fly.socialtap.dev/docs/changelog/index.md): every change to the API, also a JSON Feed at https://staging-fly.socialtap.dev/changelog.json

## Facebook

- [Facebook Post API](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md): Facebook post, photo, video or reel with exact counts. `GET /v1/facebook/post`; params: url (required); price: 1 credit (page) per request; beta
- [Facebook Ad Library Search API](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md): Search Meta's Ad Library by keyword. `GET /v1/facebook/search_ads`; params: query (required), country, lang, status, since, until; list: pages of up to 10, most impressions first, cursors valid 1 hour; price: 1 credit (api) per page; beta
- [Facebook Video Transcript API](https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md): Facebook video transcript. `GET /v1/facebook/transcript`; params: url (required); price: 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request; beta

## Instagram

- [Instagram Post API](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md): Instagram post, reel or carousel with media and metrics. `GET /v1/instagram/post`; params: url (required); price: 1 credit (page) per request; beta
- [Instagram Posts API](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md): A public Instagram account's posts, reels and carousels. `GET /v1/instagram/posts`; params: handle (required), since, until; list: pages of up to 12, newest first, cursors valid 24 hours; price: 1 credit per page; beta
- [Instagram Profile API](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md): Public Instagram profile with exact follower counts. `GET /v1/instagram/profile`; params: handle (required); price: 1 credit (page) per request; beta
- [Instagram Reels Transcript API](https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md): Instagram reel / video transcript. `GET /v1/instagram/transcript`; params: url (required); price: 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request; beta

## Rumble

- [Rumble Comments API](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md): Comments and replies of a Rumble video. `GET /v1/rumble/comments`; params: url (required), sort, since, until; list: pages of up to 500, newest first, cursors valid 24 hours; price: 1 credit (api) per page; beta
- [Rumble Video API](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md): Rumble video, short or live stream with votes and files. `GET /v1/rumble/post`; params: url (required); price: 1 credit (page) per request; beta
- [Rumble Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md): A Rumble channel's or user's videos, shorts and live streams. `GET /v1/rumble/posts`; params: handle (required), tab, sort, since, until, duration; list: pages of up to 25, Rumble's upload order (newest uploads first, not strictly by published_at), cursors valid 1 hour; price: 1 credit per page; beta
- [Rumble Channel API](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md): Public Rumble channel or user profile and its counts. `GET /v1/rumble/profile`; params: handle (required); price: 1 credit (page) per request; beta
- [Rumble Search API](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md): Search Rumble videos, live streams and shorts by keyword. `GET /v1/rumble/search_posts`; params: query (required), tab, sort, since, until, duration; list: pages of up to 36, Rumble's relevance order, cursors valid 1 hour; price: 1 credit (page) per page; beta
- [Rumble Transcript API](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md): Rumble video transcript. `GET /v1/rumble/transcript`; params: url (required), lang; price: 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request; beta

## Threads

- [Threads Profile API](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md): Public Threads profile with exact follower counts. `GET /v1/threads/profile`; params: handle (required); price: 1 credit (api); 1 credit (page) per request; beta

## TikTok

- [TikTok Comments API](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md): Top-level comments of a TikTok video. `GET /v1/tiktok/comments`; params: url (required); list: pages of up to 50, TikTok's comment ranking (the order its app shows), cursors valid 24 hours; price: 1 credit (api) per page; beta
- [TikTok Post API](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md): TikTok video or photo post with media and metrics. `GET /v1/tiktok/post`; params: url (required); price: 1 credit (page) per request; beta
- [TikTok Posts API](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md): A public TikTok account's videos and photo posts. `GET /v1/tiktok/posts`; params: handle (required), since, until; list: pages of up to 15, newest first, cursors valid 24 hours; price: 1 credit per page; beta
- [TikTok Profile API](https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md): Public TikTok profile and follower counts. `GET /v1/tiktok/profile`; params: handle (required); price: 1 credit (page) per request; beta
- [TikTok Transcript API](https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md): TikTok video transcript. `GET /v1/tiktok/transcript`; params: url (required), lang; price: 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request; beta

## YouTube

- [YouTube Comments API](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md): Top-level comments of a YouTube video. `GET /v1/youtube/comments`; params: url (required), sort, since, until; list: pages of up to 20, newest first, cursors valid 1 hour; price: 1 credit (api) per page; beta
- [YouTube Video API](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md): YouTube video, short or live stream with exact counts. `GET /v1/youtube/post`; params: url (required); price: 1 credit (api); 1 credit (page) per request; beta
- [YouTube Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md): A YouTube channel's videos, shorts and live streams. `GET /v1/youtube/posts`; params: handle (required), tab, sort, since, until; list: pages of up to 48, newest first, cursors valid 1 hour; price: 1 credit per page; beta
- [YouTube Channel API](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md): Public YouTube channel profile and subscriber count. `GET /v1/youtube/profile`; params: handle (required); price: 1 credit per request; beta
- [YouTube Transcript API](https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md): YouTube video transcript. `GET /v1/youtube/transcript`; params: url (required), lang; price: 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request; beta

## Account, keys, jobs, webhooks and events

- [Every other operation](https://staging-fly.socialtap.dev/docs/reference/index.md#other): Status, Account, Signup, API keys, Billing, Docs, Events, Jobs, Webhooks; each links its own reference page

## Optional

- [Full docs](https://staging-fly.socialtap.dev/llms-full.txt): every docs page and endpoint reference in one Markdown file
- [Facebook endpoints](https://staging-fly.socialtap.dev/llms-facebook.txt): every Facebook endpoint's reference in one file
- [Instagram endpoints](https://staging-fly.socialtap.dev/llms-instagram.txt): every Instagram endpoint's reference in one file
- [Rumble endpoints](https://staging-fly.socialtap.dev/llms-rumble.txt): every Rumble endpoint's reference in one file
- [Threads endpoints](https://staging-fly.socialtap.dev/llms-threads.txt): every Threads endpoint's reference in one file
- [TikTok endpoints](https://staging-fly.socialtap.dev/llms-tiktok.txt): every TikTok endpoint's reference in one file
- [YouTube endpoints](https://staging-fly.socialtap.dev/llms-youtube.txt): every YouTube endpoint's reference in one file
- [Agent Skill](https://staging-fly.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md): SKILL.md for agents that load skills (https://staging-fly.socialtap.dev/.well-known/agent-skills/index.json lists it)
- [OpenAPI](https://staging-fly.socialtap.dev/openapi.json): OpenAPI 3.1 with examples, every error per operation and `x-socialtap-*` pricing, paging and retry hints
- [Catalog](https://staging-fly.socialtap.dev/catalog.json): machine-readable list of endpoints, params, prices and errors
- [Ad schema](https://staging-fly.socialtap.dev/resources/ad/index.md): A public ad library entry: advertiser, creatives, run dates, placements and, where disclosed, reach and spend ranges.
- [Comment schema](https://staging-fly.socialtap.dev/resources/comment/index.md): A public comment or reply on a post, with its author, thread position and like/reply counts.
- [Post schema](https://staging-fly.socialtap.dev/resources/post/index.md): A public post (video, reel, short, photo, carousel, tweet or text) with its author, media and engagement metrics.
- [Profile schema](https://staging-fly.socialtap.dev/resources/profile/index.md): A public account (creator, channel, page, company or community) with its bio, links and follower metrics.
- [Transcript schema](https://staging-fly.socialtap.dev/resources/transcript/index.md): Timed transcript of a public video: the platform's caption track, or speech-to-text on its audio when there is none.
- [Status](https://staging-fly.socialtap.dev/status/index.md): live endpoint health and measured latency and success rates