---
title: "CPI API — Consumer Price Index Reference | Narwhal API"
description: "Retrieve the headline consumer price index for one country and month. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/cpi"
---

# Consumer Price Index (CPI) API

Retrieve the headline consumer price index for one country and month.

`economics_get_cpi` is available through REST and the `economics_get_cpi` MCP tool. Both return the same data shape and use the same credit.

## Endpoint and request

REST endpoint

```
GET /v1/economics/{country}/cpi
```

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/cpi?period=2026-07" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

MCP uses tool `economics_get_cpi` with the corresponding arguments below.

## Parameters

The accepted period format for this operation is `YYYY-MM`.

| Name | Required | Type | Meaning |
| --- | --- | --- | --- |
| `country` | Yes | path · ISO alpha-3 | One supported uppercase country code; see this operation’s coverage list. |
| `period` | No | query · YYYY-MM | Omit it for the latest accepted complete release, or pass one exact period. |
| `version_id` | No | query · UUID | Optional immutable publication version. Use `resource_version` from a `dataset.published` or `dataset.revised` event; omit to read the current admitted indicator. |

## Response

Example response

```
{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "index_base": "1982-84=100",
  "released_on": "2026-11-10"
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. |
| `period` | string | Yes | The official observation period returned. |
| `value` | positive decimal string | Yes | The headline index level. |
| `index_base` | string | Yes | Base period and base value of the index, for example 1982-84=100. |
| `released_on` | date | Yes | The official publication date, not Narwhal's retrieval time. |
| `source` | object | No | The optional `source` object appears only when the statistic is received through a distributor. It contains `publisher` (the original publisher named by the distributor) and `distributor` (the distributing organisation). When `source` is present, `released_on` is the distributor's publication date, not the original publisher's release date. Publisher-direct series omit `source`. |

## Errors and credits

- `400 invalid_query` — the country, period, or filter format is invalid.
- `401 invalid_api_key` — the Bearer key is missing or rejected.
- `404 series_not_found` — no approved observation matches the request.
- `429 rate_limit_exceeded` — the network or account short-window limit was reached; retry after `Retry-After`.
- `402 insufficient_credits` — your balance does not cover the call.
- `503 economics_unavailable` — Narwhal cannot safely serve an accepted publication.

Only a successful data response costs credit. See [all errors, headers, and retry rules](https://narwhalapi.com/docs/errors.md).

## Freshness

Omitting `period` returns Narwhal's latest stored accepted release. The API call reads Narwhal's database; it does not call the official publisher live.

`released_on` is the official publication date.

Read [how source checks, validation, stored releases, and failed checks work](https://narwhalapi.com/docs/freshness.md).

## Current public-beta coverage

35 Countries

`AUS, AUT, BEL, CAN, CHE, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA`

Headline national CPI coverage follows the country list below. For euro area countries this is the national index, not the Eurostat HICP, so figures can differ from Eurostat's. For Australia this is the monthly CPI, not the quarterly CPI, so a month's rate can differ from the quarter's.

### Annual World Bank history

126 Countries

`ABW, AFG, AGO, ALB, ARM, ATG, AZE, BDI, BEN, BFA, BHR, BHS, BIH, BLR, BLZ, BOL, BRB, BRN, BTN, BWA, CAF, CIV, CMR, COD, COG, COM, CPV, CRI, CUW, CYM, DJI, DMA, DOM, ECU, EGY, ETH, FJI, FSM, GAB, GEO, GHA, GIN, GMB, GNB, GNQ, GRD, GTM, GUY, HND, HTI, IRN, IRQ, JAM, JOR, KAZ, KEN, KGZ, KHM, KIR, KNA, LAO, LBN, LBR, LBY, LCA, LKA, LSO, MAC, MDA, MDG, MDV, MLI, MMR, MNE, MNG, MOZ, MRT, MUS, MWI, NAM, NCL, NER, NGA, NIC, NPL, OMN, PAN, PLW, PNG, PRY, PSE, RUS, RWA, SDN, SEN, SLB, SLE, SLV, SMR, SSD, STP, SUR, SWZ, SXM, SYC, SYR, TCD, TGO, TJK, TLS, TON, TTO, TUN, TZA, UGA, UKR, URY, UZB, VCT, VEN, VNM, VUT, WSM, YEM, ZMB, ZWE`

These countries have no latest-value route. A request to this route returns `404 series_not_found`; read the history route instead.

### Monthly BIS history

17 Countries

`ARE, BGR, CYP, DZA, GRC, HKG, HUN, ISL, KWT, MAR, MKD, MLT, PER, ROU, SRB, SVK, TUR`

These countries have no latest-value route. A request to this route returns `404 series_not_found`; read the history route instead.

Indonesia and regional Economics routes are not public. Daily FX is available through the [FX API](https://narwhalapi.com/api/fx.md).

Return to [all Economics operations](https://narwhalapi.com/docs/api/economics.md).

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)

Was this page helpful?
