All APIs

Economic calendar API

Track scheduled economic releases and their publication status. Build a release calendar for GDP, prices, labour, trade, and yield curves without treating uncertain schedules as exact times.

Online94.13% uptime, last 30 days674 ms typical response

First request

List the releases in a month

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Example response
{
  "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
}

Find a central bank rate decision

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-12-09&end_date=2026-12-09" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
Example response
{
  "releases": [
    {
      "release_id": "52e78613-4f51-4cc8-b8dd-a4c3cc798c50",
      "revision": 1,
      "country": "USA",
      "series_id": "usa-monetary-policy-press-conference",
      "name": "Monetary policy press conference",
      "topic": "policy_communication",
      "family": "policy_rate",
      "status": "scheduled",
      "at": "2026-12-09T19:30:00Z",
      "timezone": "America/New_York",
      "values": []
    },
    {
      "release_id": "ed7bb0f9-6b9b-4e27-9b43-d891742ec3d4",
      "revision": 1,
      "country": "USA",
      "series_id": "usa-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "at": "2026-12-09T19:00:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}

Calendar subscriptions

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'
Example response
{
  "subscription_id": "00000000-0000-4000-8000-000000000301",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2027-10-22T09:00:00Z"
}

Endpoints

GETList releases/v1/economics/calendar

List releases in a date window.

Parameters

  • countriesoptional

    ISO alpha-3 codes, such as USA. Repeat the parameter for several countries, at most 50.

  • start_dateoptional

    First day of the window. The window starts 30 days before today by default.

  • end_dateoptional

    Last day of the window. It ends 335 days after today by default. The window spans at most 366 days.

  • limitoptional

    Releases per page, 1 to 100. The default is 100.

  • cursoroptional

    Continue with next_cursor and the same filters.

Each release in the list

  • release_idstring

    The release to read in detail.

  • namestring

    Narwhal’s standard English name, such as Producer prices. It contains no dates.

  • topicstring

    What the series measures, the same in every country, such as consumer_prices or gdp.

  • periodstring

    The period the release covers, such as 2026-09 or 2026-Q3.

  • statusstring

    Where the release stands, such as scheduled.

  • at / date / between / bystring

    The timing the publisher gave: an exact time, a day, a range of days or a deadline. None appears when the date is unknown.

  • valuesarray

    The published figures. The array is empty until they are out.


Full reference →
GETGet one release/v1/economics/calendar/{release_id}

Read a release, optionally selecting version_id.

Parameters

  • release_idrequired

    The release’s UUID.

  • version_idoptional

    The UUID of an earlier version. Without it you get the current one.

The release

  • versionstring

    The immutable version, which you can pass back as version_id.

  • namestring

    Narwhal’s standard English name, such as Producer prices. It contains no dates.

  • topicstring

    What the series measures, the same in every country, such as consumer_prices or gdp.

  • periodstring

    The period the release covers, such as 2026-09 or 2026-Q3.

  • statusstring

    Where the release stands, such as scheduled.

  • at / date / between / bystring

    The timing the publisher gave: an exact time, a day, a range of days or a deadline. None appears when the date is unknown.

  • valuesarray

    The published figures. The array is empty until they are out.


Full reference →

Use cases

Next CPI release date

Find when the next US CPI is due, in UTC and New York time.

Read the guide →

An economic calendar

Build a calendar of releases for the countries and dates you choose.

Read the guide →

Alerts before a release

Get a reminder before a release from a calendar feed or a daily script.

Read the guide →

Release times in your time zone

Convert UTC release times to local time, with daylight saving handled.

Read the guide →

FOMC meetings and minutes

List the scheduled FOMC rate decisions and minutes.

Read the guide →

Economic calendar for a product

Show upcoming releases for chosen countries in your own app.

Read the use case →

Release times for traders

Read the release time, period and previous value before a number is out.

Read the use case →

Coverage

114 countries. 43 have release schedules read from their own publishers; the other 71 have dates from a third-party calendar, marked indicative.

Show all 114 countries

Sources

55 official publishers: statistical offices, ministries and central banks. A publisher's own date and figure always win over the third-party calendar.

  • Instituto Nacional de Estadística y Censos (INDEC)Argentina
  • Australian Bureau of Statistics (ABS)Australia
  • Statistics AustriaAustria
  • Eurostat7 countries
  • StatbelBelgium
  • National Bank of BelgiumBelgium
  • Banco Central do BrasilBrazil
  • National Statistical Institute (NSI)Bulgaria
  • Statistics CanadaCanada
  • Central Bank of Chile (BCCh)Chile
  • National Statistics Institute of Chile (INE)Chile
  • Croatian Bureau of Statistics (CBS)Croatia
Show all 55 sources
  • Czech Statistical Office (ČSÚ)Czechia
  • Statistics DenmarkDenmark
  • Statistics EstoniaEstonia
  • European Commission (DG ECFIN)Euro area
  • Statistics FinlandFinland
  • Finnish Customs (Tulli)Finland
  • National Institute of Statistics and Economic Studies (INSEE)France
  • French CustomsFrance
  • Federal Statistical Office of Germany (Destatis)Germany
  • Hellenic Statistical Authority (ELSTAT)Greece
  • Hungarian Central Statistical Office (KSH)Hungary
  • Statistics IcelandIceland
  • Ministry of Statistics and Programme Implementation (MoSPI)India
  • Central Statistics Office (CSO)Ireland
  • Italian National Institute of Statistics (Istat)Italy
  • Statistics Bureau of JapanJapan
  • Cabinet Office of JapanJapan
  • Japan CustomsJapan
  • Central Statistical Bureau of Latvia (CSB)Latvia
  • State Data Agency of LithuaniaLithuania
  • STATECLuxembourg
  • Department of Statistics Malaysia (DOSM)Malaysia
  • INEGIMexico
  • Statistics Netherlands (CBS)Netherlands
  • Stats NZNew Zealand
  • Statistics Norway (SSB)Norway
  • Statistics PolandPoland
  • Statistics Portugal (INE)Portugal
  • National Bank of Romania (BNR)Romania
  • Federal State Statistics Service (Rosstat)Russia
  • Bank of RussiaRussia
  • Singapore Department of Statistics (SingStat)Singapore
  • Singapore government open-data publicationsSingapore
  • Statistical Office of the Republic of Slovenia (SURS)Slovenia
  • National Statistics Institute of Spain (INE)Spain
  • Spanish Tax Agency (AEAT)Spain
  • Statistics Sweden (SCB)Sweden
  • Directorate-General of Budget, Accounting and Statistics (DGBAS)Taiwan
  • Turkish Statistical Institute (TurkStat)Turkey
  • Office for National Statistics (ONS)United Kingdom
  • Bureau of Labor Statistics (BLS)United States
  • Bureau of Economic Analysis (BEA)United States
  • US Census BureauUnited States

Related APIs

Public Holidays API

Official public holidays by country, with national and regional scope.

Explore the API →

Economics API

Official indicators for prices, labour, output, trade and rates.

Explore the API →

Pricing

Prepaid credit, $2 per 1,000 calls, no plans or tiers.

See pricing →

FAQ

Does every release have an exact time?

No. A publisher may specify only a date, a range, or a deadline. The response preserves that precision in the top-level at, date, between, or by field.

Can I retrieve an earlier version?

Use the version_id parameter on a release detail request to select an immutable version.

Is there a free economic calendar API?

Yes. Every Narwhal account gets $10 of free credit each month, with no card and no end date. A calendar request costs one call at $2 per 1,000 calls, so the free credit covers 5,000 calls a month.

Does the calendar include consensus forecasts?

Yes, where a third-party calendar has one. A value carries the consensus next to the previous figure and, after the release, the actual. The consensus is a forecast, not a published figure, and is absent when none is known. There is no importance rating.

What time zone are release times in?

An exact release time, in the at field, is in UTC. The timezone field gives the publisher's own IANA time zone, such as Asia/Jakarta, so you can show local time. A release that has only a date has no time.

How much history does the calendar return?

A request covers a window of up to 366 days. The default runs from 30 days before today to 335 days after. Page through longer ranges one window at a time. A release that changed keeps its earlier versions, which you read with version_id.

Can I get the calendar as an ICS feed?

Yes. Create a calendar subscription and Narwhal returns a private .ics link that a calendar app can subscribe to. It can hold releases, public holidays or both, for 1 to 50 countries over a window of up to 366 days. Creating one costs one call.

Can an AI agent read the calendar over MCP?

Yes. The Narwhal MCP server has economics_list_releases and economics_get_release, the same two operations as the REST endpoints.

What are the rate limits?

50 requests a minute while the account holds only free credit, and 500 a minute once it holds paid credit. One network address is limited to 120 a minute. A 429 response carries Retry-After and costs nothing.

What should I check before using the data?

A scheduled release is not a guarantee of publication at an exact time. Preserve the timing precision and timezone, and handle cancelled releases explicitly. The scheduled time and the time Narwhal observed the release describe different events.