Skip to content
Clear Street Clear Street
Get started
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

OEMS instrument UUID

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

formatdate
Optional<String> dividendAmount

The dividend amount per share.

Optional<String> dividendYield

The dividend yield as a percentage of the stock price.

Optional<String> frequency

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

Optional<LocalDate> paymentDate

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

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.

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

Optional<String> epsEstimate

The estimated earnings per share (EPS) for the period

Optional<String> epsSurprisePercent

The percentage difference between actual and estimated EPS

Optional<String> revenueActual

The actual total revenue for the period

Optional<String> revenueEstimate

The estimated total revenue for the period

Optional<String> revenueSurprisePercent

The percentage difference between actual and estimated revenue

String instrumentId

OEMS instrument UUID from the request

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

Get Instrument Events

package com.clear_street.api.example;

import com.clear_street.api.client.ClearStreetClient;
import com.clear_street.api.client.okhttp.ClearStreetOkHttpClient;
import com.clear_street.api.models.v1.instrumentdata.InstrumentDataGetInstrumentEventsParams;
import com.clear_street.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"
  }
}