Make your first economics request

Keep the key out of the URL

Store your Narwhal key as a secret or environment variable. Send it in the Authorization header as a Bearer token. Do not put it in a query string, commit it to a repository, or expose it in browser code.

Call the CPI endpoint

Omit the period to retrieve the latest accepted complete release.

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

Read the response

The response is typed JSON without a generic data wrapper. Decimal values are strings so clients do not silently lose precision. Missing values stay missing; they do not become zero.

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "base_period": "1982-84",
  "base_value": "100",
  "released_on": "2026-08-12"
}

Change the country or operation

Replace USA with a country code listed for the operation in the coverage matrix. Then replace cpi with another documented operation path for inflation, unemployment, labour-force participation, GDP, GDP growth, trade, exports, or imports. Coverage can differ between those operations.

Handle errors by status and code

A 400 response means the request is invalid. A 401 means the API key is missing or invalid. A 404 means the requested route or series is not available. A 429 means the quota is exhausted. A 503 means the requested data or service cannot be served safely at that moment.

Error bodies use application/problem+json and include a request ID. Retry 500 and 503 responses with bounded backoff. Fix 400 and 401 responses before trying again, and wait for the documented reset before retrying a 429.

REST and MCP use the same data

The MCP tools use the same key, stored publications, response schemas, and data quota as REST. Choose the interface that fits your application; the underlying economic data is the same.

Request a bounded history page

Use the matching history route when you need more than the latest release. Keep country, start, end, and limit unchanged while paging, and pass the returned next_cursor as the cursor for the next request. If the cursor expires or the publication is withdrawn, restart without it. An empty valid range is different from an unavailable series and should remain empty in your application.

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