> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Stats Access
> Understand the new-account stats policy, legacy access, fixed samples, coverage limits, and upgrades.
The stat dictionary is available to every authenticated API key. Production game boxes, season aggregates, archives, and live REST boxes follow the account's effective stats access.
Accounts created on or after September 7, 2026 at 18:00 UTC follow the policy below. Accounts created before `2026-09-07T18:00:00Z` retain their existing legacy stats access. A missing `stats_policy_version`, or a value of `0`, means legacy access; it is not a new denial.
## New-account access matrix
This policy applies to accounts created on or after `2026-09-07T18:00:00Z` (September 7, 2026 at 18:00 UTC). It does not change prices, data-point allowances, odds history, or Web/Mobile product plans.
| API tier | Stats access for new accounts |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Free | Stat catalog and a fixed, complete-game box-score sample; new Free accounts also receive a seven-day evaluation of current-season completed boxes and aggregates |
| Starter | Supported completed-game team/player boxes in the current season, plus current-season team and player aggregates |
| Pro | Starter access plus available prior-season game and season archives |
| Ultra | Pro access plus live REST event boxes and live stats WebSocket delivery |
| Super, Mega, Max | The Ultra stats feature set with higher volume and odds-history capacity |
| Enterprise | Entitlements are scoped by contract |
The policy does not split ordinary box scores into individual paid stat fields. It also does not promise every sport, season, event, or stat definition is available.
## Stats access feature contract
Every stats route, including the catalog and fixed sample, returns effective policy headers. These headers are authoritative for the API key that made the request; integrations must not infer stats access from a plan name.
| Header | Meaning |
| ------------------------------- | -------------------------------------------------------------------------- |
| `X-Stats-Policy-Version` | `0` is legacy behavior; `1` is the new-account stats policy |
| `X-Stats-Game-Access` | Completed current-season event boxes are available |
| `X-Stats-Season-Access` | Current-season team and player aggregates are available |
| `X-Stats-History-Access` | Access to available prior-season game and season archives |
| `X-Stats-Live-Access` | In-progress REST event boxes are available |
| `X-Stats-Evaluation-Active` | Present for a new Free account; indicates whether its evaluation is active |
| `X-Stats-Evaluation-Expires-At` | Present for a new Free account; ISO 8601 evaluation expiry |
For an account created before `2026-09-07T18:00:00Z`, the server reports version `0` (or omits the version) and preserves existing REST stats access. A new Free account's evaluation can expire locally even if a cached upstream account grant has not refreshed.
The following object mirrors the policy represented by the headers. It is included here as an integration contract, not as a public token-inspection response.
```json theme={null}
{
"stats_policy_version": 1,
"stats_game_access": true,
"stats_season_access": true,
"stats_history_access": false,
"stats_live_access": false,
"stats_evaluation_active": true,
"stats_evaluation_expires_at": "2026-09-14T00:00:00Z"
}
```
| Field | Meaning |
| ----------------------------- | --------------------------------------------------------------------------- |
| `stats_policy_version` | `0` or absent is legacy access; `1` is the new-account stats policy |
| `stats_game_access` | Completed current-season event boxes are available |
| `stats_season_access` | Current-season team and player aggregates are available |
| `stats_history_access` | Available prior-season game and season archives are available |
| `stats_live_access` | In-progress REST event boxes are available |
| `stats_evaluation_active` | A new Free-account evaluation is currently active |
| `stats_evaluation_expires_at` | ISO 8601 evaluation expiry; it can remain present after the evaluation ends |
`stats_live_access` covers REST event boxes only. The `stats` WebSocket channel remains an Ultra-or-higher live-delivery feature. See [Live Game Stats](/api-reference/v2/stats#live-game-stats-over-websocket). The effective headers are authoritative for every request.
## Start with the fixed sample
`GET /api/v2/stats/sample` returns a fixed, complete-game box-score sample for schema and parsing tests. It requires an API key, consumes no data points, and is marked as sample data. It is intentionally static: it does not establish coverage, sport availability, event freshness, or a production-data entitlement.
```bash theme={null}
curl -H "X-TheRundown-Key: $THERUNDOWN_API_KEY" \
"https://therundown.io/api/v2/stats/sample"
```
Use the sample for a first integration. It has the wrapper `{sample: true, event, team_stats, player_stats}`. Do not poll it. A successful non-billable sample or catalog response can omit `X-Datapoints`; do not infer that an arbitrary response without the header is free. New Free accounts receive a default seven-day, no-card evaluation from account creation with current-season completed game boxes and current-season aggregates. It stays within the normal Free `20,000/day` and `200,000/month` data-point caps, never creates an automatic charge, and ends with the catalog and fixed sample still available. Check `stats_evaluation_active` and `stats_evaluation_expires_at` rather than calculating an expiry yourself.
## Production routes and safe polling
| Need | Route | Cost-safe use |
| ------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Stat catalog | `GET /api/v2/stats` | Cache by sport; definitions change far less often than games |
| Completed game box | `GET /api/v2/events/{eventID}/stats` and `/players/stats` | Fetch after a terminal event status; save the result and refresh only if your product needs corrections |
| Current-season aggregate | `GET /api/v2/teams/{teamID}/stats` and `/players/stats` | Cache and refresh on your product's postgame schedule; do not poll each team continuously |
| Live event box | Event box routes above | Only with `stats_live_access`; use a single event and a bounded interval when WebSocket delivery is unavailable |
| Live changes | V2 WebSocket `stats` channel | Ultra or higher; subscribe by event and merge row-level deltas |
For an Ultra live tracker, fetch one narrow REST baseline for the event, then subscribe to the stats channel and merge changes. On reconnect or a detected gap, fetch both baselines once before resuming. The detailed sequence is in [Streaming Live Game Stats](/guides/multiplexed-websocket#streaming-live-game-stats).
Odds data delay, odds-history days, and stats access are separate concepts. Do not infer one from another. In particular, an odds-history allowance does not establish statistics-season coverage.
## Coverage and historical limits
* A current season follows the latest started event's sport season, not the calendar year. Sports have different calendars and postseason timing.
* Current-season aggregates are the latest published aggregate. They can include in-progress activity; they are not a promise of a postgame-only snapshot.
* Prior-season access is limited to the game and season records available for that sport. Check the returned data before relying on an archive for research or backtesting.
* Archived game boxes preserve the event's team identity. Player season endpoints, however, use the player's current roster association; they do not guarantee historical roster or team attribution after a transfer.
* Empty arrays can mean an event has not started, the sport/event has no published rows, or a requested filter has no matching rows. They do not prove that a stat is zero.
## V1 and V2 compatibility
Stats are documented on the canonical V2 routes above. V1 delta endpoints, including `/api/v1/deltaV2`, are odds/event delta compatibility routes; they are not stats aliases and cannot be used to bypass an entitlement. API keys for accounts created before `2026-09-07T18:00:00Z` retain their existing legacy stats access.
## When access is unavailable
After a new Free account's evaluation expires, or when a production request is outside the account's effective access, the route returns `403`. Handle the structured fields instead of retrying or guessing from a plan name:
```json theme={null}
{
"error": "This API key is not entitled to current-season game stats",
"feature": "stats_game_access",
"required_tier": "starter",
"upgrade_url": "/pricing/api",
"sample_url": "/api/v2/stats/sample"
}
```
`sample_url` is a schema-testing fallback, not a replacement for production data. Keep the response visible to the account owner, avoid automatic retries on `403`, and use the returned stats headers before changing a polling job.
## Temporary metadata unavailability
When the service cannot resolve the metadata needed to classify an event or season, a production stats route can return a non-billable `503` instead of guessing an entitlement or suggesting an upgrade:
```json theme={null}
{
"error": "Statistics metadata is temporarily unavailable",
"code": "stats_metadata_unavailable",
"retryable": true
}
```
This response is non-billable and has no `Retry-After` header. Billing middleware can omit `X-Datapoints`, including on errors, so use the response status and body rather than requiring that header. Treat it as a temporary service condition: retry with your normal bounded backoff, keep the previous cached result if one exists, and do not show an upgrade prompt. A `403` remains an entitlement response and is not retryable.