Get Economic Calendar Events

GET/v1/calendars/economic-events

Retrieves macroeconomic calendar events (e.g. CPI, jobs reports, central bank rate decisions), optionally filtered by country, impact, and event time range.

Absent a timestamp lower bound, results default to events from the start of the previous trading day (America/New_York); absent an upper bound, results default through 7 days from today (America/New_York).

Query ParametersExpand Collapse

country: optional string

Comma-separated ISO 3166-1 alpha-2 country codes (or EU) to filter by. Defaults to US when omitted.

impact: optional array of "NONE" or "LOW" or "MEDIUM" or "HIGH"

Comma-separated impact levels to filter by.

One of the following:

"NONE"

"LOW"

"MEDIUM"

"HIGH"

page_size: optional number

The number of items to return per page. Only used when page_token is not provided.

formatint64

maximum10000

minimum1

page_token: optional string

Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.

formatbyte

timestamp: optional object { gt, gte, lt, lte }

gt: optional string

Return only rows where timestamp is strictly after the given value. A bare YYYY-MM-DD date expands to the end of that day (UTC), so this matches from the start of the following day. See Range filters for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.

gte: optional string

Return only rows where timestamp is on or after the given value. A bare YYYY-MM-DD date expands to the start of that day (UTC). See Range filters for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.

lt: optional string

Return only rows where timestamp is strictly before the given value. A bare YYYY-MM-DD date expands to the start of that day (UTC). See Range filters for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.

lte: optional string

Return only rows where timestamp is on or before the given value. A bare YYYY-MM-DD date expands to the end of that day (UTC), so this matches through the end of that day. See Range filters for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.

ReturnsExpand Collapse

data: EconomicEventList { country, name, timestamp, 8 more }

country: string

ISO 3166-1 alpha-2 country code, or EU.

name: string

Event name as reported by the provider.

timestamp: string

UTC instant of the event.

formatdate-time

actual: optional string

Actual reported value. Null before the print, or if the provider never reports one for this event. When a null/undefined value is observed, it indicates that there is no available data.

change: optional string

Change from the previous value. When a null/undefined value is observed, it indicates that there is no available data.

change_percentage: optional string

Change from the previous value, as a percentage. When a null/undefined value is observed, it indicates that there is no available data.

currency: optional string

Currency associated with the event, if applicable. When a null/undefined value is observed, it indicates that there is no available data.

estimate: optional string

Analyst-estimated value. When a null/undefined value is observed, it indicates that there is no available data.

impact: optional EconomicEventImpact

Expected market impact, if known. When a null/undefined value is observed, it indicates that there is no available data.

One of the following:

"NONE"

"LOW"

"MEDIUM"

"HIGH"

previous: optional string

Previous period’s reported value. When a null/undefined value is observed, it indicates that there is no available data.

unit: optional EconomicEventUnit

Unit of the numeric value fields, if known. When a null/undefined value is observed, it indicates that there is no available data.

Get Economic Calendar Events

curl https://api.clearstreet.com/v1/calendars/economic-events \
    -H "Authorization: Bearer $API_KEY"

{
  "data": [
    {
      "actual": null,
      "change": null,
      "change_percentage": null,
      "country": "US",
      "currency": "USD",
      "estimate": "0.30",
      "impact": "HIGH",
      "name": "CPI m/m",
      "previous": "0.20",
      "timestamp": "2025-11-05T13:30:00.000000000Z",
      "unit": "%"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "0f1a2b3c-4d5e-6f78-9012-3a4b5c6d7e8f"
  }
}

Returns Examples

{
  "data": [
    {
      "actual": null,
      "change": null,
      "change_percentage": null,
      "country": "US",
      "currency": "USD",
      "estimate": "0.30",
      "impact": "HIGH",
      "name": "CPI m/m",
      "previous": "0.20",
      "timestamp": "2025-11-05T13:30:00.000000000Z",
      "unit": "%"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "0f1a2b3c-4d5e-6f78-9012-3a4b5c6d7e8f"
  }
}