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_refreshed_at": "2026-06-14T03:00:12+00:00",
      "effective_through": "2026-04-01",
      "last_fetch": "2026-06-10",
      "source_period": "2026Q2",
      "rows": 56440
    },
    {
      "code": "ia",
      "name": "Iowa",
      "klass": "auto",
      "status": "ok",
      "last_refreshed_at": "2026-06-14T03:00:12+00:00",
      "effective_through": "2024-01-01",
      "last_fetch": "2024-01-01",
      "source_period": "2024Q1",
      "rows": 1214
    }
  ]
}

Per-state fields

Field	What it means
code	2-letter state code (lowercase).
name	Full state name (also DC).
klass	auto (re-fetched on the weekly refresh, Sunday 03:00 UTC), reload (manual file drop), static (statutory base; never re-fetched).
status	Runner’s outcome at the last refresh: ok / changed / stale / failed / static / maintenance / anchor_regression / manual / unknown.
last_refreshed_at	ISO timestamp of when the pipeline last successfully refreshed this state (the scheduled run). Answers “did we run?” — not how old the data is.
effective_through	ISO date of the newest effective rate the data reflects. Answers “how old is the data?” — not whether we ran. Read it against last_refreshed_at: a recent last_refreshed_at with an old effective_through means we refreshed on schedule and the source simply hasn’t published anything newer (e.g. a state whose local rates haven’t moved in years).
last_fetch	ISO date of the freshest source file on disk for this state (legacy; prefer last_refreshed_at for run time and effective_through for data age).
source_period	The effective_through signal as a YYYYQN quarter label. Populated for every state (including CA/FL/TX/WA, which read null before 2026-08-14).
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: our last successful source fetch for this state is older than its refresh-class threshold (5 days for auto, 40 for reload), or a shared upstream feed it depends on has drifted. It is a refresh-pipeline age signal — “we haven’t reloaded recently” — not a comparison against the publisher’s newest edition (see the note below).
• failed: the load step errored. We’re serving the previous snapshot’s data, but the next refresh will need attention.
• manual: a manually-loaded state (e.g. AZ, NM) whose currency is operator-attested rather than runner-fetched.
• unknown: the state hasn’t been through the refresh runner yet, so there’s no recorded outcome to report.
• 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.

What this endpoint does NOT tell you

status reflects TaxQL’s refresh pipeline — did the scheduled load run, and how recent is the loaded data. It is not a per-edition check that our rate equals the publisher’s newest release. That edition-level currency is monitored internally, and for a few states it is genuinely unevaluable — the publisher exposes no cheap edition marker (e.g. FL, LA, VA) — so we never present those as “confirmed current” here. Canada provinces are not included in this endpoint. Treat a green status as “the pipeline is healthy and the data is recent for its class,” not as a guarantee it matches the authority’s latest bulletin.

When to consume this

• Status pages: render the per-state refresh status on your own dashboard so internal teams can see at a glance whether the refresh pipeline ran and how recent the loaded data is.
• 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.

Note

The endpoint reflects the most recent successful refresh. auto-class states re-fetch on the weekly Sunday run, so generated_at is normally within the last seven days. If it’s more than a week or two old, the weekly refresh may have missed a cycle — please reach out.