GET /v1/dividends

GET /v1/dividends

Returns dividend history for one or more symbols. Each entry includes declaration, ex-, record, and payment dates plus the gross cash amount and currency. See corporate actions for semantics.

Request

GET /v1/dividends?symbol=KO HTTP/1.1
Host: api.oneapi.finance
Authorization: Bearer oa_live_<your_key>

Query parameters

Param	Type	Required	Notes
`symbol`	string	one of	Single symbol.
`symbols`	string	one of	Comma-separated list, max 8.
`start_date`	ISO date	no	Inclusive lower bound on `ex_date`.
`end_date`	ISO date	no	Inclusive upper bound on `ex_date`. Default now.
`outputsize`	int	no	Cap 5,000 entries per symbol.

Response

{
  "dividends": {
    "KO": {
      "annualDividend": 1.96,
      "dividendYield": 0.0312,
      "payoutRatio": 0.7421,
      "history": [
        {
          "ex_date": "2026-03-13",
          "amount": 0.49,
          "currency": "USD",
          "declaration_date": "2026-02-15",
          "payment_date": "2026-04-01",
          "record_date": "2026-03-14"
        },
        {
          "ex_date": "2025-12-13",
          "amount": 0.485,
          "currency": "USD",
          "declaration_date": "2025-11-15",
          "payment_date": "2025-12-31",
          "record_date": "2025-12-14"
        }
      ]
    }
  }
}

Field reference

Top level:

Field	Type	Notes
`dividends`	object	Map of symbol to per-symbol dividend object.

Per-symbol object:

Field	Type	Notes
`annualDividend`	number \| null	Sum of dividends paid in the trailing 12 months, source currency.
`dividendYield`	number \| null	Annual dividend / current price. Fractional rate.
`payoutRatio`	number \| null	Annual dividend / TTM EPS.
`history`	array	Dividend events, descending by `ex_date`.

History entry:

Field	Type	Notes
`ex_date`	string	ISO date. The trade date on which a buyer does not receive the dividend.
`amount`	number	Gross dividend per share, in `currency`.
`currency`	string \| null	ISO 4217.
`declaration_date`	string \| null	ISO date.
`payment_date`	string \| null	ISO date.
`record_date`	string \| null	ISO date.

The wire-format models are SymbolDividends, DividendEntry, DividendsResponse.

Examples

# Single symbol, full history
curl -H "Authorization: Bearer oa_live_..." \
  "https://api.oneapi.finance/v1/dividends?symbol=KO"

# Last 5 years across multiple holdings
curl -H "Authorization: Bearer oa_live_..." \
  "https://api.oneapi.finance/v1/dividends?symbols=KO,PEP,JNJ,MO,O&start_date=2020-01-01"

import httpx, os
from datetime import date, timedelta

HEADERS = {"Authorization": f"Bearer {os.environ['ONEAPI_KEY']}"}

def annual_income(symbols: list[str], shares: dict[str, int]) -> float:
    """Estimated next-12-month dividend income for a portfolio."""
    r = httpx.get(
        "https://api.oneapi.finance/v1/dividends",
        params={"symbols": ",".join(symbols)},
        headers=HEADERS,
        timeout=10.0,
    )
    r.raise_for_status()
    total = 0.0
    for sym, info in r.json()["dividends"].items():
        ann = info.get("annualDividend") or 0.0
        total += ann * shares.get(sym, 0)
    return total

print(annual_income(["KO", "PEP", "JNJ"], {"KO": 100, "PEP": 50, "JNJ": 30}))

const r = await fetch(
  "https://api.oneapi.finance/v1/dividends?symbols=KO,PEP,JNJ",
  { headers: { Authorization: `Bearer ${process.env.ONEAPI_KEY}` } },
);
const { dividends } = await r.json();
for (const [symbol, info] of Object.entries(dividends)) {
  console.log(`${symbol}: $${info.annualDividend?.toFixed(2)}/yr`);
}

Errors

Status	`code`	When
400	`bad_request`	Both `symbol` and `symbols`, or `symbols` longer than 8.
401	`unauthenticated`	Missing or invalid API key.
404	`not_found`	All requested symbols unknown.
429	`rate_limit`	See rate limits.
502	`upstream_failure`	All sources failed.