# SocialRouter

> Social media data API with one endpoint per service. Structured JSON from LinkedIn, Instagram, TikTok, Reddit, YouTube and more. REST, SDK and MCP. Pay per record.

SocialRouter is a routing layer over multiple social-data providers. You send a request to a single endpoint; SocialRouter routes it to a compatible provider, moves to the next one if that provider errors or rate-limits, and returns the same response shape whichever one fulfilled it. Reachable over HTTP, from the TypeScript SDK, or from an agent through the MCP server.

## Why SocialRouter

- **One integration for every provider.** One endpoint per service, one response shape across every network and provider. You write your parsing once.
- **Failover inside the call.** When a provider errors or rate-limits, the next compatible one picks up the same request. Nothing to retry on your side.
- **You stay in control.** Let SocialRouter pick the provider, pin one in the request, or register your own provider key and be invoiced by that provider directly.
- **Billed per record returned.** No subscription and no minimum. A failed attempt returns no records and costs nothing.

## Key numbers

- 61 services
- 12 networks covered
- 3 providers integrated

## Networks

LinkedIn, Google Maps, YouTube, Reddit, Instagram, Facebook, TikTok, Pinterest, Bluesky, X, Snapchat, Apollo

## Providers

- **Apify** — Versatile scraping platform with broad social media coverage. 23 services.
- **Bright Data** — Enterprise-grade data collection with high volume capacity. 40 services.
- **Apollo** —  6 services.

## When to use SocialRouter

Reach for it when a job needs public data that lives on a social network and there is no first-party access to it:

- **Find people or companies** — search profiles or posts on a network, then read who wrote or engaged with them.
- **Watch an account or a competitor** — pull a profile's posts, comments, followers or reviews on a schedule.
- **Listen for a signal** — read a subreddit, a keyword search or a hashtag and hand the records to whatever decides what matters.
- **Enrich a record you already hold** — start from a profile URL, a domain or a company name and get the entity behind it.

It is the wrong tool for: data behind a login you own (the platform's own API is first-party and cheaper), anything you need as a live stream (every call is a request/response run that returns records), and any use the source platform's terms forbid.

## How an agent should call it

1. **Read the catalogue first**, `GET https://api.socialrouter.io/v1/services` — no key needed. It names every service, the field its input goes in (`urls`, `queries` or `identifiers`), its typed options, its offers and the price per record. Pick the service from there rather than guessing an endpoint.
2. **Run it** with the API key in `Authorization: Bearer <key>`. One endpoint per service, `POST /v1/extract/{platform}/{service}` for a network or `/v1/enrich/{entity}/{service}` for a person or a company.
3. **Read `served_by`** to know which offer ran, and `status` to know whether it completed. Errors carry a machine-readable `error.code` and a corrective `error.message`; a 402 means the account is out of credits, a 429 means a limit was hit, and both are account states an agent cannot fix by retrying faster.

## How it works

1. **Get an API key.** Sign up with GitHub or Google. No credit card.
2. **Call one endpoint per service**, `POST /v1/extract/{platform}/{service}` (or `/v1/enrich/{entity}/{service}`). SocialRouter handles offer selection, failover and normalization.

   ```
   POST /v1/extract/linkedin/post.likes
   {
     "urls": ["linkedin.com/posts/..."]
   }
   ```

   `provider` is optional and pins one offer (`source/name`, e.g. `apify/apimaestro`). Pinning disables failover.
3. **Read a normalized response.** The shape does not depend on which offer ran — `served_by` names the one that did.

   ```
   {
     "status": "completed",
     "platform": "linkedin",
     "service": "post.likes",
     "served_by": "apify/apimaestro",
     "data": [
       { "name": "Sarah Chen", "title": "VP of Sales" }
     ]
   }
   ```

## Developer resources

- [OpenAPI 3.1 spec](https://api.socialrouter.io/v1/openapi.json) — every endpoint, typed request and response schemas, one operationId per service
- [MCP server, Streamable HTTP](https://mcp.socialrouter.io/mcp) — point an MCP host at this URL; `npx @socialrouter/mcp` is the same tools over stdio
- [TypeScript SDK](https://www.npmjs.com/package/@socialrouter/sdk) — `npm i @socialrouter/sdk`
- [CLI](https://www.npmjs.com/package/@socialrouter/cli) — `npx @socialrouter/cli`
- [Docs](https://docs.socialrouter.io) — API reference, SDK, CLI and MCP guides
- [API keys](https://www.socialrouter.io/dashboard/keys) — self-serve, created in the dashboard, no sales call and no credit card
- [Playground](https://www.socialrouter.io/dashboard/playground) — run any service from the browser before wiring it up

## Key pages

- [Home](https://www.socialrouter.io/)
- [Services](https://www.socialrouter.io/services) — every service, its providers and its price per record
- [Compare](https://www.socialrouter.io/compare) — providers side by side
- [Docs](https://docs.socialrouter.io) — API reference, SDK, CLI and MCP guides