# ReachSocial

> Provider-neutral public social data for applications and agents. ReachSocial returns normalized metadata and source media URLs; it does not download or retain media bytes.

Official site: https://reachsocial.dev

## Machine entry points

- Executable service catalog: https://reachsocial.dev/v1/services
- Reviewed service roadmap: https://reachsocial.dev/v1/catalog
- OpenAPI: https://reachsocial.dev/openapi.json
- Agent operating guide: https://reachsocial.dev/agent.md
- Plain-text agent guide: https://reachsocial.dev/agent.txt
- API catalog: https://reachsocial.dev/.well-known/api-catalog
- Status: https://reachsocial.dev/status.json
- MCP server card: https://reachsocial.dev/.well-known/mcp.json (returns 503 while MCP is disabled)
- Official MCP Registry record for `dev.reachsocial/social-data`: https://registry.modelcontextprotocol.io/v0.1/servers/dev.reachsocial%2Fsocial-data/versions/latest
- Glama connector: https://glama.ai/mcp/connectors/dev.reachsocial/reach-social-one-api-for-social-media-data

## Available services

- `instagram.profile` — sync; $0.05; POST `/v1/services/instagram.profile/execute`; inputs: url; returns `profile`.
- `instagram.post` — sync; $0.05; POST `/v1/services/instagram.post/execute`; inputs: url; returns `item`.
- `instagram.feed` — sync; $0.05; POST `/v1/services/instagram.feed/execute`; inputs: url, max_items?; returns `feed`.
- `instagram.highlight` — sync; $0.05; POST `/v1/services/instagram.highlight/execute`; inputs: url, max_items?; returns `stories`.
- `x.profile` — sync; $0.05; POST `/v1/services/x.profile/execute`; inputs: url; returns `profile`.
- `x.post` — sync; $0.05; POST `/v1/services/x.post/execute`; inputs: url; returns `item`.
- `x.feed` — sync; $0.05; POST `/v1/services/x.feed/execute`; inputs: url, max_items?; returns `feed`.
- `tiktok.profile` — sync; $0.05; POST `/v1/services/tiktok.profile/execute`; inputs: url; returns `profile`.
- `tiktok.feed` — sync; $0.05; POST `/v1/services/tiktok.feed/execute`; inputs: url, max_items?, cursor?; returns `feed`.
- `tiktok.video` — sync; $0.05; POST `/v1/services/tiktok.video/execute`; inputs: url; returns `item`.
- `youtube.channel` — sync; $0.05; POST `/v1/services/youtube.channel/execute`; inputs: url; returns `profile`.
- `youtube.feed` — sync; $0.05; POST `/v1/services/youtube.feed/execute`; inputs: url, max_items?; returns `feed`.
- `youtube.video` — sync; $0.05; POST `/v1/services/youtube.video/execute`; inputs: url; returns `item`.
- `facebook.profile` — sync; $0.05; POST `/v1/services/facebook.profile/execute`; inputs: url; returns `profile`.
- `reddit.post` — sync; $0.05; POST `/v1/services/reddit.post/execute`; inputs: url; returns `item`.

## Authentication and payment

- B2B clients send `Authorization: Bearer <ReachSocial API key>` and a stable `Idempotency-Key`.
- Anonymous public calls require a random 32–255 character `Idempotency-Key`, then receive an x402 v2 `402 Payment Required` challenge on Base mainnet. Sign the exact requirement and retry once with `PAYMENT-SIGNATURE`.
- Never submit a wallet private key, provider token, or B2B API key as service input.

## MCP access and result recovery

MCP is available to approved clients with a scoped API key. Wallet sign-in and per-request payment approval are limited to approved pilot wallets. For wallet access, connect to /mcp/ using OAuth, sign in, and approve agent access. Reuse a valid ReachSocial browser sign-in with Continue to [app]. Generate and save a random request key with the exact inputs before each new request. A service tool returns a request ID, price, and payment URL. Glama's Inspector displays Review payment and Refresh result buttons in the ReachSocial card. Review payment opens that request on ReachSocial, where the user approves payment in their wallet. Clients without the card use the returned payment_url; URL-capable clients may show a payment prompt. After the user pays for that exact request, retrieve its result automatically with get_reachsocial_request and the original request ID. In a manual inspector, Refresh result or the same tool inputs and idempotency key recover that request. Keep the Glama Inspector tab open during payment; closing it can require reconnecting. Login, opening a link, and accepting a prompt do not authorize or prove payment. Result retrieval never creates a payment.
Directory listings describe the server; they do not grant access or authorize spending.

## Execution rule

Choose the smallest available service matching the URL. Use `/execute` for synchronous services and `/jobs` for asynchronous services. For a job, retain its job token when present and poll the returned status URL until `succeeded`, `failed`, or `expired`; never recreate a pending paid job. A lost paid response can be recovered with the same key and input at `/v1/payments/recover/{service_id}` without another transfer.

## Contract

Successful results use schema `1.0` and normalization `v1`. Missing provider fields are null or empty; ReachSocial does not invent them and never exposes raw provider payloads or provider names.