---
title: "Dataset-wide freshness for NHL player props"
method: GET
path: "/v1/nhl/props/freshness"
tags: ["nerd"]
---

# Dataset-wide freshness for NHL player props

`GET /v1/nhl/props/freshness`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/nhl/props/freshness`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Answers "is the NHL props dataset live right now" with no player or
market, for a build-time reader (e.g. marketing copy) that cannot
supply either. Returns the SAME `freshness` shape documented on
`GET /v1/nhl/players/{player_id}/props`, derived from
`MAX(fetched_at)` across every held NHL prop line rather than one
player's line: `data_as_of`, `age_days`, `status`
(`live` ≤2d, `recent` ≤14d, `stale` >14d, or `no_data` when the table
is empty), and `note`. A page reading this can never claim `live`
while the per-player endpoint would call the same data `stale`.

## Response `200`

ok

- object

## Other responses

- `503`: Service temporarily unavailable (`503`). Returned when a backing query exceeds the endpoint's `statement_timeout` (Postgres cancels it) instead of holding the connection for seconds. Transient under heavy load; retry after a short delay. Standard error envelope with `error.code = upstream_unavailable`.

---

[API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/31fb54ac414e?raw)