---
title: "Gross Domestic Product history API Reference | Narwhal API"
description: "Retrieve the current accepted gross domestic product time series for one country. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/gdp-history"
---

# Gross Domestic Product history API

Retrieve the current accepted gross domestic product time series for one country.

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

## Endpoint and request

REST endpoint

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

Example request

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

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

## Parameters

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

| 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-QN | 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-QN | 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",
  "currency": "USD",
  "annualized": true,
  "as_of": "2026-10-29T00:00:00Z",
  "observations": [
    {
      "period": "2026-Q2",
      "value": "32563030000000"
    },
    {
      "period": "2026-Q3",
      "value": "33010036000000"
    }
  ],
  "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 | Who published the figure: the statistics office or central bank, for example `{"publisher": "Office for National Statistics"}`. Where the data reaches us through another body, `distributor` names that body too. If we cannot tell who published a figure, `source` is left out. |
| `frequency` | string | No | Present, as `annual`, only for yearly World Bank history. Periods are then years in `YYYY` format. |
| `seasonal_adjustment` | string or null | Yes | Whether the figure is seasonally adjusted, as the publisher states it: `seasonally_adjusted`, `not_seasonally_adjusted`, `calendar_adjusted` or `trend`. `null` means the publisher does not say. Never read `null` as adjusted. |
| `price_basis` | string or null | Yes | `current` for nominal GDP at current prices, or `constant` for real GDP at a reference year's prices. `null` means the publisher does not say. |
| `currency` | ISO 4217 string | Yes | The national currency for every value on the page, or USD for World Bank annual history. |
| `not_seasonally_adjusted` | `true` | No | Present, as true, only when the figures are not seasonally adjusted. |
| `annualized` | `true` | No | Present, as true, only when the figures are annualized. |
| `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[].value` | decimal string | Yes | The current-price GDP value. |
| `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, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, 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

165 Countries

`ABW, AFG, AGO, ALB, AND, ARE, ARM, ASM, ATG, AZE, BDI, BEN, BFA, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRB, BRN, BTN, BWA, CAF, CIV, CMR, COD, COG, COM, CPV, CRI, CUB, CUW, CYM, CYP, DJI, DMA, DOM, DZA, ECU, EGY, ERI, ETH, FJI, FRO, FSM, GAB, GEO, GHA, GIN, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUM, GUY, HKG, HND, HTI, HUN, IMN, IRN, IRQ, ISL, JAM, JOR, KAZ, KEN, KGZ, KHM, KIR, KNA, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MUS, MWI, NAM, NCL, NER, NGA, NIC, NPL, NRU, OMN, PAN, PER, PLW, PNG, PRI, PRY, PSE, PYF, ROU, RUS, RWA, SDN, SEN, SLB, SLE, SLV, SMR, SOM, SRB, SSD, STP, SUR, SVK, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, TJK, TKM, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, UZB, VCT, VEN, VIR, 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/gdp/observations?start=2024&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

Example response

```
{
  "not_seasonally_adjusted": true,
  "country": "NGA",
  "as_of": "2026-10-08T00:00:00Z",
  "source": {
    "publisher": "National statistical offices and central banks; OECD national accounts; World Bank staff estimates",
    "distributor": "World Bank, World Development Indicators (CC BY 4.0)"
  },
  "currency": "USD",
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "value": "252261880140"
    },
    {
      "period": "2025",
      "value": "290794361542"
    }
  ],
  "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?
