Social Fetch
Get API key
All use cases

Social data API for AI agents

Your agent loop needs tools that return the same JSON shape every time — not HTML it has to guess at. Wire Social Fetch through MCP (OAuth in Cursor or Claude) or register REST endpoints as function-calling tools with OpenAPI-derived JSON Schema. POST /v1/ask routes exploratory questions for free; typed GET paths are what you ship once the plan is fixed.

Try in playgroundView pricing

What usually breaks first

Most ai agents pipelines fail on schema drift and billing surprises long before they fail on "missing a platform." The notes below are the failure modes we hear about after a DIY scraper or marketplace API is already in production.

Most agent failures around social data are not model mistakes — they are integration mistakes. An agent that fetches raw profile pages has to invent field names on every run. Hand-rolling one scraper tool per platform means your function-calling schema grows with every network, and the model starts picking the wrong tool or hallucinating parameters.

Function calling works when each tool has a narrow job, a documented JSON Schema, and responses the runtime can parse without a second LLM pass. That is what OpenAPI-backed routes give you: `data.lookupStatus`, `meta.requestId`, and `meta.creditsCharged` on every lookup — whether the agent called REST, the TypeScript SDK, or an MCP tool.

Agent loops also fan out. A research task that touches five creators on three platforms can fire fifteen tool calls before your guardrails notice. You need errors that are machine-actionable (`not_found` as HTTP 200 with `lookupStatus`, `503 temporarily_unavailable` for upstream blips, `402 insufficient_credits` before any charge) and billing that does not punish retries on infrastructure failures.

5 routes for this job

These are the routes we see in live ai agents integrations — ask, TikTok, Reddit, web, and YouTube in this list. Method, path, and query params match the public OpenAPI spec; when we add a field to docs, it ships 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

A common path starts with “point the agent at llms.txt first.” Your cron cadence, warehouse schema, and alert thresholds will differ — treat the steps as ordering hints, not a checklist you must copy verbatim.

  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 key from the dashboard. The playground pre-fills auth if you open the same path there — useful before you paste this into a worker or CI job.

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.
  • 13+ platforms behind the same field conventions — your agent parses followers, posts, and transcripts with one mental model, not thirteen scraper parsers.

Run a ai agents lookup on free credits

You get 100 credits on signup — enough to walk through the curl above against live data and inspect lookupStatus, pagination, and meta.creditsCharged. If the JSON lands cleanly in your pipeline, buy a credit pack once; balances do not expire on a subscription clock.

Open playgroundSee pricing