Social Fetch
Get API key
All use cases

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.

Try in playgroundView pricing

What usually breaks first

Common failure modes after a DIY scraper or marketplace API hits production — schema drift, billing surprises, and pagination quirks.

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 upstream blips, `402` before charge) and billing that skips infrastructure failures.

5 routes for this job

Routes used in live ai agents integrations (ask, TikTok, Reddit, web, and YouTube). Paths and params match OpenAPI; documented fields ship in responses.

  • 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.

OpenAPI reference →

How teams wire this

Typical order starts with “point the agent at llms.txt first.” Adjust cadence, schema, and thresholds to your stack.

  1. 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. 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. 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. 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. 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. Recommend staying under ~500 concurrent requests for reliability.

  6. 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)

Swap YOUR_API_KEY for a dashboard key. The playground pre-fills auth for the same path.

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

Why agent builders choose Social Fetch

  • Hosted MCP server with OAuth — no API key pasted into `mcp.json`. 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-seat tax — 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.
  • 21 platforms behind the same field conventions — your agent parses followers, posts, and transcripts with one mental model, not a scraper parser per network.

Run a ai agents lookup on free credits

100 credits on signup — run the curl above, inspect lookupStatus and meta.creditsCharged, then buy a pack when ready. Balances do not expire.

Open playgroundSee pricing