Skip to content
Clear Street Clear Street
Start Trading
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

Instrument identifier

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 When a null/undefined value is observed, it indicates that there is no available data.

formatdate
DividendAmount stringOptional

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

DividendYield stringOptional

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.

Frequency stringOptional

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.

PaymentDate TimeOptional

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
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. When a null/undefined value is observed, it indicates that there is no available data.

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 When a null/undefined value is observed, it indicates that there is no available data.

EpsEstimate stringOptional

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

EpsSurprisePercent stringOptional

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

RevenueActual stringOptional

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

RevenueEstimate stringOptional

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

RevenueSurprisePercent stringOptional

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

InstrumentID string

Instrument identifier

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 When a null/undefined value is observed, it indicates that there is no available 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"
  }
}