--- name: socialtap description: "Fetch public social media data (ads, comments, posts, profiles and transcripts) from Facebook, Instagram, TikTok and YouTube with the SocialTap API: one API key, one JSON schema per kind of data, pay per successful request. Use when the user asks to get, scrape, download or analyze ads, comments, posts, profiles and transcripts from Facebook, Instagram, TikTok and YouTube, or to build code that does." metadata: homepage: "https://staging.socialtap.dev" docs: "https://staging.socialtap.dev/llms.txt" --- # SocialTap SocialTap returns public social media data (transcripts today; profiles, posts and comments next) from every major platform through one API key, one credit balance and one response schema per resource. ## How to use the API 1. **Authenticate.** Send the API key in the `x-api-key` header of every request to `https://staging.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.socialtap.dev/signup/); never invent one. 2. **No key yet?** `POST https://staging.socialtap.dev/v1/agent_signup` with `{"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.socialtap.dev/docs/account/index.md). 3. **Pick an endpoint.** Every endpoint is `GET https://staging.socialtap.dev/v1//` with query parameters; the endpoint list ([all endpoints](https://staging.socialtap.dev/apis/index.md), or [catalog.json](https://staging.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.socialtap.dev/docs/errors/#` (`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=` 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.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.socialtap.dev/mcp` (Streamable HTTP, the same API key as `authorization: Bearer ` or in the `x-api-key` header), with the tools `get_post`, `get_profile`, `get_transcript`, `list_comments`, `search`, `find_endpoint`, `get_account`, `create_job` and `get_job`; see [the agent guide](https://staging.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. ## Endpoints | Data | Request | Price | Docs | | --- | --- | --- | --- | | Facebook · Ads (beta) | `GET /v1/facebook/search_ads` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/facebook/search_ads/index.md) | | Facebook · Transcript (beta) | `GET /v1/facebook/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/facebook/transcript/index.md) | | Instagram · Post (beta) | `GET /v1/instagram/post` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/instagram/post/index.md) | | Instagram · Transcript (beta) | `GET /v1/instagram/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/instagram/transcript/index.md) | | TikTok · Profile (beta) | `GET /v1/tiktok/profile` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/tiktok/profile/index.md) | | TikTok · Transcript (beta) | `GET /v1/tiktok/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/tiktok/transcript/index.md) | | YouTube · Comments (beta) | `GET /v1/youtube/comments` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/youtube/comments/index.md) | | YouTube · Transcript (beta) | `GET /v1/youtube/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/youtube/transcript/index.md) | ## Example ```shell curl -G 'https://staging.socialtap.dev/v1/youtube/transcript' \ --data-urlencode 'url=dQw4w9WgXcQ' \ -H "x-api-key: $SOCIALTAP_API_KEY" ``` ## More - Docs index for agents: https://staging.socialtap.dev/llms.txt; everything in one file: https://staging.socialtap.dev/llms-full.txt - API reference: https://staging.socialtap.dev/docs/reference/index.md; OpenAPI: https://staging.socialtap.dev/openapi.json - Error codes: https://staging.socialtap.dev/docs/errors/index.md