# Build with AI agents

Agents and accounts

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.

- [llms.txt](https://staging-fly.socialtap.dev/llms.txt): The instructions for agents and a link to every page, as Markdown.
- [MCP server](#mcp-server): Every endpoint and the docs as tools, in Claude Code, Cursor, VS Code or Codex.
- [Agent Skill](#agent-skill): The rules and the endpoint table, for agents that load skills.
- [OpenAPI](https://staging-fly.socialtap.dev/openapi.json): OpenAPI 3.1 with examples, errors per operation, prices and paging hints.

## 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-fly.socialtap.dev) into this project.

1. Read https://staging-fly.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-fly.socialtap.dev/v1/tiktok/profile' \
     --data-urlencode 'handle=https://www.tiktok.com/@nasa' \
     -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](https://staging-fly.socialtap.dev/llms.txt) and the Agent Skill:

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/](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.

## Which endpoint

| Data | Request | Price | Docs |
| --- | --- | --- | --- |
| Facebook · Post (beta) | `GET /v1/facebook/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md) |
| Facebook · Ads (beta) | `GET /v1/facebook/search_ads` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/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-fly.socialtap.dev/docs/reference/facebook/transcript/index.md) |
| Instagram · Post (beta) | `GET /v1/instagram/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md) |
| Instagram · Posts (beta) | `GET /v1/instagram/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md) |
| Instagram · Profile (beta) | `GET /v1/instagram/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/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-fly.socialtap.dev/docs/reference/instagram/transcript/index.md) |
| Rumble · Comments (beta) | `GET /v1/rumble/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md) |
| Rumble · Post (beta) | `GET /v1/rumble/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md) |
| Rumble · A Rumble channel's or user's videos, shorts and live streams (beta) | `GET /v1/rumble/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md) |
| Rumble · Profile (beta) | `GET /v1/rumble/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md) |
| Rumble · Search Rumble videos, live streams and shorts by keyword (beta) | `GET /v1/rumble/search_posts` | 1 credit (page) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md) |
| Rumble · Transcript (beta) | `GET /v1/rumble/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md) |
| Threads · Profile (beta) | `GET /v1/threads/profile` | 1 credit (api); 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md) |
| TikTok · Comments (beta) | `GET /v1/tiktok/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md) |
| TikTok · Post (beta) | `GET /v1/tiktok/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md) |
| TikTok · Posts (beta) | `GET /v1/tiktok/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md) |
| TikTok · Profile (beta) | `GET /v1/tiktok/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/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-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md) |
| YouTube · Comments (beta) | `GET /v1/youtube/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md) |
| YouTube · Post (beta) | `GET /v1/youtube/post` | 1 credit (api); 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md) |
| YouTube · Posts (beta) | `GET /v1/youtube/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md) |
| YouTube · Profile (beta) | `GET /v1/youtube/profile` | 1 credit per request | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/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-fly.socialtap.dev/docs/reference/youtube/transcript/index.md) |

## Docs for agents

- [llms.txt](https://staging-fly.socialtap.dev/llms.txt): the instructions above and a link to every page, as Markdown.
- [llms-full.txt](https://staging-fly.socialtap.dev/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](https://staging-fly.socialtap.dev/docs/reference/index.md): an overview of every operation, and a page per operation, readable without JavaScript.
- The MCP server's `search_docs` and `read_doc` tools: search these docs and read any page, free and without a key.
- [openapi.json](https://staging-fly.socialtap.dev/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-fly.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md`](https://staging-fly.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md) and listed in the [Agent Skills discovery index](https://staging-fly.socialtap.dev/.well-known/agent-skills/index.json). It follows the open [Agent Skills](https://agentskills.io/specification) format, so any agent that loads skills can use it. For Claude Code, add it to a project:

Shell:

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

**Show the generated SKILL.md**

SKILL.md:

````markdown
---
name: socialtap
description: "Fetch public social media data (ads, comments, posts, profiles and transcripts) from Facebook, Instagram, Rumble, Threads, 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, Rumble, Threads, TikTok and YouTube, or to build code that does."
metadata:
  homepage: "https://staging-fly.socialtap.dev"
  docs: "https://staging-fly.socialtap.dev/llms.txt"
---

# SocialTap

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.

## How to use the API

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.

## Endpoints

| Data | Request | Price | Docs |
| --- | --- | --- | --- |
| Facebook · Post (beta) | `GET /v1/facebook/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md) |
| Facebook · Ads (beta) | `GET /v1/facebook/search_ads` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/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-fly.socialtap.dev/docs/reference/facebook/transcript/index.md) |
| Instagram · Post (beta) | `GET /v1/instagram/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md) |
| Instagram · Posts (beta) | `GET /v1/instagram/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md) |
| Instagram · Profile (beta) | `GET /v1/instagram/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/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-fly.socialtap.dev/docs/reference/instagram/transcript/index.md) |
| Rumble · Comments (beta) | `GET /v1/rumble/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md) |
| Rumble · Post (beta) | `GET /v1/rumble/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md) |
| Rumble · A Rumble channel's or user's videos, shorts and live streams (beta) | `GET /v1/rumble/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md) |
| Rumble · Profile (beta) | `GET /v1/rumble/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md) |
| Rumble · Search Rumble videos, live streams and shorts by keyword (beta) | `GET /v1/rumble/search_posts` | 1 credit (page) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md) |
| Rumble · Transcript (beta) | `GET /v1/rumble/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md) |
| Threads · Profile (beta) | `GET /v1/threads/profile` | 1 credit (api); 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md) |
| TikTok · Comments (beta) | `GET /v1/tiktok/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md) |
| TikTok · Post (beta) | `GET /v1/tiktok/post` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md) |
| TikTok · Posts (beta) | `GET /v1/tiktok/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md) |
| TikTok · Profile (beta) | `GET /v1/tiktok/profile` | 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/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-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md) |
| YouTube · Comments (beta) | `GET /v1/youtube/comments` | 1 credit (api) per page | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md) |
| YouTube · Post (beta) | `GET /v1/youtube/post` | 1 credit (api); 1 credit (page) per request | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md) |
| YouTube · Posts (beta) | `GET /v1/youtube/posts` | 1 credit per page | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md) |
| YouTube · Profile (beta) | `GET /v1/youtube/profile` | 1 credit per request | [docs](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/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-fly.socialtap.dev/docs/reference/youtube/transcript/index.md) |

## Example

```shell
curl -G 'https://staging-fly.socialtap.dev/v1/tiktok/profile' \
  --data-urlencode 'handle=https://www.tiktok.com/@nasa' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

## More

- Docs index for agents: https://staging-fly.socialtap.dev/llms.txt; everything in one file: https://staging-fly.socialtap.dev/llms-full.txt
- API reference: https://staging-fly.socialtap.dev/docs/reference/index.md; OpenAPI: https://staging-fly.socialtap.dev/openapi.json
- Error codes: https://staging-fly.socialtap.dev/docs/errors/index.md
````

## MCP server

The remote MCP server at `https://staging-fly.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:

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

Claude Code (.mcp.json):

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

Cursor (mcp.json):

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

Codex:

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

Codex (config.toml):

```toml
[mcp_servers.socialtap]
url = "https://staging-fly.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 Facebook, Instagram, Rumble, TikTok or YouTube. |
| `get_profile` | Get a public profile on Instagram, Rumble, Threads, TikTok or YouTube. |
| `get_transcript` | Get the transcript of a public video or post on Facebook, Instagram, Rumble, TikTok or YouTube. |
| `list_comments` | List the comments of a public post on Rumble, TikTok or YouTube, one page per call. |
| `list_posts` | List the posts of a public profile on Instagram, Rumble, TikTok or YouTube, one page per call. |
| `search` | Search public ads or posts on Facebook or Rumble 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. |
| `search_docs` | Search the SocialTap docs (guides, the API reference, error codes, schemas, pricing) for a question or term: returns the best-matching sections with their page, a snippet and the path to read with read_doc. |
| `read_doc` | Read one SocialTap docs page as Markdown: a path from search_docs or llms.txt (/docs/pagination/), or a full docs URL. |
| `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). |
| `list_job_results` | List a job's results as they complete. |

---

[HTML version](https://staging-fly.socialtap.dev/docs/agents/) · [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)