---
title: "Dividend-capture calendar and scorecard: answers \"which ex-dividend events are"
method: GET
path: "/v1/dividend-capture"
---

# Dividend-capture calendar and scorecard: answers "which ex-dividend events are

`GET /v1/dividend-capture`

## Request

- Base URL: `https://api.alphanume.com`
- URL: `https://api.alphanume.com/v1/dividend-capture`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Dividend-capture calendar and scorecard: answers "which ex-dividend events are
coming up, and how has capturing this name's dividend actually worked?" One row per
ex-dividend event: the full schedule (declaration/record/pay dates, cash amount,
frequency, type, annualized dividend, capture yield), the ex-day price action
(cum-day close, ex open/close, price drop and drop ratio at open and close, net
capture %), and the recovery record (breakeven price, recovery status/date, days to
recover, recovered-within 1/3/5/10/20-day flags). A drop ratio well below 1 means
the stock historically falls less than the dividend -- the raw material of a capture
strategy.

Set upcoming=true for the forward ex-div calendar (default 7 days out, up to 120 via
future_days); use `ticker` for one name's full capture history.

Requires an Alphanume Pro API key. A 403 PRO_SUBSCRIPTION_REQUIRED or
DATE_RANGE_RESTRICTED error means the key's plan does not cover the request --
it does not mean the data is missing.

## Query parameters

- `ticker` string
- `date` string
- `date_gte` string
- `date_lte` string
- `date_gt` string
- `date_lt` string
- `recovery_status` string
- `upcoming` boolean
- `future_days` integer

## Response `200`

Matching rows.

- Envelope
  - `count` integer, required
  - `data` object[], required

## Other responses

- `400`: Invalid or conflicting query parameters.
- `401`: Missing or unrecognized API key.
- `403`: PRO_SUBSCRIPTION_REQUIRED: the key's plan does not include API access; every endpoint requires an active Pro subscription. DATE_RANGE_RESTRICTED: a legacy free-tier key asked for dates outside its window. In both cases the data is not missing.
- `429`: Rate limit exceeded (600/min); the body carries retry_after_seconds.

---

[API](https://skmtc.dev/alphanume/apis/alphanume-api.md) · [All operations](https://skmtc.dev/alphanume/apis/alphanume-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alphanume/apis/alphanume-api/revisions/2cb83f10bba4?raw)