Docs

Build with AI agents

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.

SocialTap is built to be integrated by AI coding agents such as Claude Code, Cursor or Codex. Every docs page is also Markdown, the whole documentation is one file, and the rules below are generated from the same catalog as the API, so they are always current.

Paste this into your agent

Give your agent this prompt to integrate SocialTap into your project. It sends the agent to the docs first and ends with a real request, so you see it working:

Prompt

Integrate the SocialTap API (https://staging.socialtap.dev) into this project.

1. Read https://staging.socialtap.dev/llms.txt first, then the Markdown docs page of the endpoint you need (linked there). Use only endpoints and parameters documented there.
2. Send the API key in the x-api-key header, read from the SOCIALTAP_API_KEY environment variable. Never hard-code it; if it is not set, ask me for it.
3. Branch on error.code: retry only the retryable codes the docs list, with backoff. On list endpoints follow page.next_cursor while page.has_more is true.
4. Verify with one real request before building on it, for example:

   curl -G 'https://staging.socialtap.dev/v1/youtube/transcript' \
     --data-urlencode 'url=dQw4w9WgXcQ' \
     -H "x-api-key: $SOCIALTAP_API_KEY"

   and check that data is not empty.
5. Tell me which endpoint you used, what meta.credits_charged was, and any error code you saw.

Instructions for AI agents

The same rules open llms.txt and the Agent Skill:

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.
No key yet? POST https://staging.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.
Pick an endpoint. Every endpoint is GET https://staging.socialtap.dev/v1/<platform>/<name> with query parameters; the endpoint list (all endpoints, or 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 "".
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.
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.
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/#<code> (error.doc_url). Failed requests cost nothing.
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.
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), so test your error handling too.
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.
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.
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.
Balance. GET /v1/account returns the balance, free.
MCP. Agents with MCP can use the remote server at https://staging.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, search, find_endpoint, get_account, create_job and get_job; see the agent guide.
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.

Which endpoint

Data	Request	Price	Docs
Facebook · Ads (beta)	`GET /v1/facebook/search_ads`	1 credit (api) per page	docs
Facebook · Transcript (beta)	`GET /v1/facebook/transcript`	1 credit (captions); 2 credits + 2 per started minute of media (asr) per request	docs
Instagram · Post (beta)	`GET /v1/instagram/post`	1 credit (page) per request	docs
Instagram · Transcript (beta)	`GET /v1/instagram/transcript`	1 credit (captions); 2 credits + 2 per started minute of media (asr) per request	docs
TikTok · Profile (beta)	`GET /v1/tiktok/profile`	1 credit (page) per request	docs
TikTok · Transcript (beta)	`GET /v1/tiktok/transcript`	1 credit (captions); 2 credits + 2 per started minute of media (asr) per request	docs
YouTube · Comments (beta)	`GET /v1/youtube/comments`	1 credit (api) per page	docs
YouTube · Transcript (beta)	`GET /v1/youtube/transcript`	1 credit (captions); 2 credits + 2 per started minute of media (asr) per request	docs

Docs for agents

llms.txt: the instructions above and a link to every page, as Markdown.
llms-full.txt: every guide and endpoint reference in one Markdown file.
Every page has a Markdown twin: add index.md to its URL, or request the page with Accept: text/markdown. Each page also has "Copy page as Markdown" and "Open in Claude / ChatGPT" buttons.
The API reference: every operation on one page, readable without JavaScript.
openapi.json: OpenAPI 3.1 with examples, the exact errors of each operation and x-socialtap-* extensions for pricing, pagination and retries.

Agent Skill

The skill is published at https://staging.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md and listed in the Agent Skills discovery index. It follows the open Agent Skills format, so any agent that loads skills can use it. For Claude Code, add it to a project:

Shell

mkdir -p .claude/skills/socialtap && curl -fsSL https://staging.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md -o .claude/skills/socialtap/SKILL.md

Show the generated SKILL.md

SKILL.md

---
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": "<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.socialtap.dev/docs/account/index.md).
3. **Pick an endpoint.** Every endpoint is `GET https://staging.socialtap.dev/v1/<platform>/<name>` 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/#<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.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 <key>` 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

MCP server

The remote MCP server at https://staging.socialtap.dev/mcp (Streamable HTTP) takes your API key as authorization: Bearer <key> or in the x-api-key header, and each tool call costs what the same API request costs. Set SOCIALTAP_API_KEY in your environment, then add the server:

Claude Code

claude mcp add --transport http socialtap https://staging.socialtap.dev/mcp --header "authorization: Bearer $SOCIALTAP_API_KEY"

Claude Code (.mcp.json)

{
  "mcpServers": {
    "socialtap": {
      "type": "http",
      "url": "https://staging.socialtap.dev/mcp",
      "headers": {
        "authorization": "Bearer ${SOCIALTAP_API_KEY}"
      }
    }
  }
}

Cursor (mcp.json)

{
  "mcpServers": {
    "socialtap": {
      "url": "https://staging.socialtap.dev/mcp",
      "headers": {
        "authorization": "Bearer ${env:SOCIALTAP_API_KEY}"
      }
    }
  }
}

Codex

codex mcp add socialtap --url https://staging.socialtap.dev/mcp --bearer-token-env-var SOCIALTAP_API_KEY

Codex (config.toml)

[mcp_servers.socialtap]
url = "https://staging.socialtap.dev/mcp"
bearer_token_env_var = "SOCIALTAP_API_KEY"

Its tools cover every endpoint, grouped by resource: pass platform and the link, handle or query. Results are concise JSON (detail: "full" returns every field), state credits_charged and credits_remaining, and are cut at about 20,000 tokens with a next_cursor to continue. Listing the tools and find_endpoint work without a key.

Tool	What it does
`get_post`	Get a public post on Instagram.
`get_profile`	Get a public profile on TikTok.
`get_transcript`	Get the transcript of a public video or post on Facebook, Instagram, TikTok or YouTube.
`list_comments`	List the comments of a public post on YouTube, one page per call.
`search`	Search public ads on Facebook by query.
`find_endpoint`	Find which SocialTap tool and endpoint serves a need ("TikTok comments", "YouTube transcript") or a link: returns the best matches with the tool and arguments to call, the price, the parameters and an example result.
`get_account`	Get the account, balance and calling key.
`create_job`	Run many requests (or one long one) as a job.
`get_job`	Get a job (free to poll).