Skip to content
Clear Street Clear Street
Start Trading
API Reference
V1
Instrument Data

Get Instrument Events

InstrumentDataGetInstrumentEventsResponse v1().instrumentData().getInstrumentEvents(InstrumentDataGetInstrumentEventsParamsparams = InstrumentDataGetInstrumentEventsParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
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
InstrumentDataGetInstrumentEventsParams params
Optional<String> instrumentId

Instrument identifier

formatuuid
Optional<String> fromDate

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

Optional<String> toDate

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

ReturnsExpand Collapse
class InstrumentDataGetInstrumentEventsResponse:

Grouped instrument events by type

List<InstrumentDividendEvent> dividends

Dividend distribution events

String adjustedDividendAmount

The adjusted dividend amount accounting for any splits.

LocalDate exDate

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

formatdate
Optional<LocalDate> declarationDate

The declaration date of the dividend When a null/undefined value is observed, it indicates that there is no available data.

formatdate
Optional<String> dividendAmount

The dividend amount per share. When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> dividendYield

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.

Optional<String> frequency

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.

Optional<LocalDate> paymentDate

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.

formatdate
Optional<LocalDate> recordDate

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.

formatdate
List<InstrumentEarnings> earnings

Earnings announcement events

LocalDate date

The date when the earnings report was published

formatdate
Optional<String> epsActual

The actual earnings per share (EPS) for the period When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> epsEstimate

The estimated earnings per share (EPS) for the period When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> epsSurprisePercent

The percentage difference between actual and estimated EPS When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> revenueActual

The actual total revenue for the period When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> revenueEstimate

The estimated total revenue for the period When a null/undefined value is observed, it indicates that there is no available data.

Optional<String> revenueSurprisePercent

The percentage difference between actual and estimated revenue When a null/undefined value is observed, it indicates that there is no available data.

String instrumentId

Instrument identifier

formatuuid

Stock split events

LocalDate date

The date of the stock split

formatdate
String denominator

The denominator of the split ratio

String numerator

The numerator of the split ratio

String splitType

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

Optional<String> reportingCurrency

The currency used for reporting financial data When a null/undefined value is observed, it indicates that there is no available data.

Get Instrument Events

package com.clearstreet.api.example;

import com.clearstreet.api.client.ClearStreetClient;
import com.clearstreet.api.client.okhttp.ClearStreetOkHttpClient;
import com.clearstreet.api.models.v1.instrumentdata.InstrumentDataGetInstrumentEventsParams;
import com.clearstreet.api.models.v1.instrumentdata.InstrumentDataGetInstrumentEventsResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        ClearStreetClient client = ClearStreetOkHttpClient.builder()
            .fromEnv()
            .apiKey("My API Key")
            .build();

        InstrumentDataGetInstrumentEventsResponse response = client.v1().instrumentData().getInstrumentEvents("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"
  }
}