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

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

  - `"NONE"`

  - `"LOW"`

  - `"MEDIUM"`

  - `"HIGH"`

- `page_size: optional number`

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

- `page_token: optional string`

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

- `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](https://docs.clearstreet.com/guides/api-fundamentals#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](https://docs.clearstreet.com/guides/api-fundamentals#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](https://docs.clearstreet.com/guides/api-fundamentals#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](https://docs.clearstreet.com/guides/api-fundamentals#range-filters) for accepted formats, bare-date expansion, and combining bounds. Returns 400 if the resulting range is inverted.

### Returns

- `data: EconomicEventList`

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

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

    - `"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.

### Example

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

#### Response

```json
{
  "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"
  }
}
```