> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/use-cases/social-data-api-for-ai-agents>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/use-cases/social-data-api-for-ai-agents.mdx>

---

# Social data API for AI agents

Typed tools with stable JSON — MCP (OAuth) or REST function calling. POST /v1/ask routes exploration for free; pin typed GET paths in production.

Agent failures here are usually integration failures — invented field names, growing tool lists, wrong parameters. OpenAPI routes give narrow tools with `data.lookupStatus`, `meta.requestId`, and `meta.creditsCharged` on every lookup.

Fan-out is common. You need machine-actionable outcomes (`not_found` as HTTP 200, `503` for transient blips, `402` before charge) and billing that skips infrastructure failures.

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| POST | `/v1/ask` | Natural-language router — maps a plain-English question to a typed endpoint. Routing costs 0 credits; the nested lookup bills normally. Response includes `data.routedOperation` so the agent can switch to the explicit path next time. |
| GET | `/v1/tiktok/profiles/{handle}` | Example typed tool for function calling: fixed path, fixed response schema, one credit on `found`. Register this in your tool manifest instead of a generic “fetch URL” tool. |
| GET | `/v1/reddit/search` | Keyword search with `sortBy`, `timeframe`, and cursor pagination — useful when the agent needs threads, not just a single profile. |
| GET | `/v1/web/ask` | Q&A about one public URL. Use when the user pasted a link and the agent needs a summary, not a full platform lookup. |
| GET | `/v1/youtube/videos/transcript` | Transcript tool for RAG and summarization agents — `url` in, structured text out. Pair with MCP (`https://api.socialfetch.dev/mcp`) when prototyping in Cursor or Claude. |

## Workflow

1. **Point the agent at llms.txt first.** Add `https://www.socialfetch.dev/llms.txt` to your Cursor rules or system prompt. It lists recommended reading order, platform coverage, and links to Quickstart and Errors — so the model stops guessing endpoint shapes. Use `llms.json` when you need the full operation inventory for tool registration.
2. **Connect MCP or define function schemas.** In Cursor, add `https://api.socialfetch.dev/mcp` to `.cursor/mcp.json` and complete OAuth. In Claude Code: `claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp`. For custom runtimes, generate JSON Schema from the OpenAPI spec and register one function per route — not one mega “social API” tool with a free-text platform field.
3. **Prototype with POST /v1/ask, then pin typed routes.** Let the agent ask “how many TikTok followers does X have?” while exploring. The response tells you which operation was chosen (`data.routedOperation`). Once the workflow is stable, replace /v1/ask with the explicit GET path in your tool list — fewer routing surprises, same schema.
4. **Teach the loop how to read errors.** HTTP 200 with `lookupStatus: "not_found"` or `"private"` is a completed lookup, not a transport error — still billed, still valid data. Log `meta.requestId` on every response. Retry on `503 temporarily_unavailable` and `502 lookup_failed` (not charged). Stop and surface `402 insufficient_credits` to the user before the agent spins.
5. **Budget parallel tool calls against credits.** There is no published rate cap on paid routes — your prepaid balance is the ceiling. An agent that fires ten profile lookups in parallel is fine if you have ten credits. Pre-send validation errors (bad handle format, missing params) cost nothing. Concurrency is capped at 200 requests in flight per workspace; over that you get an uncharged 503 with Retry-After.
6. **Move from MCP exploration to production SDK.** MCP is for building: the agent inspects real JSON while you scaffold. Ship production code with `@socialfetch/sdk` or `fetch` + `x-api-key`, using shapes the agent already verified. Validate paths in the Playground before merging.

## Example: exploratory lookup via POST /v1/ask (0 credits to route)

```bash
curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"How many TikTok followers does MrBeast have?"}' \
  "https://api.socialfetch.dev/v1/ask"
```

## Why agent builders choose Social Fetch

- Hosted MCP server with OAuth (or x-api-key if the client cannot complete OAuth). Endpoint tools bill like REST; docs tools are free.
- One envelope everywhere: `data`, `meta.creditsCharged`, `meta.requestId`, and typed `error.code` on failure — parseable by your orchestrator without string-matching HTTP bodies.
- POST /v1/ask costs 0 credits to route; only the nested lookup charges. Good for agents that do not yet know which platform tool to call.
- No monthly minimum and no per-agent charge — fan-out ten parallel tool calls and pay for ten completed lookups, not an upgraded tier.
- Infrastructure failures (`lookup_failed`, `503`) are not charged. `not_found` on a completed lookup is charged — teach the agent that empty results are still outcomes.
- 57 platforms behind the same field conventions — your agent parses followers, posts, and transcripts with one mental model, not a scraper parser per network.
