Get Instrument Events

$ clear-street v1:instrument-data get-instrument-events

GET/v1/instruments/{instrument_id}/events

Retrieves corporate events (dividends, splits, etc.) for an instrument, grouped by event type.

Date range defaults:

from_date: today - 365 days
to_date: today + 60 days

ParametersExpand Collapse

--instrument-id: string

OEMS instrument UUID

--from-date: optional string

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

--to-date: optional string

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

ReturnsExpand Collapse

V1InstrumentDataGetInstrumentEventsResponse: BaseResponse { metadata, error }

data: object { dividends, earnings, instrument_id, 2 more }

Grouped instrument events by type

dividends: array of InstrumentDividendEvent { adjusted_dividend_amount, ex_date, declaration_date, 5 more }

Dividend distribution events

adjusted_dividend_amount: string

The adjusted dividend amount accounting for any splits.

ex_date: string

The day the stock starts trading without the right to receive that dividend.

declaration_date: optional string

The declaration date of the dividend

dividend_amount: optional string

The dividend amount per share.

dividend_yield: optional string

The dividend yield as a percentage of the stock price.

frequency: optional string

The frequency of the dividend payments (e.g., “Quarterly”, “Annual”).

payment_date: optional string

The payment date is the date on which a declared stock dividend is scheduled to be paid.

record_date: optional string

The record date, set by a company’s board of directors, is when a company compiles a list of shareholders of the stock for which it has declared a dividend.

earnings: array of InstrumentEarnings { date, eps_actual, eps_estimate, 4 more }

Earnings announcement events

date: string

The date when the earnings report was published

eps_actual: optional string

The actual earnings per share (EPS) for the period

eps_estimate: optional string

The estimated earnings per share (EPS) for the period

eps_surprise_percent: optional string

The percentage difference between actual and estimated EPS

revenue_actual: optional string

The actual total revenue for the period

revenue_estimate: optional string

The estimated total revenue for the period

revenue_surprise_percent: optional string

The percentage difference between actual and estimated revenue

instrument_id: string

OEMS instrument UUID from the request

splits: array of InstrumentSplitEvent { date, denominator, numerator, split_type }

Stock split events

date: string

The date of the stock split

denominator: string

The denominator of the split ratio

numerator: string

The numerator of the split ratio

split_type: string

The type of stock split (e.g., “stock-split”, “stock-dividend”, “bonus-issue”)

reporting_currency: optional string

The currency used for reporting financial data

Get Instrument Events

clear-street v1:instrument-data get-instrument-events \
  --api-key 'My API Key' \
  --instrument-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e

{
  "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"
      }
    ],
    "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    "reporting_currency": "USD",
    "splits": [
      {
        "date": "2020-08-31",
        "denominator": "1",
        "numerator": "4",
        "split_type": "stock-split"
      }
    ]
  },
  "error": null,
  "metadata": {
    "request_id": "0f1a2b3c-4d5e-6789-8a7b-6c5d4e3f2a1b"
  }
}

{
  "error": {
    "code": 404,
    "message": "Instrument not found: AAP"
  },
  "metadata": {
    "request_id": "fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2"
  }
}

Returns Examples

{
  "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"
      }
    ],
    "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    "reporting_currency": "USD",
    "splits": [
      {
        "date": "2020-08-31",
        "denominator": "1",
        "numerator": "4",
        "split_type": "stock-split"
      }
    ]
  },
  "error": null,
  "metadata": {
    "request_id": "0f1a2b3c-4d5e-6789-8a7b-6c5d4e3f2a1b"
  }
}

{
  "error": {
    "code": 404,
    "message": "Instrument not found: AAP"
  },
  "metadata": {
    "request_id": "fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2"
  }
}