macro_get_calendar

List upcoming official macro data releases and policy meetings.

Answers "what economic data comes out this week?" and lets you time-contextualize analysis ("the GDP second estimate lands Wednesday — hold the comparison until then"). Use this for when a number is published; use macro_get_series for the number itself once it is out.

Schedules come from the agencies themselves: the BLS news-release calendar, the BEA release schedule, the Census economic-indicator calendar, the Federal Reserve FOMC and statistical-release calendars, and the ECB statistical and Governing Council calendars.

The result is the shared envelope. data.start and data.end echo the resolved window, data.source echoes the filter, and data.events is the bounded page. meta.source is "macro_calendar" and meta.as_of is the most recent time any event on the page was seen on its agency's schedule. pagination holds the cursor paging state.

Each event carries source (the publishing agency), release_name, scheduled_at (UTC, RFC 3339), scheduled_end (only for multi-day events — FOMC and ECB Governing Council meetings run two days), period_label (the reference period as the agency publishes it, e.g. "July 2026" or "2nd Quarter 2026"; null where the agency does not state one), status (scheduled, or tentative where the agency flags the date as provisional), url, as_of, attribution, and series_keys.

attribution is the citation the publisher requires when that row is reused: null for the U.S. agencies, whose schedules are public-domain works, and the ECB's required source line on ECB rows. Reproduce it alongside any ECB date you pass on.

Occurrences an agency has withdrawn are not served. A meeting that moved across a month boundary and a feed entry that was re-keyed both leave their original row in storage; only the occurrence its own schedule still lists is returned. Withdrawal waits for a second consecutive refresh that omits the occurrence, so a cancellation can still be served for one cycle after it is announced — a short document looks exactly like a cancellation, and briefly serving one release too many is much the better error. A release the agency renames keeps its past occurrences under the name they were published with, which is the record of what was announced at the time; future occurrences move to the new name.

series_keys is the link back to the data: when a release drives catalog series, pass one of those keys to macro_get_series after the release lands. It is empty for scheduled events with no ingested series (FOMC meetings, most Census indicators).

Times are the agency's published wall-clock converted to UTC. Where an agency publishes only a date — FOMC and ECB meetings — the timestamp is midnight in the agency's local zone; the FOMC statement itself lands around 2:00 p.m. ET on the final day.

Bounds: default limit 50, max 200; the default window is today through 14 days ahead and the maximum span is 93 days. Ordering is scheduled_at ascending, then event id — soonest first, because a calendar is read forwards. To page, pass pagination.next_cursor back as cursor while keeping start, end and source unchanged; when pagination.has_more is false, next_cursor is null. A window with nothing scheduled in it is a normal empty success, not an error.

U.S. agency schedules are public domain. ECB rows are reused under the ECB's terms and carry the required "Source: European Central Bank" attribution. Errors carry a machine code: bad_parameter for end before start, a window over 93 days, an out-of-range limit, or a malformed cursor.

Example: macro_get_calendar(start="2026-09-01", end="2026-09-07").