You do not have to choose, and you no longer have to do the arithmetic. A record from /stocks/v1/dividends carries both numbers side by side, so which one you read depends on whether you are reconciling against a brokerage statement from that date or comparing one payment with another across a split.
Applies to
- Plans: every Stocks plan includes dividends. The free Basic tier sees the last two years; every paid tier sees all history.
- Endpoints: /stocks/v1/dividends. The older /v3/reference/dividends is marked deprecated in the documentation and returns only cash_amount, with no adjusted field, which is why older code does this by hand.
- Asset classes: stocks and exchange-traded funds.
The two fields, on one record
Both fields sit on one record. NVDA split ten for one on 10 June 2024, and its 2024 dividends show the effect exactly:
curl -X GET "https://api.massive.com/stocks/v1/dividends?ticker=NVDA&ex_dividend_date.gte=2024-01-01&ex_dividend_date.lte=2024-12-31&sort=ex_dividend_date.desc&limit=10&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "ex_dividend_date": "2024-12-05", "pay_date": "2024-12-27", "cash_amount": 0.01, "split_adjusted_cash_amount": 0.01 },
{ "ex_dividend_date": "2024-09-12", "pay_date": "2024-10-03", "cash_amount": 0.01, "split_adjusted_cash_amount": 0.01 },
{ "ex_dividend_date": "2024-06-11", "pay_date": "2024-06-28", "cash_amount": 0.01, "split_adjusted_cash_amount": 0.01 },
{ "ex_dividend_date": "2024-03-05", "pay_date": "2024-03-27", "cash_amount": 0.04, "split_adjusted_cash_amount": 0.004 }
]
}
The March record is the only one where the two differ. It was paid at 0.04 per share on the pre-split share count, and 0.004 is that same payment expressed per current share. Every record after the split has nothing left to adjust for, so the two fields agree.
Which field to use
Which field to use is decided by the question you are asking:
| Question | Field |
|---|---|
| What did a holder receive per share that day? | cash_amount |
| How does this payment compare with a later one? | split_adjusted_cash_amount |
| What is the trailing twelve-month payout per current share? | split_adjusted_cash_amount |
| Does this reconcile with a brokerage statement from that date? | cash_amount |
A raw series of cash_amount across a split steps downward and looks like a dividend cut. NVDA's March 2024 payout of 0.04 against June's 0.01 is not a cut: each old share became ten new ones, so the same holding that received 0.04 in March received 0.01 on each of ten shares in June, which is 0.10 per old share. The adjusted series shows 0.004 against 0.01, which is the rise that actually happened.
Two adjustment fields that are not the same thing
Two fields on this endpoint both say "adjustment" and they answer different questions. Do not substitute one for the other:
- split_adjusted_cash_amount restates the cash on today's share basis. That is what this page is about.
- historical_adjustment_factor offsets the dividend's effect on historical prices. It is close to 1, around 0.997 on NVDA's 2024 records, and it has nothing to do with splits.
split_adjusted_cash_amount is absent, not zero, on records whose ex-dividend date has not passed yet, and on most foreign listings traded over the counter. It is present on a settled US-listed record whether or not a split followed: MELI has never split, and its records carry the field with the same value as cash_amount. Fall back to cash_amount rather than assuming the field is always there.
Why both are stored
Both are stored because only the unadjusted number is a fact. It is what the company declared and what the holder was paid, and it reconciles against a statement from that date. The adjusted number is a derived view that changes every time a new split happens, so storing it alone would silently rewrite history for every consumer at once. Storing both means you can have the fact and the comparison without recomputing either.
Prices are handled the other way round, so do not carry this across without checking. The aggregates endpoints return split-adjusted bars by default, and you add &adjusted=false when you want the prices as they were quoted on the day. Dividing an already-adjusted bar by the split ratio adjusts it twice.
If you see an error
A dividend series that appears to drop sharply on one date is almost always a cash_amount series crossing a split. Compare split_adjusted_cash_amount for the same records before treating it as a cut.
An empty results array with HTTP 200 means the ticker paid no dividend in that date range, which is the normal answer for most tickers. It does not indicate missing data.
A request that returns a record from the middle of a ticker's history is missing a sort. This endpoint defaults its sort column to ticker, so the order within one ticker is arbitrary, and the older order=desc parameter is ignored rather than refused.
