Plan around releases
Filter the calendar by countries and date window, then follow the returned release IDs.
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.
First request
Quickstart →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 Illustrative response · not a live request
{
"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
}Calendar subscriptions
Create a subscribed ICS feed through Narwhal API for your team's chosen countries and date window. Include available public holidays, economic release dates, or both. Use it in Google Calendar, Apple Calendar, Outlook, or other calendar clients.
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 Illustrative response · not a live request
{
"subscription_id": "example-subscription",
"url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
"expires_at": "2026-12-31T23:59:59Z",
"refresh_note": "calendar clients control refresh latency"
}Endpoints
GETList releases in a date window./v1/economics/calendar
GETRead a release, optionally selecting version_id./v1/economics/calendar/{release_id}
How the data works
Understand the schedule
Distinguish exact times, dates, estimated ranges, deadlines, and unknown schedules.
Follow a release
Retrieve a release and its version, reference period, status, and publication timestamps.
Coverage
View coverage →A scheduled release is not a guarantee of publication at an exact time. Preserve the schedule precision and timezone, and handle cancelled releases explicitly. Publication timestamps and observation timestamps describe different events.
Explore related pages
Economic release calendar
Browse official schedules and publication status.
View calendar →API reference
Parameters and response fields.
Read the docs →Public holidays API
Get public holidays by country and year through REST or MCP. Check a date or find the next holiday with national and regional scope.
Explore the API →Common questions
Does every release have an exact time?
No. A publisher may specify only a date, a range, or a deadline. The schedule object preserves that precision.
Can I retrieve an earlier version?
Use the version_id parameter on a release detail request to select an immutable version.