Authentication
Authenticate Social Fetch API requests with an API key in the x-api-key header. Put the key in the SOCIALFETCH_API_KEY environment variable, then test it with one free curl request.
Every request to https://api.socialfetch.dev authenticates with an API key sent in the x-api-key header. Keys start with sfk_. There's no OAuth flow or token exchange for the REST API: the key is the whole credential, so it works the same from a terminal, a server, a CI job or an AI agent.
1. Create a key
Sign up at app.socialfetch.dev/signup (new accounts get free credits, no card needed), then create a key under API Keys. The full key is shown once, so copy it then. Quickstart walks through it with screenshots.
2. Put it in SOCIALFETCH_API_KEY
Every example in these docs, the TypeScript SDK and the socialfetch CLI read the key from the SOCIALFETCH_API_KEY environment variable:
export SOCIALFETCH_API_KEY=sfk_...For a .env file or PowerShell:
3. Test it with curl
GET /v1/whoami is free. It returns the account and workspace the key belongs to:
curl -sS \
-H "x-api-key: $SOCIALFETCH_API_KEY" \
"https://api.socialfetch.dev/v1/whoami"Then make a paid lookup the same way. This TikTok profile lookup costs 1 credit:
curl -sS \
-H "x-api-key: $SOCIALFETCH_API_KEY" \
"https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio"When authentication fails
| Status | Code | Meaning |
|---|---|---|
401 | unauthorized | The key is wrong, revoked or expired. On free routes such as /v1/whoami, a missing key also returns 401. |
402 | payment_required | No key was sent to a paid route. Check the header name and that SOCIALFETCH_API_KEY is set where the command runs. |
402 | insufficient_credits | The key works, but the workspace is out of credits or the key reached its monthly spend limit. See Credits. |
403 | forbidden | The key is valid but can't be used right now. reason says why. |
All error bodies share one { error } shape with a requestId. See Errors.
Keep the key secret
- Send it only in the
x-api-keyheader. Never put it in a URL or query string, where it ends up in logs, and never inAuthorization: Bearer, which is rejected. - Keep it on a server or in your own scripts. Never ship it in website front-end code or a mobile app.
- Use one key per app or machine, so you can revoke one without breaking the rest. Owners can set a monthly spend limit on each key (Teams).
SDK, CLI and MCP
- TypeScript SDK:
new SocialFetchClient({ apiKey: process.env.SOCIALFETCH_API_KEY! }). See TypeScript SDK. - CLI:
npx socialfetch listen --forward-to <url>readsSOCIALFETCH_API_KEY(or--api-key). See CLI and agents. - MCP (
https://api.socialfetch.dev/mcp): clients sign in with OAuth in the browser. A client that can't do OAuth can send the samex-api-keyheader. See MCP.
Limits on how fast you can call the API are in Rate limits.
Quickstart
Create an account and an API key, run your first lookup in the Playground and with cURL, then read the `{ data, meta }` response and the credits it cost.
CLI and agents
Use Social Fetch from a terminal or a coding agent: set SOCIALFETCH_API_KEY, call the API with curl and jq, run the socialfetch CLI, connect the MCP server and install the agent skill. No browser needed after you have a key.