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 | At the cap |
|---|---|---|---|
| Free | $0 | 5,000 | hard stop |
| Hobby | $30 | 10,000 | analysis pauses; standard continues |
| Pro | $100 | 50,000 | analysis pauses; standard continues |
| Scale | $500 | 250,000 | analysis pauses; standard continues |
| Growth | $1,500 | 1,000,000 | analysis pauses; standard continues |
| 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.
On a paid plan, 5,000 units covers about 500 analysis cards. Free accounts can use every non-analysis tool but cannot call analysis endpoints.
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, the cap only pauses /v1/analysis/* — those requests return the same
429 QUOTA_EXCEEDED until the period resets or you upgrade. Standard endpoints keep
working past the cap: usage is still metered, but requests are never blocked. There is no
metered overage billing today — you are never charged past your plan price.
Upgrade at any time from the Billing page — the new limit applies immediately.
See Errors for the full error shape and retry guidance.