Merchandise trade history API

Retrieve the current accepted merchandise trade time series for one country.

economics_get_trade_history is available through REST and the economics_get_trade_history MCP tool. Both return the same data shape and consume the same monthly quota.

Endpoint and request

REST endpoint

GET /v1/economics/{country}/trade/observations

Example request

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

MCP uses tool economics_get_trade_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: AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP, and USA.
`start`	No	query · YYYY-MM	Inclusive first observation period.
`end`	No	query · YYYY-MM	Inclusive last observation period.
`limit`	No	query · integer, 1–1000	Maximum observations returned. Defaults to 100.
`cursor`	No	query · opaque string	The next_cursor from the previous page.

Response

Example response

{
  "observations": [
    {
      "country": "USA",
      "measure": "trade_exports",
      "value": "189000000000",
      "unit": "USD",
      "transformation": "",
      "period": "2026-06"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T16:00:00Z"
}

Field	Type	Required	Meaning
`observations`	array	Yes	Oldest-first accepted observations. Missing source values are omitted, never filled.
`observations[].country`	string	Yes	The requested uppercase ISO alpha-3 country code.
`observations[].measure`	string	Yes	The canonical measure represented by this observation.
`observations[].period`	string	Yes	The official month or quarter represented by the observation.
`observations[].value`	decimal string	Yes	The accepted source value without binary floating-point conversion.
`observations[].unit`	string	Yes	The source unit or currency code for the measure.
`observations[].transformation`	string	Yes	The measure transformation, or an empty string for a level.
`next_cursor`	string or null	No	Pass this unchanged as cursor to read the next page.
`as_of`	RFC 3339 timestamp	No	When Narwhal accepted the current stored series snapshot.

Errors and quota

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 quota_exhausted — the account has reached its monthly allowance.
503 economics_unavailable — Narwhal cannot safely serve an accepted publication.

Only a successful data response consumes quota. See all errors, headers, and retry rules.

Freshness

This route returns Narwhal's current accepted series as of as_of. It is current-vintage history, not a reconstruction of every past publication vintage.

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.

Current public-beta coverage

Available official history is public for AUS, CAN, DEU, FRA, GBR, JPN, MYS, NLD, SGP, and USA. The first available period varies by source.

Indonesia, regional routes, and Commodities are not public. Current FX is available through the separate FX API.

Return to all Economics operations.