Data freshness

The GET /v1/freshness endpoint returns the most recent refresh-runner snapshot for every state we serve. It’s a public endpoint (no API key required) — the data is operational transparency, not anything sensitive.

Endpoint

GET https://api.taxql.com/v1/freshness

No authentication. Same posture as /healthz.

Response shape

{
  "generated_at": "2026-06-14T16:12:01",
  "states": [
    {
      "code": "tx",
      "name": "Texas",
      "klass": "auto",
      "status": "ok",
      "last_fetch": "2026-06-10",
      "source_period": "2026Q2",
      "rows": 56440
    },
    {
      "code": "az",
      "name": "Arizona",
      "klass": "reload",
      "status": "stale",
      "last_fetch": "2026-05-01",
      "source_period": "2026Q2",
      "rows": 720
    }
  ]
}

Per-state fields

Field	What it means
`code`	2-letter state code (lowercase).
`name`	Full state name (also DC).
`klass`	`auto` (fetched daily), `reload` (manual file drop), `static` (statutory base; never re-fetched), `maintenance` (known upstream outage; serving last good data).
`status`	Runner’s outcome at the last refresh: `ok` / `changed` / `stale` / `failed` / `static` / `maintenance` / `anchor_regression`.
`last_fetch`	ISO date of the freshest source file on disk for this state.
`source_period`	Derived quarter label (`YYYYQN`) from the freshest currently-effective rate row.
`rows`	Row count after the refresh. Quick sanity for “did anything land”.

Status field

ok / changed: refresh succeeded; changed means rates moved since the previous snapshot.
stale: the source file on disk is older than the runner’s threshold (5 days for auto, 40 days for reload).
failed: the load step errored. We’re serving the previous snapshot’s data, but the next refresh will need attention.
anchor_regression: a pinned validation anchor for this state diverged from its expected value after the load. The structural fix layer (P0-1b corrections-as-overrides) typically resolves these before they reach this surface.
static: the state’s rate is a statutory baseline (Delaware, Montana, New Hampshire, Oregon, plus DC and a few partial-tax states). There’s no source file to age, so it’s never stale.
maintenance: a known upstream outage. We’re serving the last good data and the operator is aware.

When to consume this

Status pages: render the per-state status on your own dashboard so internal teams can see at a glance whether a state’s rate data is current.
Monitoring: poll periodically (suggested cadence: hourly) and alert on failed or anchor_regression for states you care about.
Decisioning: if your business is highly sensitive to a particular state’s rate, check source_period before relying on the rate for a quarterly close.