---
title: "Scheduled US macro releases (economic calendar)"
method: GET
path: "/api/calendar/"
tags: ["calendar"]
---

# Scheduled US macro releases (economic calendar)

`GET /api/calendar/`

The official forward schedule of US macro releases: FOMC decisions
(with SEP and press-conference markers) and minutes, CPI, PPI, the
jobs report (nonfarm payrolls), GDP estimates (advance/second/third),
PCE, advance retail sales, weekly jobless claims and JOLTS — sourced
from the agencies' own schedule pages (Fed, BLS, BEA, Census, DOL).

Each occurrence carries a stable `uid` (`US-CPI-2026-07`) that
survives reschedules: a moved release keeps its identity, updates
`scheduled_at` and reports `schedule_status`. `phase` says only
whether the scheduled moment has passed (`upcoming`/`elapsed`) — it
deliberately does not claim the agency actually published. Pair the
calendar with `/api/news/macro/` to read what a release meant once
it's out.

The window is `[from_date, to_date)` — from inclusive, to exclusive;
date-only values mean UTC midnight; defaults are today (UTC) → +7
days; the span is capped at 400 days. No pagination: a full year of
every series is ~250 rows (hard cap 500), ordered by `scheduled_at`
ascending. Cancelled and postponed occurrences stay in the response
with their `schedule_status`.

## Query parameters

- `from_date` string
- `to_date` string
- `event_key` string
- `importance` 'high' | 'medium' | 'low'
- `country` 'US'

## Response `200`

Occurrences within the window, `scheduled_at` ascending.

- CalendarEvents
  - `events` CalendarEvent[]
    - `uid` string
    - `event_key` 'fomc_decision' | 'fomc_minutes' | 'cpi' | 'ppi' | 'nfp' | 'gdp' | 'pce' | 'retail_sales' | 'jobless_claims' | 'jolts'
    - `title` string
    - `reference_period` string — What the release covers, machine-readable: a month (`2026-07`), a quarter (`2026-Q2`), or — for weekly claims — the reference week-ending Saturday (`2026-07-25`).
    - `release_stage` string, nullable — GDP only — `advance`, `second` or `third`; null elsewhere.
    - `scheduled_at` string, date-time — Official release moment (UTC; 08:30 / 10:00 / 14:00 ET converted).
    - `phase` 'upcoming' | 'elapsed'
    - `schedule_status` 'scheduled' | 'postponed' | 'cancelled'
    - `schedule_basis` 'official' | 'inferred' — `official`: the date is printed on the agency's own schedule page. `inferred`: derived from the documented publication cadence — weekly jobless claims (DOL publishes no forward schedule) and FOMC minutes dates the Fed has not printed yet (three weeks after the meeting). Inferred dates flip to official once the agency lists them.
    - `importance` 'high' | 'medium' | 'low'
    - `category` 'earnings' | 'mergers_acquisitions' | 'regulation' | 'macro_economy' | 'sector_analysis' | 'market_movers' | 'technology' | 'commodities' | 'crypto' | 'ipo' | 'geopolitics' | 'insider' | 'corporate_actions' | 'other' — `market_movers` is for articles whose subject IS a notable price move ("AMD up 5% today"); `sector_analysis` is genuine sector-level analysis; `insider` covers SEC Form 4 insider transactions only. SEC 8-K filings categorize by their primary item: an earnings release (Item 2.02) is `earnings`, a completed acquisition or disposition (Item 2.01) is `mergers_acquisitions`, and the remaining events (material agreements, debt, executive changes, annual-meeting results) are `corporate_actions`.
    - `country` string
    - `source_url` string, uri — The agency's own schedule page for the series.
    - `press_conference_at` string, date-time, nullable — FOMC decisions only — the 14:30 ET press conference; null elsewhere.
    - `has_sep` boolean — FOMC decisions only — true when the meeting carries a Summary of Economic Projections (the "dot plot").

## Other responses

- `400` — Unknown parameter or value, a malformed date, `to_date` not after `from_date`, or a window over 400 days.
- `401` — Missing or invalid API key.
- `429` — Rate limit exceeded — either the per-minute burst cap or the per-day volume cap. The `Retry-After` header tells you how long to wait (a burst block is short, ≤60s; a day-cap block is capped at 3600s — the true reset is `X-RateLimit-Reset`). The `X-RateLimit-*` trio shows the daily volume budget. The body's `extra` names your tier, its `limit_per_minute` / `limit_per_day`, `retry_after_seconds`, and — below Pro — an `upgrade` block with the higher tiers' caps and the pricing URL.

---

[API](https://skmtc.net/alphai/apis/alphai-rest-api.md) · [All operations](https://skmtc.net/alphai/apis/alphai-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alphai/alphai-rest-api/versions/2f34f38bad24/schema)