Skip to content
Clear Street Clear Street
Get started
API Reference
V1
Instrument Data

Get Instrument Events

client.V1.InstrumentData.GetInstrumentEvents(ctx, instrumentID, query) (*V1InstrumentDataGetInstrumentEventsResponse, error)
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

OEMS instrument UUID

formatuuid
query V1InstrumentDataGetInstrumentEventsParams
FromDate param.Field[string]Optional

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

ToDate param.Field[string]Optional

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

ReturnsExpand Collapse
type V1InstrumentDataGetInstrumentEventsResponse struct{…}

Grouped instrument events by type

Dividend distribution events

AdjustedDividendAmount string

The adjusted dividend amount accounting for any splits.

ExDate Time

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

formatdate
DeclarationDate TimeOptional

The declaration date of the dividend

formatdate
DividendAmount stringOptional

The dividend amount per share.

DividendYield stringOptional

The dividend yield as a percentage of the stock price.

Frequency stringOptional

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

PaymentDate TimeOptional

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

formatdate
RecordDate TimeOptional

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

Earnings announcement events

Date Time

The date when the earnings report was published

formatdate
EpsActual stringOptional

The actual earnings per share (EPS) for the period

EpsEstimate stringOptional

The estimated earnings per share (EPS) for the period

EpsSurprisePercent stringOptional

The percentage difference between actual and estimated EPS

RevenueActual stringOptional

The actual total revenue for the period

RevenueEstimate stringOptional

The estimated total revenue for the period

RevenueSurprisePercent stringOptional

The percentage difference between actual and estimated revenue

InstrumentID string

OEMS instrument UUID from the request

formatuuid

Stock split events

Date Time

The date of the stock split

formatdate
Denominator string

The denominator of the split ratio

Numerator string

The numerator of the split ratio

SplitType string

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

ReportingCurrency stringOptional

The currency used for reporting financial data

Get Instrument Events

package main

import (
  "context"
  "fmt"

  "github.com/clear-street/clear-street-go"
  "github.com/clear-street/clear-street-go/option"
)

func main() {
  client := clearstreet.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.V1.InstrumentData.GetInstrumentEvents(
    context.TODO(),
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    clearstreet.V1InstrumentDataGetInstrumentEventsParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

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