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

# GDP growth history API

Retrieve the current accepted gdp growth time series for one country.

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

## Endpoint and request

REST endpoint

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

Example request

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

MCP uses tool `economics_get_gdp_growth_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",
  "as_of": "2026-10-29T00:00:00Z",
  "observations": [
    {
      "period": "2026-Q2",
      "year_over_year": "2.2",
      "quarter_over_quarter": "0.6",
      "calculated": [
        "quarter_over_quarter"
      ]
    },
    {
      "period": "2026-Q3",
      "year_over_year": "2.1",
      "quarter_over_quarter": "0.8",
      "calculated": [
        "quarter_over_quarter"
      ]
    }
  ],
  "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. `mixed` means the two growth figures are on different bases. Japan is one example: its year on year growth is not adjusted, and its quarter on quarter growth is. |
| `year_over_year_seasonal_adjustment` | string or null | Yes | The basis of each growth figure on its own, using the same values. They are filled only when `seasonal_adjustment` is `mixed`. Otherwise, or where the release does not state that figure's basis, they are `null`. |
| `quarter_over_quarter_seasonal_adjustment` | string or null | Yes | The basis of each growth figure on its own, using the same values. They are filled only when `seasonal_adjustment` is `mixed`. Otherwise, or where the release does not state that figure's basis, they are `null`. |
| `annualization` | string or null | Yes | Whether quarter on quarter growth is annualized: `annualized` or `not_annualized`. It is `null` when the answer has no quarter on quarter figure. Year on year growth is never annualized. |
| `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. |
| `year_over_year_not_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases and whose year-over-year figure is not seasonally adjusted. |
| `quarter_over_quarter_not_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases and whose quarter-over-quarter figure is not seasonally adjusted. |
| `seasonally_adjusted` | `true` | No | Present, as true, only when both figures are recorded as seasonally adjusted. |
| `year_over_year_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases and whose year-over-year figure is seasonally adjusted. |
| `quarter_over_quarter_seasonally_adjusted` | `true` | No | Present, as true, only for a country that mixes bases and whose quarter-over-quarter figure is seasonally adjusted. |
| `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 | Real change from the same quarter one year earlier, in percent. |
| `observations[].quarter_over_quarter` | decimal string | No | Real change from the previous quarter, in percent, not annualized. |
| `observations[].year_to_date` | decimal string | No | Real change for the year to date, 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"` and `"quarter_over_quarter"`. 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, 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-growth/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)"
  },
  "frequency": "annual",
  "observations": [
    {
      "period": "2024",
      "year_over_year": "4.1"
    },
    {
      "period": "2025",
      "year_over_year": "4.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?
