Rate limits

Xpoz applies two limits per account: an instantaneous request rate and a credit quota (one-time on Free, monthly on Pro and Max). Both are enforced against the OAuth-authenticated user behind any MCP, SDK, or CLI call.

Per-plan limits

Plan	Requests / min	Concurrent requests	Credits	Approx. results	Tracked items
Free	30	2	500 (one-time)	up to 75,000	1
Pro ($20/mo)	120	6	7,500 / month	up to 1,000,000	3
Max ($200/mo)	600	20	120,000 / month	up to 18,000,000	10
Enterprise	custom	custom	custom	custom	custom

Credits are charged per query, not per row returned: Reddit and Twitter/X queries cost 2 credits, TikTok 5, Instagram 12, and result counts scale accordingly. Overage on paid plans is $3 per 1,000 credits on Pro and $2 per 1,000 credits on Max. Count-only tools (countTweets, checkAccessKeyStatus) do not consume credits. Current plan details: /pricing.

429 contract

When the per-minute rate limit is exceeded, the MCP server returns a JSON-RPC error with code -32099 mapped from a transport-level HTTP 429:

{
  "jsonrpc": "2.0",
  "id": 17,
  "error": {
    "code": -32099,
    "message": "rate_limited",
    "data": {
      "retry_after_ms": 4200,
      "limit": 120,
      "window_seconds": 60
    }
  }
}

Transport headers also carry the contract for non-MCP HTTP probes:

Header	Meaning
`Retry-After`	Seconds to wait before retry (RFC 7231)
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix seconds at which the window resets

Quota exceeded

When the credit quota is exhausted, calls that would return data fail with:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly result quota reached for plan: Free",
    "details": { "plan": "free", "limit": 100000, "reset_at": "2026-06-01T00:00:00Z" }
  }
}

Upgrade at /pricing or, on Pro and Max, wait for the monthly reset (Free credits are a one-time allocation and do not reset). checkAccessKeyStatus returns the live remaining quota.

Retry guidance

429 (rate_limited): sleep for retry_after_ms then retry. For unattended jobs use jittered exponential backoff capped at 60 s.
5xx: retry up to 3 times with exponential backoff (1s, 2s, 4s).
4xx (other): do not retry — the request is malformed or unauthorized.

Avoiding rate limits