Rate Limits & Clamping
The WSO API provides per-minute request rate limits, concurrency controls, and query clamping rules enforced per account across all API keys.
Plan Allocation Matrix
| Plan | Rate Limit (RPM) | Max Concurrency | Max Rows / Query | History Window |
|---|---|---|---|---|
| Loading plan allocations from /public/plans... | ||||
Per-Minute Limits & No Daily Quota
Every API call costs the same; the per-minute rate limit and concurrency ceiling are the only budget. There is no daily quota. Batch requests (such as batch option quotes) count as one request against your rate limit.
Per-minute rate limits refill continuously via a GCRA (Generic Cell Rate Algorithm) leaky bucket. When your bucket is temporarily exhausted, the API returns HTTP 429 with a Retry-After header indicating the number of seconds until sufficient tokens have replenished.
Query Result Clamping
Result clamping caps the limit query parameter on endpoints whose limits table defines max_rows:
- /v1/chain/{symbol}
- /v1/earnings
- /v1/dividends
- /v1/flow
- /v1/stocks/top-iv
- /v1/stocks/top-ivr
On these endpoints the server uses the limit you send, or the endpoint's default when you send none, and caps it at your plan's max_rows. Whenever that cap lowers the limit, the response carries X-Limit-Clamped: true — including requests that send no limit when the endpoint's default is above your plan's max_rows. The cap is applied before the query runs; responses are never truncated afterwards. Each endpoint's own maximum and out-of-range rules are listed on its reference page. All other endpoints are not clamped.
History clamping applies to /v1/earnings, /v1/dividends, /v1/flow and /v1/flow/net: dates before your plan's history_days window are moved forward to the start of the window (Eastern Time), and the response carries X-Limit-Clamped: true.
Response Headers
Responses include diagnostic and rate-limit headers according to the stage reached in request processing:
| Header Name | Description |
|---|---|
| X-RateLimit-Limit | Maximum number of allowed requests in the current 1-minute window. |
| X-RateLimit-Remaining | Remaining requests allowed in the current 1-minute window. |
| X-RateLimit-Reset | Time in seconds until the rate limit bucket fully refills. |
| X-Request-ID | Unique request identifier. Echoes a valid client-supplied request ID or contains a server-generated UUID for tracing. |
| X-Limit-Clamped | Returned with value 'true' when results were clamped by account tier row or history limits. Can appear on 200 responses as well as downstream handler 4xx/5xx responses. |
| Retry-After | Number of seconds to wait before retrying a rate-limited request. |
| X-Data-Source | Present only when the response was served from stored data because the live provider was unavailable (value database-fallback). |
| WWW-Authenticate | Specifies Bearer authentication challenge. |
Retry-After response header specifying the seconds to wait before retrying.