# SocialAPIs: instructions for AI agents

> SocialAPIs (socialapis.io) is a REST API for public Facebook and Instagram data: Pages, posts, groups, the Meta Ads Library, Marketplace, Instagram profiles, posts and reels. Public, logged-out data only: no Facebook or Instagram logins, no private profiles or groups, no posting.

## Auth

- Header: `x-api-token: <API key>` on the REST API (the MCP server takes `Authorization: Bearer <API key>`).
- Get a key: https://socialapis.io/auth/signup (Google or email). Free plan: 200 calls a month, no card.
- Keep the key out of URLs you share and out of client-side code.

## REST API

- Base URL: https://api.socialapis.io
- Every endpoint is a GET with query parameters and a JSON response. One line per endpoint: https://socialapis.io/llms-endpoints.txt (live). Docs: https://socialapis.io/api-sources and https://docs.socialapis.io
- OpenAPI 3.1: https://socialapis.io/openapi.json
- Example: `curl -G "https://api.socialapis.io/facebook/pages/details" -H "x-api-token: $SOCIALAPIS_API_KEY" --data-urlencode "link=https://www.facebook.com/EngenSA"`
- Pagination: pass `end_cursor` from the response (`page_info.end_cursor`) to the next call.
- Cost: credits per call, 1 credit for most endpoints; each endpoint lists its price, and every response says what it charged (`X-SocialAPIs-Credits-Deducted` header). Balance: `GET /usage` (free).

## MCP server

- Hosted: https://mcp.socialapis.io/mcp (streamable HTTP), header `Authorization: Bearer <API key>`
- Local: `npx -y @socialapis/mcp` with `SOCIALAPIS_API_KEY` in the environment
- 12 read-only tools (facebook_page, facebook_group, facebook_post, facebook_search, facebook_ads, facebook_marketplace, instagram_profile, …), each with an `action` argument. A tool call costs the same credits as the API call behind it.
- Setup per client: https://socialapis.io/integrations

## Agent skill

- `npx skills add SocialAPIsHub/skills` (https://github.com/SocialAPIsHub/skills): which endpoint fits which task, for Claude Code and other skill-aware agents.

## Rate limits

- When a key sends too many requests the API answers HTTP 429: wait and retry with backoff. Don't retry a 4xx caused by bad input; fix the parameters.

## Pricing

- Free: 200 calls a month
- Pro: $4.99/month, 1,500 calls a month
- Ultra: $49/month, 30,000 calls a month
- Mega: $179/month, 120,000 calls a month
- Enterprise: custom volume and SLA
- Details: https://socialapis.io/pricing

## More

- Summary for LLMs: https://socialapis.io/llms.txt (plus every published answer: https://socialapis.io/llms-full.txt)
- Contact: https://socialapis.io/contact-us, Telegram https://t.me/socialapis