Data freshness
Narwhal stores accepted official releases, then serves them without calling the source during your API request.
Fresh means the latest complete official release that Narwhal has validated and published. It does not mean that each customer request calls the official source live.
Where responses come from
Each successful REST or MCP request reads Narwhal's stored current publication. Source websites, files, and APIs are checked separately by the ingestion system.
This keeps customer response time independent from an official source's speed or temporary outage.
How releases are updated
- A scheduled worker checks the official source for a new release.
- Narwhal retrieves the source material and validates its identity, period, fields, and completeness.
- The normalized observations and supporting evidence are stored together.
- Only after the whole release passes does Narwhal make it the version returned to customers.
An incomplete or invalid candidate is never mixed into the public response.
What freshness fields mean
| Field or signal | Meaning |
|---|---|
period | The month, quarter, or year represented by the official observation. |
released_on | The official publication date. It is not Narwhal's retrieval or publication time. |
| Latest request | Omitting period requests the latest accepted complete release currently stored by Narwhal. |
| Exact-period request | Passing period requests that exact published period when it remains available in the current official release. |
Public beta responses do not currently expose a Narwhal ingestion timestamp. Use the official release calendar and contact support with a request ID if a known release appears delayed.
When a source check fails
Narwhal keeps the last accepted publication available. It does not erase it, replace missing values with zero, or publish a partial update.
A failed source check is retried on its schedule. If Narwhal cannot safely serve an accepted publication, the request fails with a documented 503 problem instead of returning uncertain data.
Public-beta expectations
- Narwhal does not promise a fixed source-to-publication delay during beta.
- Customer API latency measures reading stored data, not the time required to ingest a new official release.
- Official agencies can revise a period; a later accepted publication can therefore replace its previously stored value.
Continue with the Economics API reference or review errors and retries.