Economic releases API reference

List scheduled releases and retrieve immutable publication versions with their original schedule precision.

Request

Both operations use your Narwhal bearer key. Product overview →

List releases

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31&limit=25" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

GET /v1/economics/calendar/{release_id} retrieves one release. Add version_id to select a specific immutable version.

Parameters

Parameter	Rule
`countries`	Optional ISO alpha-3 codes. Repeat the query parameter for multiple countries; at most 50.
`start_date / end_date`	Optional inclusive date window. Defaults to 30 days before today through 335 days after today; span at most 366 days.
`view`	`view` is `compact` (default) for a compact entry per release, or `full` for the same object returned by `GET /v1/economics/calendar/{release_id}`. The full view includes every field: version, revision, schedule detail, value timestamps, seasonal adjustment and the value before revision.
`limit / cursor`	Page size 1–100, default 100. Continue with `next_cursor` and unchanged filters.
`release_id / version_id`	Release detail uses a UUID path ID and an optional UUID version ID.

Example response

Illustrative list response. The detail operation returns one release object with the same fields.

200 OK

{
  "status": "ok",
  "snapshot": "calendar-snapshot-20260914",
  "as_of": "2026-09-14T08:00:00Z",
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "series_id": "usa-consumer-prices",
      "country": "USA",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "title": "Consumer Price Index",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York"
    }
  ],
  "next_cursor": null
}

Field	Rule
`title / name`	`title` is the publisher's own title, in its own language and wording. `name` is Narwhal's standard English name from a closed list, such as `Producer prices` or `Labour force survey`, and contains no dates.
`series_id`	`series_id` is Narwhal's permanent ID for the series, shared by every edition, such as `tur-producer-prices`. It is absent when the series has not yet been classified.
`topic`	`topic` identifies what the series measures and is consistent across countries, such as `consumer_prices`, `labour_force`, `gdp`, `merchandise_trade` or `policy_rate`. It is absent when the series has not yet been classified, and new topics may be added.
`stage`	`stage` identifies which edition of a period's figures the release contains: `flash`, `advance`, `first`, `second`, `third`, `preliminary` or `final`. It is absent for a single-edition release.
`at / date / between / by`	One timing field appears once the day is known: `at` is the exact release time, `date` is the release day with no time set, `between` is an inclusive range of possible days as `[from, to]`, or `by` is the latest possible day, a deadline rather than a promised day. All timestamps are in UTC; `timezone` is the publisher's IANA time zone, and in the full view, `schedule.local_date` is the release day in that time zone.
`period / values`	`period` is the period the release covers. `values` appears once figures are published and contains `measure`, `unit`, `transformation`, `actual` and `previous`, with `currency` and `scale` for money amounts.

The list returns compact entries by default, and a field appears only when it has a value; pass view=full for every field. Research articles and repeated datasets that some publishers list beside their releases are not included.

Schedule and status meaning

family is one of gdp, prices, labour, trade, yield_curve, policy_rate, activity, survey, housing, money, or public_finance. status is scheduled, published, or cancelled.

Schedule precision is exact, date, estimated_range, deadline, or unknown. Preserve the source timezone and available bounds; a deadline is an upper date, not a promised publication day. observed_at and officially_published_at describe different events and can be null.

Cancellation and rescheduling remain explicit versions. Do not fill an unknown time with midnight.

Narwhal's calendar sources European Central Bank (ECB) and Bank of Canada release dates and times from their respective websites, where they are available free of charge. In every response, each ECB release includes a notice field citing the ECB and stating the information is available free of charge at https://www.ecb.europa.eu.

Release calendar coverage

Selected official release schedules are available for the countries below. Coverage varies by publisher and economic series; inclusion does not mean every indicator has a schedule. Filter the list request by country and date window to see the releases available in that snapshot.

Countries with release schedules · 35

An empty result means no releases are listed for that query in the snapshot. It does not guarantee that the publisher has no upcoming releases. Public holidays and bank closures are separate calendar datasets.

Values

Each release in the economic release calendar API includes an indicators array. Each indicator contains a figure printed by the publisher: actual for the release's own period and previous for the period before. Narwhal never computes these figures. The fields below describe the period, unit, transformation, and annualization of each figure.

Field	Rule
`period / previous_period`	`period` identifies the period covered: a month (`2026-08`), a quarter (`2026-Q3`), a week ending on a date (`2026-09-26`), or rolling three months (`2026-06/2026-08`, first and last month). `previous_period` is one step back in the same form. In weekly releases, a figure may cover the week before the release's own week, as with continuing jobless claims.
`unit`	`unit` is `percent`, `index` (with `index_base`, such as `2015=100`), `thousands`, `currency`, `ratio` (for example, a jobs-to-applicants ratio), or `balance` (a survey net balance in points, not a percentage).
`currency / scale`	`currency` (an ISO 4217 code) and `scale` (`units`, `thousands`, `millions`, `hundred_millions`, or `billions`) appear only when `unit` is `currency`. The figure uses the scale printed by the publisher.
`transformation`	`transformation` is `level`, `month_over_month`, `year_over_year`, `quarter_over_quarter`, `three_month_on_three_month`, or `change` (a difference in levels, expressed in thousands, such as employment change).
`annualization`	`annualization` is always present: `annualized` (for example, U.S. GDP growth at an annual rate) or `not_annualized`.
`actual / previous`	`actual` is the figure for the release's own period; `previous` is the figure for the period before. Both are printed by the publisher, never computed by Narwhal. `previous` may be `null` if the release does not state it; the next release then carries the earlier `actual` as its `previous`.

New values for these fields may be added over time, so clients should accept values they do not recognize.