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 after2026-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.
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.
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.
stats_live_access covers REST event boxes only. The stats WebSocket channel remains an Ultra-or-higher live-delivery feature. See Live Game Stats. 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.
{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
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.
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 returns403. Handle the structured fields instead of retrying or guessing from a plan name:
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-billable503 instead of guessing an entitlement or suggesting an upgrade:
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.