---
title: "Inflation history API Reference | Narwhal API"
description: "Retrieve the current accepted inflation time series for one country. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/inflation-history"
---

# Inflation history API

Retrieve the current accepted inflation time series for one country.

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

## Endpoint and request

REST endpoint

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

Example request

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

MCP uses tool `economics_get_inflation_history` 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. |
| `start` | No | query · YYYY-MM | Inclusive first observation period. A year in `YYYY` format works only for countries served from World Bank annual data. A national series rejects it with `400 invalid_query`. |
| `end` | No | query · YYYY-MM | Inclusive last observation period. A year in `YYYY` format works only for countries served from World Bank annual data. A national series rejects it with `400 invalid_query`. |
| `limit` | No | query · integer, 1–1000 | Maximum number of periods returned. Defaults to 100. A page may contain fewer periods; follow next_cursor. |
| `cursor` | No | query · opaque string | The next_cursor from the previous page. |
| `version` | No | query · first_reported | Accepts `first_reported` only: returns the first stored value per period with `first_reported_at`. Cannot be combined with `as_of`. |
| `as_of` | No | query · YYYY-MM-DD | Returns the series as published through the end of the specified UTC day. Cannot be combined with `version`. |

## Response

Example response

```
{
  "country": "USA",
  "as_of": "2026-11-10T00:00:00Z",
  "observations": [
    {
      "period": "2026-07",
      "year_over_year": "3.4",
      "month_over_month": "0.0",
      "year_to_date": "3.0"
    },
    {
      "period": "2026-08",
      "year_over_year": "3.4",
      "month_over_month": "0.3",
      "year_to_date": "3.4"
    },
    {
      "period": "2026-09",
      "year_over_year": "3.7",
      "month_over_month": "0.6",
      "year_to_date": "4.0"
    },
    {
      "period": "2026-10",
      "month_over_month": "0.2",
      "year_to_date": "4.2"
    }
  ],
  "next_cursor": null
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. Returned once per page, not for each observation. |
| `start` | string | No | Present only when Narwhal moves the requested start to a later period. Earlier periods are not returned. |
| `as_of` | RFC 3339 timestamp | No | When the source last updated the newest observation on this page, in whole seconds, UTC. |
| `source` | object | No | Provenance for a statistic received through a distributor; see the latest-value operation. |
| `frequency` | string | No | Present, as `annual`, only for yearly World Bank history. Periods are then years in `YYYY` format. |
| `observations` | array | Yes | Oldest-first accepted observations, one per period. Missing source values are omitted, never filled. A page can hold fewer observations than limit; follow next_cursor until it is null. |
| `observations[].period` | string | Yes | The official month, quarter or year represented by the observation. |
| `observations[].first_reported_at` | RFC 3339 timestamp | No | Present only with `version=first_reported`, this UTC timestamp records when Narwhal first stored the period (the latest time if its measures were stored separately); periods released before capture began show Narwhal's first capture. |
| `observations[].year_over_year` | decimal string | No | Change from the same month one year earlier, in percent. |
| `observations[].month_over_month` | decimal string | No | Change from the previous month, in percent. |
| `observations[].year_to_date` | decimal string | No | Change from the prior December, in percent. Omitted when the publisher does not release it. |
| `observations[].calculated` | array of strings | No | Present only when Narwhal calculated a figure in this row from the publisher's own numbers because the publisher does not print it. Lists the calculated figures: `"year_over_year"`, `"month_over_month"` and `"year_to_date"`. A printed figure always wins over a calculated one. |
| `next_cursor` | string or null | Yes | Pass this unchanged as cursor to read the next page; null on the last page. |

## Errors and credits

- `400 invalid_query` — The country, period or filter format is invalid, or `as_of` and `version` are sent together.
- `400 invalid_cursor` — the cursor is malformed, or was issued for other filters or another operation.
- `401 invalid_api_key` — the Bearer key is missing or rejected.
- `404 series_not_found` — no approved observation matches the request.
- `409 cursor_expired` The pagination cursor is too old or the data behind it changed. Restart without the cursor.
- `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

By default, this route returns Narwhal's current accepted series; the response `as_of` is the update time of the newest observation. Any key can read an earlier vintage with `as_of` or `version=first_reported`. Vintage history starts at Narwhal's first capture and is not a reconstruction of every past publication.

Official sources can be sparse and expose different historical depths. Narwhal omits missing observations rather than interpolating or carrying values forward.

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`

Available official history follows this operation’s country coverage. The first available period varies by source.

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

Narwhal uses the World Bank only where no national, OECD, Eurostat or BIS series exists for the country. The history route returns yearly figures from the World Bank, World Development Indicators (CC BY 4.0). Periods are years in `YYYY` format, the response has `frequency` set to `annual`, and the `source` object names the publisher and the World Bank as distributor. World Bank figures are never joined to a national series.

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/NGA/inflation/observations?start=2024&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

Example response

```
{
  "country": "NGA",
  "as_of": "2026-10-08T00:00:00Z",
  "source": {
    "publisher": "International Monetary Fund (IMF), International Financial Statistics: consumer price index, annual average",
    "distributor": "World Bank, World Development Indicators (CC BY 4.0)"
  },
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "year_over_year": "33.2"
    },
    {
      "period": "2025",
      "year_over_year": "23.0"
    }
  ],
  "next_cursor": null
}
```

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?
