---
title: "Inflation API Reference | Narwhal API"
description: "Retrieve year-over-year, month-over-month, and year-to-date inflation for one month. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/inflation"
---

# Inflation API

Retrieve year-over-year, month-over-month, and year-to-date inflation for one month.

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

## Endpoint and request

REST endpoint

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

Example request

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

MCP uses tool `economics_get_inflation` 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",
  "year_over_year": "3.4",
  "month_over_month": "0.0",
  "year_to_date": "3.0",
  "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. |
| `year_over_year` | decimal string | Yes | Change from the same month one year earlier, in percent. |
| `month_over_month` | decimal string | No | Change from the previous month, in percent. Left out where the publisher releases only the year-over-year figure. |
| `year_to_date` | decimal string | No | Change from the prior December, in percent. Omitted when the publisher does not release it. |
| `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`. On a newest figure read from the publisher's own release, `source` is `{"publisher": "..."}` with no distributor, and `released_on` is the publisher's local release day. |
| `stage` | string | No | Appears only on a newest figure read from the publisher's release. Which reading of the figure this is: `flash`, `advance`, `first`, `second`, `third`, `preliminary` or `final`. |
| `published_at` | RFC 3339 timestamp | No | Appears only on a newest figure read from the publisher's release. When the publisher released the figure. |
| `provisional` | `true` | No | Present, as true, only when the figure read from the release is marked provisional. |
| `calculated` | array of strings | No | Present only when Narwhal calculated a figure from the publisher's own numbers because the publisher does not print it. Lists the calculated figures: `["year_over_year"]`, `["month_over_month"]` or both. A printed figure always wins over a calculated one. A stored answer can carry it too, not only an answer read from the release. |

### Newest figure read from the release

The newest answer can come from Narwhal's own read of the statistics office's release, before the stored series has it. Such an answer adds `source`, `stage`, `published_at` and `provisional` (only when true). An answer with none of these fields is the stored value. A stored answer can also carry `calculated`, which lists the figures Narwhal calculated from the publisher's own numbers.

Inflation also answers the newest figure for a country that has no stored series. It has no history: a `period` or `version_id` request for such a country returns `404 series_not_found`.

Where a stored series reaches Narwhal through a distributor, the statistics office's own printed figure for the same period replaces it. The answer then names the office as the source and no distributor.

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/GRC/inflation" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

Example response

```
{
  "country": "GRC",
  "period": "2026-10",
  "year_over_year": "5.7",
  "released_on": "2026-11-10",
  "source": {
    "publisher": "Hellenic Statistical Authority"
  },
  "stage": "final",
  "published_at": "2026-11-10T10:00:00Z"
}
```

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

The newest figure can be shown as soon as the publisher releases it, from Narwhal's read of the release. Until the stored series has the same period, the answer carries the read fields described above.

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

## Current public-beta coverage

36 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, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA`

National inflation coverage follows the country list below; year-to-date availability follows each source contract. 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. A country with no stored series can still answer the newest figure from the publisher's release: it has no history, so a period or version_id request for it returns 404 series_not_found.

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

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?
