CLclear-street
Instrument Data

Get All Instrument Events

Changed on

List instrument events across all securities, grouped by date. Results are paginated via page_size / page_token; a date's events may span two pages.

Date range defaults (anchored on the current trading day, or the next trading day if today is a weekend or US market holiday):

  • Unfiltered (no instrument_ids): a single trading day (from_date = to_date = anchor). If only one bound is given, the other defaults to 6 days from it; there is no maximum span once both bounds are given.
  • Filtered (with instrument_ids): a 30-day lookback ending on the anchor (from_date = anchor − 30 days, to_date = anchor).

Pagination metadata does not include total_items or total_pages for this endpoint. Use next_page_token to detect whether more results exist.

get/v1/instruments/events

Request

  • Base URL
    https://api.clearstreet.com
  • Auth
    HTTP bearer

Query parameters

event_typesAllEventsEventType[]

Filter by event type(s). Comma-delimited list. Example: event_types=EARNINGS,IPO.

instrument_idsInstrumentIdOrSymbol[]

Filter by instrument. Comma-separated instrument IDs (UUID) or symbols (equity tickers or OSI option symbols). Example: instrument_ids=550e8400-e29b-41d4-a716-446655440000,AAPL.

from_datestring

The start date for the query range, inclusive (YYYY-MM-DD).

to_datestring

The end date for the query range, inclusive (YYYY-MM-DD).

page_sizeinteger

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

page_tokenstring byte

Base64URL-encoded pagination token

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

Response

Instrument events grouped by date

Example response

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": {
    "event_dates": [
      {
        "events": [
          {
            "dividend_event_data": {
              "adjusted_dividend_amount": "0.88",
              "declaration_date": "2025-07-25",
              "dividend_amount": "0.88",
              "dividend_yield": "1.25",
              "ex_date": "2025-08-15",
              "frequency": "Quarterly",
              "payment_date": "2025-08-20",
              "record_date": "2025-08-01"
            },
            "earnings_event_data": {
              "date": "2025-07-25",
              "eps_actual": "1.35",
              "eps_estimate": "1.30",
              "eps_surprise_percent": "3.8",
              "report_time": "BMO",
              "revenue_actual": "391035000000",
              "revenue_estimate": "391025000000",
              "revenue_surprise_percent": "0.05",
              "transcript_available": true
            },
            "stock_split_event_data": {
              "date": "2025-08-15",
              "denominator": "4",
              "numerator": "1",
              "split_type": "stock-split"
            }
          }
        ]
      }
    ]
  }
}

Changes

  • 49c5c6b23633Revision changes
    • info

      added the required property /////////// to the response with the status

  • 1bd9eddeffc8Revision changes
    • warning

      for the query request parameter instrument_ids, the type of property items/ changed from no type to string

    • info

      added the new optional query request parameter page_size

    • info

      added the new optional query request parameter page_token

    • info

      added the optional property /////////// to the response with the status

    • info

      response property allOf[subschema #2]/data/event_dates/items/events/items/ipo_event_data/oneOf[InstrumentEventIpoItem]/market_cap deprecated