CLclear-street
Instrument Data

Get Instrument Events

Changed on

Retrieves corporate events (earnings, dividends, splits, IPO) for an instrument, grouped by event type. Filter to specific types via event_types.

Date range defaults:

  • from_date: today - 365 days
  • to_date: today + 60 days
get/v1/instruments/{instrument_id}/events

Request

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

Path parameters

instrument_idstring required

Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.

Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).

Query parameters

event_typesAllEventsEventType[]

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

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

Response

Instrument events grouped by type

Example response

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": {
    "dividends": [
      {
        "adjusted_dividend_amount": "0.25",
        "declaration_date": "2024-10-31",
        "dividend_amount": "0.25",
        "dividend_yield": "0.44",
        "ex_date": "2024-11-08",
        "frequency": "Quarterly",
        "payment_date": "2024-11-14",
        "record_date": "2024-11-11"
      }
    ],
    "earnings": [
      {
        "date": "2024-10-31",
        "eps_actual": "1.64",
        "eps_estimate": "1.60",
        "eps_surprise_percent": "2.5",
        "revenue_actual": "94930000000",
        "revenue_estimate": "94500000000",
        "revenue_surprise_percent": "0.45",
        "transcript_available": true
      }
    ],
    "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    "ipos": [],
    "splits": [
      {
        "date": "2020-08-31",
        "denominator": "1",
        "numerator": "4",
        "split_type": "stock-split"
      }
    ]
  }
}

Changes

  • 49c5c6b23633Revision changes
    • info

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

  • 1bd9eddeffc8Revision changes
    • breaking

      for the path request parameter instrument_id, the minLength was increased from 0 to 1

    • info

      added the new optional query request parameter event_types

    • info

      for the path request parameter instrument_id, the type was generalized from no type to string

    • info

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