Two fields answer two different questions here, and mixing them up is the usual mistake. distribution_type describes the character of one payment on /stocks/v1/dividends, and frequency describes the schedule the payment belongs to. A payment can be recurring with a frequency of 52, and a special one almost always carries a frequency of 0.
Applies to
- Plans: every Stocks plan includes dividends. The free Basic tier sees the last two years; every paid tier sees all history, whose oldest ex-dividend date is in 2000.
- Endpoints: /stocks/v1/dividends, filterable on distribution_type and frequency. The older /v3/reference/dividends still responds but is marked deprecated in the documentation, and it carries a different field, dividend_type. Its documentation lists CD (a consistent schedule), SC (special cash), and LT and ST for long-term and short-term capital gain distributions, but a filter on LT or ST returns no records.
- Asset classes: US stocks and ETFs.
The types
There are five types, and this is how often each turned up in the 5,000 most recent records by ex-dividend date:
| distribution_type | Meaning | In the sample |
|---|---|---|
| recurring | Paid on a regular schedule | 4,711 |
| special | A one-time or commemorative payment | 128 |
| unknown | Cannot be classified from what was reported | 78 |
| irregular | Unpredictable or non-recurring | 49 |
| supplemental | Extra, beyond the regular schedule | 34 |
Handle recurring and special properly and treat the other three as ordinary cash amounts rather than assuming they will not appear, because unknown alone outnumbers irregular.
How to filter by type
curl -X GET "https://api.massive.com/stocks/v1/dividends?ticker=NVDA&distribution_type=recurring&sort=ex_dividend_date.desc&limit=2&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "ticker": "NVDA", "pay_date": "2026-10-01", "ex_dividend_date": "2026-09-10",
"frequency": 4, "cash_amount": 0.25, "currency": "USD",
"distribution_type": "recurring", "split_adjusted_cash_amount": 0.25 },
{ "ticker": "NVDA", "pay_date": "2026-06-26", "ex_dividend_date": "2026-06-04",
"frequency": 4, "cash_amount": 0.25, "currency": "USD",
"distribution_type": "recurring", "split_adjusted_cash_amount": 0.25 }
]
}
Sort with sort=ex_dividend_date.desc. This endpoint defaults its sort column to ticker, so within a single ticker the order is arbitrary: ?ticker=NVDA&limit=1 with no sort returned the 2016 record, and the same request for MSFT, KO and AAPL returned 2014, 2015 and 2022. None of them is the newest. Always pass a sort when limit is small.
What frequency tells you
frequency tells you the number of payments expected in a year. It ranges wider than most people expect, because funds are in the same dataset as operating companies:
| Value | Schedule | In the same 5,000-record sample |
|---|---|---|
| 2 | Twice a year | 2,334 |
| 4 | Quarterly | 1,280 |
| 12 | Monthly | 772 |
| 0 | No regular schedule | 278 |
| 52 | Weekly | 256 |
| 1 | Annually | 73 |
| 3 | Three times a year | 4 |
| 104 | Twice weekly | 3 |
A distribution_type of special and a frequency of 0 usually travel together, but they answer different questions: the type describes the payment, the frequency describes the pattern it belongs to.
Capital gain distributions and return of capital
A fund distribution made up partly of capital gains and return of capital still comes back from /stocks/v1/dividends as one ordinary dividend record, with the whole payment in cash_amount. No field on a dividend record separates income, capital gains and return of capital, and distribution_type describes how a payment recurs rather than how it is taxed. The Gabelli Equity Trust paid $0.15 a share on 19 December 2025, of which $0.0153 was ordinary income, $0.108 long-term capital gains and $0.0267 return of capital, according to the income tax information in its annual report filed with the SEC:
curl -X GET "https://api.massive.com/stocks/v1/dividends?ticker=GAB&ex_dividend_date=2025-12-12&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "ticker": "GAB", "record_date": "2025-12-12", "pay_date": "2025-12-19",
"ex_dividend_date": "2025-12-12", "frequency": 4, "cash_amount": 0.15,
"currency": "USD", "distribution_type": "recurring" }
]
}
The Gabelli record carries the whole $0.15 as one cash amount with a distribution_type of recurring, and the deprecated /v3/reference/dividends labels the same payment CD. For the split between income, capital gains and return of capital, use the fund's own distribution notices or tax statements.
Why the type matters for a yield calculation
The type matters because a special dividend will wreck a naive trailing yield. Summing twelve months of cash_amount and dividing by the price treats a one-off payment as if it recurs, and a large special dividend can double the apparent yield of a stock that has not changed its regular payment at all. Filter to recurring, or multiply one regular payment by its frequency, depending on whether you want what was paid or what is expected.
If you see an error
An empty results array is the normal answer for most tickers: most companies pay no dividend.
A dividend that looks far too large for the ticker is usually a special record. Check distribution_type before treating it as an error.
split_adjusted_cash_amount is absent, not zero, on two kinds of record: ones whose ex-dividend date has not passed yet, and most foreign listings traded over the counter. In a 2,000-record sample of settled dividends, 1,715 carried it and 275 of the 285 that did not were F-suffix tickers. Read cash_amount and fall back to it rather than assuming the adjusted field is always present.
