## 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

### Parameters

- `InstrumentDataGetInstrumentEventsParams params`

  - `Optional<String> instrumentId`

    OEMS instrument UUID

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

### Returns

- `class InstrumentDataGetInstrumentEventsResponse:`

  - `InstrumentEventsData data`

    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.

      - `Optional<LocalDate> declarationDate`

        The declaration date of the dividend

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

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

    - `List<InstrumentEarnings> earnings`

      Earnings announcement events

      - `LocalDate date`

        The date when the earnings report was published

      - `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

    - `List<InstrumentSplitEvent> splits`

      Stock split events

      - `LocalDate date`

        The date of the stock split

      - `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

### Example

```java
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");
    }
}
```

#### Response

```json
{
  "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"
  }
}
```