Rate Limits
Per-minute and daily quotas for the SociaHive API and MCP server, plus the headers and back-off strategy.
SociaHive enforces per-user rate limits on every API key and OAuth token. Limits are bucketed by the kind of operation, not by the HTTP method — a tool that does a single read costs less budget than one that ships a generated flow graph.
The buckets
| Bucket | Limit | Window | Examples |
|---|---|---|---|
| read | 120 requests | 1 minute | list_flows, get_flow, list_scheduled_posts, get_analytics_overview, anything that fetches without mutating |
| write | 30 requests | 1 minute | create_flow, update_node, add_edge, create_scheduled_post, cancel_scheduled_post |
| expensive | 5 requests | 1 minute | generate_flow (AI flow generation), anything that fans out to an LLM or vector store |
| destructive | 10 requests | 10 minutes | delete_flow, delete_scheduled_post, bulk_delete_scheduled_posts. Deletes from a connected AI app also have a cap of 50 deleted items a day |
| daily | 1,000 requests | 24 hours | A cap that applies across all buckets combined — protects against runaway loops |
All limits are per user (per API key holder or OAuth subject), not per-key. Creating multiple keys doesn't multiply your quota.
Response when you exceed a bucket
The Retry-After header is canonical — honor it. details.window tells you which bucket tripped if you want to back off only that class of operation.
Recommended back-off
Don't retry tighter than Retry-After says — you'll just bounce off the same bucket again and waste your daily-cap budget.
MCP-specific limits
Beyond the four buckets above, the MCP HTTP transport adds a concurrent-session cap of 200. A "session" is an open SSE connection; idle ones time out after 5 minutes. If you're spawning many short-lived MCP clients in parallel (e.g. CI jobs), close the session explicitly after each batch instead of relying on GC.
The daily cap is the floor you'll actually hit
For most consumers, the per-minute buckets are forgiving — 120 reads per minute is more than any interactive session uses. The daily 1,000-request cap is what bulk-import scripts and aggressive cron jobs hit first.
If you're doing bulk work, prefer the bulk endpoints (posts.bulk, bulk_update_flows) over loops of single calls — one bulk call counts as one request against your quota regardless of how many entities it touches.
What's NOT rate-limited
- Authentication endpoints (
/api/oauth/*) — separately throttled by Cloudflare at the edge - Public marketing pages and
/api/v1/openapi.json(read-only static) - Outbound webhooks — SociaHive calls your endpoint, not the other way round. See Webhooks for the retry policy and signature scheme.
Tier-specific limits
The buckets above are the same for every paid tier. What changes by tier is the resource caps — connected accounts, scheduled posts per month, AI credits, etc. — not the API request rate. Tier resource caps are returned by the whoami MCP tool and the /api/v1/usage REST endpoint.