Data Vintages

How point-in-time data access works across providers.

Data Vintages

Macroeconomic data gets revised. GDP numbers published today will be revised next month and again the month after. If you're backtesting a trading strategy or validating a model, you need the data as it existed at a specific point in time, not the latest revised version.

Vintage capability by provider

Provider	Capability	How it works
FRED	Native	FRED's ALFRED service provides exact point-in-time snapshots going back to 1990.
BLS	Simulated	Built from BLS revision history. Reconstructs what was published as of a given date.
BEA	Simulated	Built from BEA revision history. Same reconstruction approach as BLS.
All others	Unavailable	Returns the current snapshot with a `fallbackReason` explaining the limitation.

Using vintages in API calls

Pass a vintage object when fetching observations or running forecasts:

{
  "vintage": {
    "mode": "specific",
    "date": "2024-06-15"
  }
}

If the provider doesn't support vintages, you still get data back, but the response's vintage audit object will have vintageCapability: "unavailable" and a fallbackReason explaining what happened.

Audit metadata

Every response that touches vintage data includes a vintage audit block:

{
  "vintage": {
    "mode": "specific",
    "date": "2024-06-15",
    "provider": "fred",
    "source": "fred/series/observations",
    "vintageCapability": "native",
    "fallbackReason": null
  }
}

Use vintageCapability to decide how much to trust the data for backtesting:

"native" - exact point-in-time data from the provider
"simulated" - reconstructed from revision history
"unavailable" - current snapshot, not a true vintage