Rate limits
The limits the Social Fetch API enforces: no requests-per-second cap on paid lookups with an API key, 200 requests in flight per workspace, per-minute limits on free routes and keyless calls, and how 429, 503 and Retry-After work.
Paid lookups sent with an API key have no request quota and no requests-per-second limit. Your credit balance is what limits them, plus a cap of 200 requests in flight per workspace. Free routes and requests sent without a key have per-minute limits.
Every limit is the same on every plan.
Limits by route
| Requests | Limit | Counted per | When you go over |
|---|---|---|---|
Paid lookups (/v1/**, /v2/**) with an x-api-key | No per-minute limit. 200 requests in flight at once. | Workspace (all its keys together) | 503 temporarily_unavailable, reason: "concurrency_limit", Retry-After: 1 |
| Requests without an API key (x402 payments, or a missing key) | 60 per minute | Client IP address | 429 temporarily_unavailable with Retry-After |
GET /v1/whoami | 30 per minute | User | 429 temporarily_unavailable with Retry-After |
GET /v1/balance | 30 per minute | Workspace | 429 temporarily_unavailable with Retry-After |
GET /health | 60 per minute | Client IP address | 429 temporarily_unavailable with Retry-After |
POST /v1/query/validate | 60 per minute | Workspace | 429 temporarily_unavailable with Retry-After |
POST /v1/query/suggest | 10 per minute and 300 per day | Workspace | 429 temporarily_unavailable with Retry-After |
| Webhook endpoint test sends | 10 per minute | Webhook endpoint | 429 with Retry-After |
| Webhook redeliveries | 30 per minute | Webhook endpoint | 429 with Retry-After |
MCP (/mcp), signed in | 600 per minute | Signed-in user | 503 temporarily_unavailable with Retry-After |
| MCP, not signed in | 60 per minute, and 15 unpaid tool calls per minute | Client IP address | 429 temporarily_unavailable with Retry-After |
Per-minute limits use a sliding one-minute window, not a fixed clock minute.
The in-flight cap isn't a rate: a slot frees as soon as a request finishes, so a workspace can send far more than 200 requests a minute as long as no more than 200 are running at once.
Headers
Retry-After: sent with every429and with503temporarily_unavailable. It's a whole number of seconds to wait before retrying.X-Request-Id: sent on every response. Quote it to support.
The API doesn't send X-RateLimit-Limit, X-RateLimit-Remaining or RateLimit-* headers. Use Retry-After when you're refused, and GET /v1/balance (free) to see how many credits are left.
What a refusal looks like
A 429 has the same { error } body as every other error:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{
"error": {
"code": "temporarily_unavailable",
"message": "This endpoint is temporarily rate limited. Retry later.",
"requestId": "req_..."
}
}Going over the in-flight cap returns 503 with reason:
{
"error": {
"code": "temporarily_unavailable",
"message": "Too many requests in progress for this account (limit 200 at once). Retry after a request finishes.",
"requestId": "req_...",
"reason": "concurrency_limit"
}
}Neither response costs credits.
Retrying
- On
429or503, wait the number of seconds inRetry-After, then retry the same request. - If there's no
Retry-After, back off with a growing, jittered delay (for example 1 s, 2 s, 4 s). - To stay under the in-flight cap, run paid lookups through a worker pool of at most 200 per workspace.
- Don't retry
402insufficient_creditsin a loop: add credits first. See Credits.
To check that you're within a limit from the terminal:
curl -sS -i \
-H "x-api-key: $SOCIALFETCH_API_KEY" \
"https://api.socialfetch.dev/v1/balance"A full retry wrapper is in Errors.
Credits
How credits work in Social Fetch. What costs credits, pay-as-you-go and plans, where to see your balance and what each request cost, auto top-up, and balance checks for integrators.
Capability matrix
Every Social Fetch endpoint by platform: what to pass, the SDK method, how to page, what it costs and what an empty result means. Generated from the public OpenAPI spec.