Social Fetch
Start for freeStart free
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 transient 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 (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-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.
  • 23 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