# Metric History

> Returns the full time-series history for a specific macroeconomic metric and country.

`GET https://api.bavest.co/v2/metrics/{metric_code}/history`

Group: Economic Indicators. Route id: `v2_metrics_metric_code_history`. Included in: Growth.

## Description

Returns the full time-series history for a specific macroeconomic metric and country. Supports cursor-based pagination for large result sets.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `metric_code` | path | string | yes | Metric code to retrieve history for. See EconomyMetricCode schema for all 63 available codes (e.g. CPI, GDP_REAL, UNEMPLOYMENT_RATE). One of `BUSINESS_CONFIDENCE_EU`, `EXPORT_ORDERS`, `IFO_BUSINESS_CLIMATE`, `IFO_EXPECTATIONS`, `CONSUMER_CONFIDENCE_US`, `GFK_CONSUMER`, `UMICH_SENTIMENT`, `CONSUMER_EXPENDITURE`, `HOUSEHOLD_CONSUMPTION_WB`, `PCE`, `RETAIL_SALES`, `ZEW_SENTIMENT`, `CRUDE_OIL_IMPORTS`, `CRUDE_OIL_STOCKS`, `DISTILLATE_PRODUCTION`, `DISTILLATE_STOCKS`, `GASOLINE_STOCKS`, `REFINERY_CRUDE_RUNS`, `REFINERY_UTILIZATION`, `EMPLOYED_PERSONS`, `INITIAL_CLAIMS`, `JOB_OPENINGS`, `LABOR_FORCE_PARTICIPATION`, `LABOR_FORCE_WB`, `NONFARM_PAYROLLS`, `UNEMPLOYMENT_ILO`, `UNEMPLOYMENT_RATE`, `UNEMPLOYMENT_WB`, `GDP_GROWTH_WB`, `GDP_NOMINAL`, `GDP_NOMINAL_WB`, `GDP_PER_CAPITA_WB`, `GDP_REAL`, `GDP_REAL_WB`, `GOVT_CONSUMPTION`, `BUILDING_PERMITS`, `CONSTRUCTION_PRICE_INDEX`, `HOME_PRICE_INDEX`, `HOUSE_PRICE_INDEX`, `HOUSING_STARTS`, `NEW_HOME_SALES`, `AVG_HOURLY_EARNINGS`, `INCOME_STATISTICS`, `PERSONAL_INCOME`, `INDUSTRIAL_PRODUCTION`, `MANUFACTURING_IP`, `CPI`, `CPI_WB`, `CPI_CORE`, `GDP_DEFLATOR`, `HICP`, `HICP_CORE`, `HICP_CORE_INDEX`, `HICP_INDEX`, `INFLATION_WB`, `PCE_PRICE_INDEX`, `PPI`, `PPI_FINAL_DEMAND`, `BOC_RATE`, `BOE_RATE`, `BOJ_RATE`, `BOK_RATE`, `DE_10Y_YIELD`, `DE_3M_RATE`, `ECB_DFR`, `ECB_MRR`, `FED_FUNDS`, `PBOC_RATE`, `POLICY_RATE`, `RBA_RATE`, `BUSINESS_INVESTMENT`, `GROSS_CAPITAL_FORMATION_WB`, `PRIVATE_INVESTMENT`, `DURABLE_GOODS_ORDERS`, `M2_PCT_GDP_WB`, `MONEY_SUPPLY_M1`, `MONEY_SUPPLY_M2`, `MONEY_SUPPLY_M3`, `EXPORTS_GOODS_SERVICES`, `IMPORTS_GOODS_SERVICES`, `TRADE_BALANCE`, `WHOLESALE_TRADE`. Example `CPI`. |
| `country` | query | string | yes | ISO 3166-1 alpha-2 country code (e.g. US, DE, JP) Example `US`. |
| `from` | query | string (date) | no | Start date for the time series (YYYY-MM-DD) |
| `to` | query | string (date) | no | End date for the time series (YYYY-MM-DD) |
| `source` | query | string | no | Filter by data source code (e.g. BLS, FRED, EUROSTAT) Example when explicitly filtering: `BLS`. |
| `vintage` | query | string | no | Vintage date for revision tracking. Returns the data as it was known on this date. Example when explicitly filtering: `2026-01-15`. |
| `cursor` | query | string | no | Pagination cursor (reference_period value from previous response's next_cursor). Use instead of from for subsequent pages. |
| `limit` | query | integer (int32) | no | Maximum number of observations to return per page (default 1000, max 1000) Default `1000`. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | MetricsHistoryResponse | no | Full time-series history for a macroeconomic metric in a single country. |
| `data.category` | string \| null | no | Metric category (e.g. inflation, gdp, employment) Example: `inflation`. |
| `data.country` | string | no | ISO 3166-1 alpha-2 country code. Example: `US`. |
| `data.from` | string (date) \| null | no | Earliest reference period in the returned data. Example: `2020-01-01`. |
| `data.to` | string (date) \| null | no | Latest reference period in the returned data. Example: `2026-02-01`. |
| `data.next_cursor` | string \| null | no | Cursor for the next page of results. Pass as the cursor query parameter to fetch the next page. Null when there are no more pages. Example: `2020-01-01`. |
| `data.metrics` | array of MetricsHistoryMetric | no | Metric time-series data (always a single-element array for the requested metric) |
| `data.metrics[].code` | string | yes | Machine-readable metric code. Example: `CPI`. |
| `data.metrics[].name` | string \| null | no | Human-readable metric name. Example: `CPI All Urban Consumers`. |
| `data.metrics[].frequency` | string \| null | no | Data release frequency (e.g. Monthly, Quarterly, Annual) Example: `Monthly`. |
| `data.metrics[].source` | string \| null | no | Data source code (e.g. BLS, FRED, EUROSTAT) Example: `BLS`. |
| `data.metrics[].count` | integer | yes | Number of observations in the data array. Example: `74`. |
| `data.metrics[].data` | array of MetricsHistoryObservation | yes | Time-series observations ordered by reference_period ascending. |
| `data.metrics[].data[].reference_period` | string (date) | yes | Reference period for the observation (YYYY-MM-DD) Example: `2026-02-01`. |
| `data.metrics[].data[].period_end` | string (date) \| null | no | End date of the observation period (for quarterly/annual data) |
| `data.metrics[].data[].value` | number (double) \| null | no | Observed metric value. Example: `326.785`. |
| `data.metrics[].data[].is_revised` | boolean | no | Whether this observation has been revised from a previously published value. Example: `false`. |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl 'https://api.bavest.co/v2/metrics/CPI/history?country=US' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "category": "inflation",
    "country": "US",
    "from": "1947-01-01",
    "to": "2026-08-01",
    "next_cursor": null,
    "metrics": [
      {
        "code": "CPI",
        "name": "CPI All Urban Consumers",
        "frequency": "Monthly",
        "unit": "INDEX_1982",
        "count": 956,
        "data": [
          {
            "reference_period": "2026-07-01",
            "period_end": null,
            "value": 333.918,
            "is_revised": false
          },
          {
            "reference_period": "2026-08-01",
            "period_end": null,
            "value": 334.98,
            "is_revised": false
          }
        ]
      },
      {
        "code": "CPI",
        "name": "CPI All Urban Consumers",
        "frequency": "Monthly",
        "unit": "INDEX_2015",
        "count": 841,
        "data": [
          {
            "reference_period": "2026-01-01",
            "period_end": null,
            "value": 2.3864,
            "is_revised": false
          },
          {
            "reference_period": "2026-02-01",
            "period_end": null,
            "value": 2.4141,
            "is_revised": false
          }
        ]
      }
    ]
  },
  "meta": {
    "parameters": {
      "metric_code": "CPI",
      "country": "US",
      "limit": "1000"
    },
    "time": 2022
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_metrics_metric_code_history
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt