Browse all documentation

Economic releases API reference

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

Request

Browse the economic release calendar →

Both operations use your Narwhal bearer key. Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. 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

ParameterRule
countriesOptional ISO alpha-3 codes. Repeat the query parameter for multiple countries; at most 50.
start_date / end_dateOptional inclusive date window. Defaults to 30 days before today through 335 days after today; span at most 366 days.
limit / cursorPage size 1–100, default 100. Continue with next_cursor and unchanged filters.
release_id / version_idRelease detail uses a UUID path ID and an optional UUID version ID.

404 not_found for an unknown release_id. A malformed, tampered or filter-mismatched cursor returns 400 invalid_cursor. A cursor older than 30 minutes or an unavailable snapshot returns 409 cursor_expired. Restart without the expired cursor.

Example response

Illustrative list response. The detail operation returns one release object with the same fields plus version and observed_at.

200 OK
{
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "revision": 0,
      "country": "USA",
      "series_id": "usa-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}
FieldRule
namename is Narwhal's standard English name from a closed list, such as Producer prices or Labour force survey, and contains no dates.
series_idseries_id is Narwhal's permanent ID for the series, shared by every edition, such as tur-producer-prices. It is a slug, not a UUID, so /v1/economics/series/* routes do not accept it. It is absent when the series has not yet been classified.
topictopic 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.
stagestage 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 / byNo timing field appears when the date is unknown or an estimated range has only a lower bound. 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, not a promised day. All timestamps are in UTC; timezone is the publisher's IANA time zone.
period / valuesperiod is the period the release covers, at the level of detail the publisher provides: 2026-09 (month), 2026-Q3 (quarter), 2018-04/2018-06 (rolling range), 2026-09-12 (day or week), or 2025 (year). It is absent when the publisher states none. values is always present and is empty until figures are published; see Values below.
date_basisdate_basis is indicative when the date comes from a third-party calendar and not from the publisher. An indicative date can still move. It is absent when the publisher or the central bank set the date. The publisher's date always wins over the third-party calendar.
meetingmeeting is set on a central bank's policy meeting and holds the meeting's days from the bank's own calendar. kind is scheduled (the date is on the bank's calendar for the year), unscheduled or extraordinary. starts_on is the first day of a multi-day meeting, when the bank gives it, and ends_on is the last day, the day the decision is announced.
revision / version / observed_atrevision increases each time the release's details change. It is 0 if the release has never been revised. GET /v1/economics/calendar/{release_id} also returns version, the immutable version to pass back as version_id, and observed_at, when Narwhal last observed the release in the publisher's calendar.

A field appears only when it has a value. 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.

Timing uses the top-level at, date, between, or by field. Preserve timezone and the available bounds; by is a deadline, not a promised publication day. observed_at is when Narwhal last observed the release in the publisher's calendar.

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.

Consensus, indicative dates and central bank meetings

Besides the publishers' own schedules, the calendar carries a third-party calendar. It adds a consensus forecast to figures, dates for releases the publishers do not list, and the days of central bank policy meetings. The publisher's date and figure always win over the third-party calendar.

This request returns the Bank Indonesia policy rate decision with a meeting object and a consensus on each rate, and a bank lending release whose date is indicative. Nothing is published yet, so actual is absent.

Policy rate meeting and indicative date
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=IDN&start_date=2026-11-18&end_date=2026-11-18" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "7c9f64b5-bc4c-4875-9757-a5a3be9796dd",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "date": "2026-11-18",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "deposit_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5",
          "consensus": "5"
        },
        {
          "measure": "lending_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "6.5",
          "consensus": "6.75"
        },
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5.75",
          "consensus": "6"
        }
      ],
      "meeting": {
        "kind": "scheduled",
        "ends_on": "2026-11-18"
      }
    },
    {
      "release_id": "ff160cc0-f950-4bde-8f98-73dbb6ff6423",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-bank-lending",
      "name": "Bank lending",
      "topic": "money_credit",
      "family": "money",
      "period": "2026-10",
      "status": "scheduled",
      "date_basis": "indicative",
      "at": "2026-11-18T07:30:00Z",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "bank_credit_yoy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "13.26"
        }
      ]
    }
  ],
  "next_cursor": null
}

After a decision, a figure from the third-party calendar shows as provisional until the publisher's own release confirms it. This answer is the Bank Negara Malaysia decision of 5 November 2026.

Provisional figure
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=MYS&start_date=2026-11-05&end_date=2026-11-05" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
200 OK
{
  "releases": [
    {
      "release_id": "007f2565-07af-43df-b778-0abef890689a",
      "revision": 1,
      "country": "MYS",
      "series_id": "mys-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "published",
      "date_basis": "indicative",
      "at": "2026-11-05T07:00:00Z",
      "timezone": "Asia/Kuala_Lumpur",
      "values": [
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "actual": "2.75",
          "previous": "2.75",
          "consensus": "2.75",
          "provisional": true
        }
      ]
    }
  ],
  "next_cursor": null
}

Treat date_basis: indicative and provisional as signs that a date or a figure can still change.

Release calendar coverage

The calendar covers 114 countries as of 13 November 2026. Official release schedules from statistical offices and central banks come first. A third-party calendar adds countries and releases that the publishers do not list in a form Narwhal can read. A date that comes only from the third-party calendar carries date_basis indicative. 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 in the calendar · 114

AGO ALB ARE ARG ARM AUS AUT AZE BEL BGD BGR BHR BIH BLR BRA BWA CAN CHE CHL CHN COL CPV CRI CYP CZE DEU DNK DOM ECU EGY EMU ESP EST FIN FRA GBR GEO GHA GRC GTM HKG HRV HUN IDN IND IRL ISL ISR ITA JAM JOR JPN KAZ KEN KGZ KOR LBN LKA LSO LTU LUX LVA MAC MAR MDA MEX MKD MLT MNE MNG MOZ MUS MWI MYS NAM NGA NLD NOR NZL OMN PAK PER PHL PNG POL PRT PRY PSE ROU RUS RWA SAU SGP SLV SRB SUR SVK SVN SWE SWZ SYC THA TUN TUR TWN UGA UKR URY USA UZB VNM ZAF ZMB ZWE

Countries with a release calendar page · 114

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. Central bank meeting dates are served in this calendar as meeting. Public holidays, including bank holidays, and exchange closures are separate calendar datasets: see the public holidays reference and the exchange closures reference.

Values

Each release in the economic release calendar API includes a values array, empty until figures are published. Each value is a figure printed by the publisher: actual for the release's own period and previous for the period before. An actual that comes from a third-party calendar is marked provisional. Narwhal never computes these figures.

Illustrative published values
{
  "values": [
    {
      "measure": "producer_price_change_mom",
      "unit": "percent",
      "transformation": "month_over_month",
      "actual": "0",
      "previous": "0.1",
      "previous_revised_from": "0.2"
    }
  ]
}
FieldRule
measuremeasure identifies the figure within the release, such as producer_price_change_mom.
conceptconcept names what a figure measures, such as gdp or cpi, so the same figure has the same concept in every country. Read it with transformation and annualization to compare like with like.
noticenotice contains source terms that the publisher requires with each access, such as the ECB's. Show it with the release. It is absent when there are no such terms.
periodperiod appears only when the value covers a different period from the release period, as with continuing jobless claims, which cover the week before the release's own week.
unitunit is percent (a value of 1.2 means 1.2%), 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 / scalecurrency (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.
transformationtransformation is 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). It is absent for a level.
annualized / not_seasonally_adjustedannualized is true when the figure is at an annual rate, as with U.S. GDP growth. not_seasonally_adjusted is true when the figure is not seasonally adjusted. If annualized is absent, the figure is not annualized. If not_seasonally_adjusted is absent, the figure is seasonally adjusted, or, on a figure from a third-party calendar, the source does not say.
actual / previousactual 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. A figure the release does not state is absent; the next release then carries the earlier actual as its previous.
consensusconsensus is the expected figure for the period, from a third-party calendar. It is a forecast and not a published figure. It is absent when no forecast is known, and it can appear on a value whose actual the publisher printed.
provisionalprovisional is true when actual has not been confirmed by the publisher's own release. The figure comes from a third-party calendar and can change when the publisher publishes. It is absent otherwise.
previous_revised_fromprevious_revised_from is the earlier figure as first printed, when this release revised previous.
value_statusvalue_status appears only when actual is missing: pending_capture after the scheduled time until the figure is captured, or unavailable when the release was published or cancelled without that figure.

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

Was this page helpful?