rate limits & quotas

Understand API query quotas, endpoint isolation, reset schedules, and service-specific limits.

To protect low-latency streaming infrastructure for all traders, gexbot applies tiered query quotas and concurrency limits.

Quota Policy & Endpoint Isolation

Independent Endpoint Buckets: Quotas track independently per endpoint pool. Every route form of one endpoint shares one pool, including the platform integration routes. Exceeding a limit on one endpoint (such as historical downloads or Research charts) does not block your account on other endpoints or live WebSockets.
Route Pools (api_default): Standard snapshot routes (/{ticker}/{package}/{category}) share one default quota pool (api_default). The /{ticker}/{package}/{category}/majors route (api_majors), the /{ticker}/{package}/{category}/maxchange route (api_max_change), /futures/conversion (api_futures_conversion), /hist/{ticker}/{package}/{category}/{date} (api_history_cache) and /research/{ticker}/{metric} (api_research_command) each have their own quota pool. Each pool has its own daily and monthly limit. The api_majors and api_max_change allowances are equal to each other and smaller than api_default.
Quota Windows: Quotas operate over independent daily and monthly windows.
Per Account: Quotas count per account. All API keys of one account share each pool.
Midnight ET Rollover: Daily quotas reset every night at 12:00 AM ET (Midnight Eastern Time) to align with US trading session boundaries. Monthly quotas reset at 12:00 AM ET on the first day of the month.
Email Breach Notifications: On the first breach of an endpoint in a daily or monthly window, gexbot sends an email alert to your registered account email (maximum 1 notification per endpoint per window).

Service-Specific Quotas

Live REST API (Classic, State, Orderflow)

Operating Hours (NYSE RTH): Spot prices, trade classification, and live feeds update actively from 9:30 AM to 4:00 PM ET. GEX by Open Interest updates daily at 8:30 AM ET.
Tier Scaling: The api_default allowance grows with each subscription level. The api_majors and api_max_change allowances grow from Classic to State to Orderflow. Quant uses the same api_majors and api_max_change allowance as Orderflow. History and futures allowances are fixed.
Server Calculation Frequency: Live calculations refresh at most once per second (1/sec) during market hours. Polling a single ticker more frequently than 1/second returns identical data.
Universe Scanning: To track multiple tickers or profiles simultaneously, stream metrics over WebSockets using the Quant tier rather than heavy REST polling.

Research API (`gbR`)

Research add-on required: A research_ API key can be created only with the active Research add-on. The Research REST API has no preview tier.
Web app and Discord without the add-on: 50 charts per day and 1,500 per month for a linked account; 10 per day and 300 per month for a Discord account with no linked gexbot account.
Add-on quota: 1,000 charts per day and 20,000 per month in the web app and Discord. A Research API key has its own pool (api_research_command), separate from the gexbot data pools: 1,000,000 requests per day and 30,000,000 per month per endpoint.
Dynamic Caching:
- Market Hours (09:30–16:00 ET): Live metrics cache on 15-minute floor intervals on-request.
- Premarket (before 09:30 ET): Uses the previous session quotes. Open Interest refreshes daily at 08:00 ET.
- After Hours & Weekends: Returns the cached snapshot from the previous session close.

Quant WebSocket Streaming

Session Slot: Each account has one custom-script WebSocket session slot, shared by all custom API keys of the account, and one platform-integration session slot, shared by the official platform keys (ATAS, Bookmap, NinjaTrader, MotiveWave, Quantower, Sierra Chart, TradingView). A slot covers every hub the account is authorized for (v2_classic, v2_state_gex, v2_state_greeks_zero, v2_state_greeks, v2_state_greeks_one, v2_orderflow). Spot data uses these same connections and has no hub of its own. One custom-script session and one platform-integration session can run at the same time.
Subsequent Negotiations: A new POST or GET /negotiate from any key of the same account closes the existing connections of that slot on every hub with the reason Websocket Session Limit Reached before it returns new URLs. PATCH /negotiate does not close the session; it needs a live connection on every targeted hub.
Group Quotas: Default limit of 150 active hub and group pairs. Each subscribed analytics group plus its companion {TICKER}_spot membership counts toward this limit.
Connection Window: Authorized URLs from negotiation expire after 15 minutes if not connected.

Handling 429 Responses

When you exceed a rate limit quota:

The server returns HTTP status 429 Too Many Requests.
The response body includes a descriptive error message:
```
{
  "error": "Rate limit exceeded."
}
```
Use exponential backoff before retrying.
If support raises your limit during a window, the 429 can continue for up to 15 minutes.