Dividends

Parameters#

limitintegeroptional · query

Maximum records per page, from 1 to 500; default 100.Default: 100

cursorstringoptional · query

Opaque cursor, expires after one hour. Keep all query parameters unchanged. Changes to entitlements can invalidate it.

If-None-Matchstringoptional · header

ETag from a previous response. Authorization is rechecked before returning 304, and a 304 costs no credits.

symbolsstringoptional · query

Comma-separated MIC:TICKER symbols (crypto pairs are CRYPTO:BTC-USD, currency pairs FOREX:EUR-USD, indices INDEX:GSPC, bonds BOND and the ISIN, such as BOND:US00037BAF94) or bare tickers, which resolve to the exchange listing that ticker; neither part is case-sensitive, and two spellings of one listing count as a repeated value. A bare ticker that names no listing as written is also read in the common vendor spellings: with an exchange suffix (RY.TO, SHEL.L, VOD.LSE, BHP.AX), ^GSPC for INDEX:GSPC, and EURUSD=X or EURUSD for FOREX:EUR-USD. At most 100, further limited by the effective plan and key scope. A symbol names the listing recorded under it at symbol_at; at a date before any ticker is recorded for a listing, the earliest ticker recorded for it selects it as well (see symbol_at). Supply symbols or instrument_ids, or omit both for a market-wide request, which from and to must bound.

instrument_idsstringoptional · query

Comma-separated stable instrument IDs (the instrument_id of each row, and of the research endpoints) instead of symbols; each selects its listing at any date, including history from before its earliest recorded ticker and listings that no longer trade. Rows carry the symbol the listing had at symbol_at, or where it had none then, its symbol at as_of, else the last one it carried by as_of, else its first. At most 100. Cannot be combined with symbols.

exchangesstringoptional · query

Market-wide requests only (no symbols or instrument_ids): comma-separated ISO MIC codes, at most 100. Defaults to every exchange of the entitled markets. A malformed or repeated code returns 422 invalid-exchanges, a MIC the API does not serve 404 exchange-not-found, and one outside the key's markets 403 market-not-entitled.

symbol_atstringoptional · query

Resolve symbols as they were assigned at the end of this UTC date (YYYY-MM-DD); defaults to as_of. Only listings the security master holds resolve: it was built in September 2026 and records delistings from then on, so most issuers delisted earlier, such as TWTR or SIVB, resolve at no date. A ticker names the listing that carries it at symbol_at, and every row of a from/to range carries that symbol, rows from before the listing took the ticker included: a ticker reused after its earlier holder delisted returns the new holder's older rows, so set symbol_at inside the range to name the listing that traded under the ticker then. Tickers are recorded only where there is evidence for them (for many listings from 2003, though prices start earlier), and none is asserted earlier. As a lookup convenience, a date before a listing's earliest recorded ticker still finds the listing by that ticker when no record contradicts it (no listing is recorded under the ticker by that date, and the listing has no earlier ticker): its rows carry the symbol as a label and meta.unrecorded_symbols lists it. A date before the listing's first row returns 200 with no-data, as a to before it does. A ticker another listing held, or one the listing was renamed from or to, returns 404 naming the date and the listing; instrument_ids select a listing at any date.

as_ofstringoptional · query

Knowledge cutoff as a UTC date (YYYY-MM-DD): the response reflects what was known by the end of that day. Defaults to now; cannot be in the future. A date from before the dataset's knowledge history returns 422 point-in-time-unavailable naming the earliest one, which GET /v1/datasets lists as earliest_as_of.

fromstringoptional · query

First ex_date to include (YYYY-MM-DD). Required without symbols or instrument_ids.

tostringoptional · query

Last ex_date to include (YYYY-MM-DD); on or after from, so from equal to to selects one day. Required without symbols or instrument_ids, at most 365 days after from.

known_fromstringoptional · query

First UTC date (YYYY-MM-DD, inclusive) on which a revision became known. Filters eligible revisions; not a change feed or deletion log.

known_tostringoptional · query

Last UTC date (YYYY-MM-DD, inclusive) on which a revision became known; on or after known_from.

orderstringoptional · query

Direction on ex_date, asc (default) or desc; ties keep their internal order in the same direction. The cursor is bound to it.

ascdesc

Default: asc

typesstringoptional · query

Corporate-action type codes: cash_dividend or split. Any other code is accepted and matches no action.

effective_fromstringoptional · query

First UTC date (YYYY-MM-DD, inclusive) of effective_at. No current source states effective_at, so this filter matches no action today; bound ex_date with from and to instead.

effective_tostringoptional · query

Last UTC date (YYYY-MM-DD, inclusive) of effective_at; on or after effective_from. No current source states effective_at, so this filter matches no action today; bound ex_date with from and to instead.

formatstringoptional · query

Response format. csv returns the data rows with a header row, for spreadsheet functions such as IMPORTDATA; nested fields become dotted columns and lists one JSON array cell, the next page cursor is returned in X-Next-Cursor and meta.errors in X-Meta-Errors. A result without rows is the header row alone, listing the documented fields of a row. Default json, or csv when format is omitted and the Accept header ranks text/csv above JSON; a format the Accept header does not admit returns 406 not-acceptable.

jsoncsv

Response fields#

Returns data as an array of records. All example values are illustrative.

idstring

Stable public record ID; unchanged when the dividend is revised. Calculated dividend metrics (/v1/financials/metrics) list the dividends they were calculated from by this ID in input_record_ids.

security_idstring

Deprecated: the same stable public ID as instrument_id, which replaces it.Being superseded by instrument_id, which carries the same value. Read instrument_id where present; security_id remains for compatibility.

instrument_idstring

Stable public instrument ID, independent of ticker; the instrument_id of the research endpoints.

symbolstring

symbol

exchange_micstring

exchange mic

action_typestring

cash_dividend. stock_dividend is reserved: the current sources record a stock dividend paid in the listing's own shares as a split, which /v1/splits lists.

cash_dividendstock_dividend

ex_datestring · null

ex date

record_datestring · null

Record date: holders on the register at its end receive the dividend. From the corporate-action record, or, where that states none, from the exchange's announcement (announcement.record_date).

pay_datestring · null

pay date

effective_atstring · null

The instant the action takes effect, if the source states one. The current sources give dates only, so it is null: an action takes effect on its ex_date, and a dividend is paid on its pay_date.

announced_atstring · null

When the action was announced. No source states the instant: a US dividend taken from the second source carries that source's declaration date at 00:00 UTC, a date rather than a time, and every other action is null; dividends carry the declaration_date the provider supplies instead.

declaration_datestring · null

Provider declaration date when supplied; date precision does not imply a known announcement time.

frequencystring · null

The provider's payment frequency label as supplied, such as Quarterly; null when it sends none. Never inferred or filled from another source: frequency_per_year and distribution_type carry the classification. Not a reliable cadence to display: the provider labels twice-monthly payers Bimonthly and a twice-weekly one Biweekly, and calls other dividends Bimonthly that are quarterly. Show frequency_per_year, or the listing's dividend_payments_per_year from /v1/financials/metrics, instead.

is_cancelledboolean

is cancelled

legsarray

legs

frequency_per_yearinteger · null

Payments per year: 104 twice-weekly, 52 weekly, 24 semi-monthly, 12 monthly, 4 quarterly, 2 semi-annual, 1 annual; 0 for a non-recurring payment. From the provider frequency label (0 for Other or Special); when frequency is null or a label OHLC does not recognize (such as None or Unknown), from a second source's cadence for the same dividend (US listings only), as for distribution_type. Bimonthly and Biweekly, which the provider gives twice-monthly and twice-weekly payers, are never read as 6 or 26: without a second source, such a dividend is 24 or 104 when the median gap between the listing's last five regular ex-dates through it (cash dividends not labelled Other or Special) is that of twice-monthly (11 to 20 days) or twice-weekly (4 days or less) payments, else null. Null when neither states a cadence, and for Interim and Final labels.

distribution_typestring

From the provider frequency label: special for Special; irregular for Other, a one-off outside the regular schedule; recurring for a cadence label (Weekly through Annual, Interim, Final), and for Bimonthly or Biweekly where the listing's ex-date gaps confirm a cadence, as for frequency_per_year. Without a recognized label, and for US listings only, from a second source's classification of the same dividend (same listing and ex_date, matching cash amount) known by the as_of cutoff: recurring for a regular dividend with a stated cadence, special for a special one, irregular for a capital gains distribution. frequency keeps the provider's value (null, or the unrecognized label), which tells such a row from one its label classifies. unknown when neither source classifies it. The current sources never distinguish supplemental payments.

recurringspecialsupplementalirregularunknown

split_adjusted_amountstring · null

The cash leg restated for later share distributions: cash_amount x product of (split_from / split_to) over the listing's /v1/splits rows with execution_date after ex_date and on or before the as_of date, multiplied as exact fractions and rounded half up to 18 places once, trailing zeros removed. 0.82 paid before a 4-for-1 split is 0.205. Null without exactly one cash leg or an ex_date.

historical_adjustment_factorstring · null

Cumulative dividend factor from the validated adjustment factor set /v1/eod?adjustment=total_return uses at the same as_of: the product, over this dividend and every later dividend in the set effective on or before the as_of date, of (reference_close - cash_amount) / reference_close, where reference_close is the last reconciled close before that ex_date. Each factor is stored truncated to 24 places and the product is truncated to 36 places per step, as /v1/eod multiplies. total_return bars before ex_date are the raw price x this factor x the split factor of later splits, rounded half up to 6 places. 0.82 on a 100.82 close is 100 / 100.82 = 0.99186669311644514977187. Null when the set is quarantined or missing or has no factor for this dividend (stock, cancelled or future ex-date dividends).

announcementobject · null

What the exchange's own announcement of this dividend states beyond its amount and dates: currently announced by the ASX for its listings (franking, reinvestment plans, specials), null for other listings. Attached only where the announcement describes the same payment: same listing and ex_date, and an amount that agrees with the cash leg, in its currency or in the declared one (equal, or equal once the more precise is rounded to the places of the other, the two within 1%). Null when none agrees; an ETF's final distribution announced after the estimate the cash leg still carries, or a special announced with a regular dividend that the cash leg leaves out, carries none until the leg agrees. Point in time: a query with an earlier as_of sees the version of the announcement known then, or none.

Response metadata#

Responses include meta.timezone. Dataset responses include next_cursor; health and exports have their own metadata. Request tracing uses the X-Request-ID header.

When something goes wrong#

An empty data: [] is a successful query with no matching records. Invalid symbols, permissions and malformed parameters produce an RFC 9457 problem with an actionable detail.

Plans#

Requires corporate-actions.read. Access, recency and history depth come from the plan definitions the API enforces.

Free requests are limited to AAPL, NVDA, JNJ, PEP, MSFT, SPY, QQQ.

History is how far back a plan may request. How far records actually go for a symbol is history_from in dataset coverage. Nothing is real-time. Compare plans