> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macrobymark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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