## 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                         | 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 [#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.

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

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