Quotas
Plan tiers, monthly unit allowances, and what happens when you exceed.
Units
Every API request that reaches a data endpoint costs at least 1 unit, and heavier endpoints cost more — see the weights table below. Quota resets at the start of each billing period.
Health and readiness checks (/healthz, /readyz) are free and never counted.
Plans
| Plan | Price / mo | Units / mo | Overage |
|---|---|---|---|
| Free | $0 | 5,000 | none — hard stop |
| Hobby | $30 | 10,000 | 0.5¢ / unit |
| Pro | $100 | 50,000 | 0.3¢ / unit |
| Scale | $500 | 250,000 | 0.15¢ / unit |
| Growth | $1,500 | 1,000,000 | 0.1¢ / unit |
| Enterprise | Custom | 5,000,000 baseline, contract-sized | Custom |
All paid plans have access to all competitions and all endpoints, including
/v1/analysis/*. The free tier covers every endpoint except /v1/analysis/*, which
returns 403 TIER_REQUIRES_PAID.
What 5,000 units actually buys you
Units are abstract — here's the translation in real calls. Pick the row that matches your workload.
| Workload | Weight per call | What 5,000 units gives you |
|---|---|---|
| Raw lookups (person/team search, standings, contest detail, competitions) | 1× | ≈ 5,000 lookups |
| Box scores, game logs, season stats, contest lists | 2× | ≈ 2,500 reads |
| Rosters and matchup boards | 3× | ≈ 1,600 pulls |
| Play-by-play (Statcast) | 5× | ≈ 1,000 games |
Analysis cards (/analysis/*) | 10× | ≈ 500 cards (paid tier) |
The exact weight for each endpoint is published in the OpenAPI spec as
x-statshawk-weight and shown on each REST reference page.
So a chat bot that does light lookups all month sits comfortably in the free tier. A model that calls a prop-analysis card on every message will burn through 5,000 units in a session — bump up.
Monitoring usage
Your current-period usage is visible on the Billing page. The response headers on every API call also carry your real-time quota state — see Rate limits for the header names.
Exceeding your quota
On the free tier, hitting the monthly cap is a hard stop — further requests return
429 Too Many Requests with error.code: "QUOTA_EXCEEDED" until the period resets or you
upgrade. The X-RateLimit-Reset header carries the period-end timestamp.
On paid tiers, usage past the included allowance rolls into the per-unit overage rate in the table above rather than stopping — a quota 429 on a paid plan is rare and usually clears within seconds as the billing ceiling reconciles.
Upgrade at any time from the Billing page — the new limit applies immediately.
See Errors for the full error shape and retry guidance.