## Units [#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 [#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 [#what-5000-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](/docs/api) 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 [#monitoring-usage]

Your current-period usage is visible on the [Billing](/dashboard/billing) page. The response
headers on every API call also carry your real-time quota state — see
[Rate limits](/docs/getting-started/rate-limits) for the header names.

## Exceeding your quota [#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](/dashboard/billing) page — the new limit applies
immediately.

See [Errors](/docs/getting-started/errors) for the full error shape and retry guidance.