Skip to content
Clear Street Clear Street Clear Street
Start Trading
API Reference
V1
Calendar

Get Economic Calendar Events

v1.calendar.get_economic_events_calendar(CalendarGetEconomicEventsCalendarParams**kwargs) -> CalendarGetEconomicEventsCalendarResponse
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).

ParametersExpand Collapse
country: Optional[str]

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

impact: Optional[List[Literal["NONE", "LOW", "MEDIUM", "HIGH"]]]

Comma-separated impact levels to filter by.

One of the following:
"NONE"
"LOW"
"MEDIUM"
"HIGH"
page_size: Optional[int]

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

formatint64
maximum10000
minimum1
page_token: Optional[Union[str, Base64FileInput]]

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

formatbyte
timestamp: Optional[Timestamp]
gt: Optional[str]

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[str]

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[str]

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[str]

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
class CalendarGetEconomicEventsCalendarResponse: …
country: str

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

name: str

Event name as reported by the provider.

timestamp: datetime

UTC instant of the event.

formatdate-time
actual: Optional[str]

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[str]

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

change_percentage: Optional[str]

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[str]

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

estimate: Optional[str]

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 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

from clearstreet import ClearStreet

client = ClearStreet(
    api_key="My API Key",
)
response = client.v1.calendar.get_economic_events_calendar()
print(response)
{
  "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"
  }
}