---
title: "US economic calendar with actuals"
method: GET
path: "/api/markets/calendar"
tags: ["Macro"]
---

# US economic calendar with actuals

`GET /api/markets/calendar`

## Request

- Base URL: `https://xoomar.com`
- URL: `https://xoomar.com/api/markets/calendar`
- Auth: one of:
  - none
  - API key in header `x-api-key`

nextReleaseAt in the envelope is when the next high-importance release is due. Send the ETag back in If-None-Match and an unchanged calendar answers 304 Not Modified with no body. Docs: https://xoomar.com/markets/api/calendar

## Query parameters

- `from` string
- `to` string
- `importance` 'high' | 'med' | 'low'

## Response `200`

OK

- object
  - `data` object[]
    - `source` string: bls, bea, census, fed, dol or treasury (coupon auctions)
    - `eventName` string: CPI (Consumer Price Index), Nonfarm Payrolls (Employment Situation), Initial Jobless Claims, Retail Sales (Advance), FOMC Rate Decision, ...
    - `importance` string: high, med, or low
    - `scheduledAt` string, date-time: Release time, UTC
    - `periodLabel` string, nullable: Reference period: 'August 2026', '3rd Quarter 2026', 'Week ending 2026-09-05'
    - `previous` string, nullable: Prior period on the same basis as actual
    - `forecast` string, nullable: Always null: consensus forecasts aren't included
    - `actual` string, nullable: Filled after release from the agency series (CPI year over year %, payrolls monthly change in thousands, retail sales % m/m, claims in thousands, ...)
    - `unit` string, nullable: What actual and previous are in: '% m/m', '% y/y, PCE price index', 'thousands, annual rate', 'USD billions, balance'
    - `canonicalUrl` string, uri: The matching page on xoomar.com
  - `updatedAt` string, date-time: When the response was built; a few dated feeds give the date of their newest row instead
  - `nextReleaseAt` string, date-time, nullable: When the next high-importance release is due, UTC, whatever the window or filter asked for; null when none is scheduled
  - `source` 'xoomar.com'
  - `docs` string
  - `license` string: Data terms
  - `attribution` string
  - `canonicalUrl` string, uri: The matching page on xoomar.com
  - `meta` object: Who publishes the data and how to credit it
    - `source` string: The publisher or publishers of the data, comma-separated
    - `sourceAttribution` string: The credit line to show wherever the data is displayed
    - `notice` string: Requests without a key only: the free key, app registration and the credit

## Other responses

- `404`: Unknown slug, ticker or country
- `429`: Rate limit: 10 requests a minute without a key, 30 with a free key

---

[API](https://skmtc.dev/xoomar/apis/xoomar-market-data-api.md) · [All operations](https://skmtc.dev/xoomar/apis/xoomar-market-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xoomar/apis/xoomar-market-data-api/revisions/07b78401eaaa?raw)