--- title: "Get Instrument Events" method: GET path: "/v1/instruments/{instrument_id}/events" tags: ["Instrument Data"] --- # Get Instrument Events `GET /v1/instruments/{instrument_id}/events` ## Request - Base URL: `https://api.clearstreet.com` - URL: `https://api.clearstreet.com/v1/instruments/{instrument_id}/events` - Auth: HTTP bearer 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 ## Path parameters - `instrument_id` string, required: Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side. ## Query parameters - `event_types` AllEventsEventType[] - `from_date` string - `to_date` string ## Response `200` Instrument events grouped by type - object - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses. - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `details` object[] - `message` string, required: A human-readable message providing more details about the error. - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data. - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request. - `total_items` integer, nullable: Total number of items available (not just in this page). - `total_pages` integer, nullable: Total number of pages available. - `data` InstrumentEventsData, required: Grouped instrument events by type - `dividends` InstrumentDividendEvent[], required: Dividend distribution events - `adjusted_dividend_amount` string, required: The adjusted dividend amount accounting for any splits. - `declaration_date` string, date, nullable: The declaration date of the dividend When a null/undefined value is observed, it indicates that there is no available data. - `dividend_amount` string, nullable: The dividend amount per share. When a null/undefined value is observed, it indicates that there is no available data. - `dividend_yield` string, nullable: The dividend yield as a percentage of the stock price. When a null/undefined value is observed, it indicates that there is no available data. - `ex_date` string, date, required: The day the stock starts trading without the right to receive that dividend. - `frequency` string, nullable: The frequency of the dividend payments (e.g., "Quarterly", "Annual"). When a null/undefined value is observed, it indicates that there is no available data. - `payment_date` string, date, nullable: The payment date is the date on which a declared stock dividend is scheduled to be paid. When a null/undefined value is observed, it indicates that there is no available data. - `record_date` string, date, nullable: 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. When a null/undefined value is observed, it indicates that there is no available data. - `earnings` InstrumentEarnings[], required: Earnings announcement events - `date` string, date, required: The date when the earnings report was published - `eps_actual` string, nullable: The actual earnings per share (EPS) for the period When a null/undefined value is observed, it indicates that there is no available data. - `eps_estimate` string, nullable: The estimated earnings per share (EPS) for the period When a null/undefined value is observed, it indicates that there is no available data. - `eps_surprise_percent` string, nullable: The percentage difference between actual and estimated EPS When a null/undefined value is observed, it indicates that there is no available data. - `report_time` 'BMO' | 'AMC': Earnings report timing: before market open or after market close - `revenue_actual` string, nullable: The actual total revenue for the period When a null/undefined value is observed, it indicates that there is no available data. - `revenue_estimate` string, nullable: The estimated total revenue for the period When a null/undefined value is observed, it indicates that there is no available data. - `revenue_surprise_percent` string, nullable: The percentage difference between actual and estimated revenue When a null/undefined value is observed, it indicates that there is no available data. - `transcript_available` boolean, required: True when an earnings call transcript exists for this event. Fetch it with `GET /v1/instruments/{instrument_id}/earnings-transcripts?event_date=`, where `` is this event's `date`. - `instrument_id` string, uuid, required: Instrument identifier - `ipos` InstrumentIpoEvent[], required: IPO events - `actions` string, nullable: IPO action. When a null/undefined value is observed, it indicates that there is no available data. - `announced_at` string, date-time, nullable: IPO announced timestamp. When a null/undefined value is observed, it indicates that there is no available data. - `company` string, nullable: IPO company name. When a null/undefined value is observed, it indicates that there is no available data. - `date` string, date, required: The date of the IPO - `exchange` string, nullable: IPO exchange. When a null/undefined value is observed, it indicates that there is no available data. - `market_cap` string, nullable: Deprecated: use `offering_amount`, which carries the same value. This is not a market capitalization. When a null/undefined value is observed, it indicates that there is no available data. - `offering_amount` string, nullable: IPO maximum aggregate offering value: all offered shares, including over-allotment (greenshoe) shares, at the top of the price range. This is an upper bound. It assumes full exercise of the over-allotment option and pricing at the top of the range. When a null/undefined value is observed, it indicates that there is no available data. - `price_range` string, nullable: IPO price range. When a null/undefined value is observed, it indicates that there is no available data. - `shares` string, nullable: IPO shares offered. When a null/undefined value is observed, it indicates that there is no available data. - `reporting_currency` string, nullable: The currency used for reporting financial data When a null/undefined value is observed, it indicates that there is no available data. - `splits` InstrumentSplitEvent[], required: Stock split events - `date` string, date, required: The date of the stock split - `denominator` string, required: The denominator of the split ratio - `numerator` string, required: The numerator of the split ratio - `split_type` string, required: The type of stock split (e.g., "stock-split", "stock-dividend", "bonus-issue") ## Other responses - `404`: Instrument not found - `500`: Internal server error ## Changes - **2026-10-21** `49c5c6b23633`: 1 info - added the required property `allOf[subschema #2]/data/earnings/items/transcript_available` to the response with the `200` status - **2026-10-16** `1bd9eddeffc8`: 1 breaking, 3 info - for the `path` request parameter `instrument_id`, the minLength was increased from `0` to `1` - added the new optional `query` request parameter `event_types` - for the `path` request parameter `instrument_id`, the type was generalized from no type to `string` - added the required property `allOf[subschema #2]/data/ipos` to the response with the `200` status - **2026-07-15** `169e8b9ad50c`: 1 info - added the optional property `allOf[subschema #2]/data/earnings/items/report_time` to the response with the `200` status - **2026-05-15** `032c3b0145e1`: 1 info - added the optional property `allOf[subschema #2]/data/reporting_currency` to the response with the `200` status [Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/instruments/:instrument_id/events/get.md) --- [API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)