Skip to main content

How quotas work

Your account has a daily quota that resets at midnight UTC, shared by all your API keys. API access is a plan entitlement (api_access), not a tier name: any plan that includes it can use the API. The quota depends on the plan:

What counts

Discovery and /me are free so clients and agents don’t burn quota finding out what exists or how much is left. A counted endpoint uses one request even when it answers 400 or 404; requests that fail authentication or entitlement checks (401, 403) are not counted.

History file credits

Downloading a daily history file does not use your request quota. It uses a separate daily bucket of file credits, so a bulk download never eats the requests your bot needs: The bucket resets at midnight UTC, like the request quota. One successful download costs one credit; a 400, 404 or 503 costs nothing. Responses to a download carry:
When the credits are gone the API answers 429 history_files_limit_exceeded (again with no Retry-After header: read X-History-Files-Reset). /me shows both buckets in quota.requests and quota.history_files. For scale: 200 credits cover about 100 sessions of two files in one day.

Rate limit headers

Every counted response includes three headers (free endpoints and file downloads don’t; downloads carry the X-History-Files-* headers above):
The rate_limit field in the response body contains the same information:

Handling 429 responses

When you exceed your quota the API answers 429 and does not send a Retry-After header. The quota resets at midnight UTC, so any honest delay-in-seconds could be up to 86400, and HTTP clients that obey Retry-After automatically would sleep for hours. Read X-RateLimit-Reset (ISO 8601, UTC) or call the free /me (quota.requests.reset) and decide for yourself:
No Retry-After header is sent on a 429 — use X-RateLimit-Reset, as the examples below do.Until July 2026 the API did send Retry-After, carrying the ISO-8601 reset timestamp. That violates RFC 9110 — which permits only delay-seconds or an HTTP-date — so retry adapters that read the header automatically (urllib3 Retry, axios-retry) could not parse it. It was removed rather than converted: the quota resets at midnight UTC, so the only correct delay-seconds value ranges up to 86400, and those same adapters would honour it by sleeping for hours.If your client reads Retry-After, switch it to X-RateLimit-Reset and apply your own backoff policy.

Planning your quota

The underlying GEX data updates every 15 minutes (Lambda capture). Polling more often than that doesn’t yield new data. A typical trading bot pattern:
  • term-oi for BTC + ETH every 15 min = 2 × 4 = 8 req/hour
  • by-strike-enhanced for 2-3 expirations every 15 min = ~10 req/hour
  • Discovery endpoints and /me: free
Total: ~430 req/day for a busy bot, within the 500/day quota.

Running out of quota?

  • Cache responses locally. The data only changes every 15 min.
  • Use the virtual all exchange (or a subset like deribit+derive) instead of calling each exchange separately.
  • Use /levels when you only need flip, regime and walls: one small call instead of a full by-strike payload.
  • Check /me instead of probing: it is free.
  • Reduce polling frequency to once every 30 min if you don’t need sub-15-min latency.
  • Contact us at admin@gammaflip.io if you need a higher custom limit.