How to Get an Upcoming Ex-Dividend Calendar via API

Use Alphanume's Dividend Capture endpoint to pull a forward ex-dividend calendar and screen it by historical recovery odds.

An ex-dividend calendar on its own just tells you what is coming. What you actually want is a calendar that also tells you how each name's ex-days have behaved in the past, so you can focus on dividends that historically recover quickly. The Alphanume Dividend Capture endpoint gives you both from one request.

The endpoint

GET https://api.alphanume.com/v1/dividend-capture

Authenticate with ?api_key=alp_your_key or an X-API-Key header. The key parameters are ticker, recovery_status, upcoming (true, 1, or yes), and future_days (default 7, max 120).

Pull the upcoming calendar

import requests

r = requests.get(
    "https://api.alphanume.com/v1/dividend-capture",
    params={"upcoming": "true", "future_days": 30, "api_key": "alp_your_key"},
)
for row in r.json()["data"]:
    print(row["date"], row["ticker"], row["cash_amount"], row["capture_yield_pct"])

The upcoming=true flag bypasses the standard 30-day delay, so you get the forward schedule even on the free tier. Set future_days up to 120 to look further out.

Screen by recovery behavior

Each name carries historical recovery statistics, including days_to_recover_breakeven and the recovered_within_1d/3d/5d/10d/20d flags. Use these to rank upcoming ex-dates by how reliably the stock has historically recovered the ex-day drop, and filter on recovery_status to keep only the favorable setups.

A simple capture workflow

• Pull the forward calendar for the next few weeks.
• Keep names with a strong historical recovery rate within your holding window.
• Weigh capture_yield_pct against drop_ratio_close to estimate the net edge.
• Track the realized outcome through recovery_status after the trade.

Access and limits

Historical data is free on a rolling 30-day delayed window and the forward calendar bypasses the delay. Pro raises the rate limit to 600 requests per minute. Start with a free Alphanume API key and the API documentation, or explore it on Alphanume.

Screening the calendar by behavior

A bare ex-dividend calendar tells you what is coming but not which events are worth trading. The value here is that each upcoming ex-date arrives attached to the name's historical recovery behavior, so you can rank the calendar by how reliably the stock has recovered the ex-day drop within your holding window.

The forward calendar via upcoming=true bypasses the standard 30-day delay and is available on the free tier, with future_days reaching up to 120 days out. Weighing capture_yield_pct against the historical drop_ratio_close gives a quick read on the net edge, and recovery_status lets you track how each trade actually resolved afterward.

Frequently asked questions

What endpoint returns the ex-dividend calendar?

GET https://api.alphanume.com/v1/dividend-capture. Pass upcoming=true to get the forward schedule, with future_days controlling how far ahead (default 7, max 120).

Does the calendar require Pro?

No. The upcoming=true forward calendar bypasses the standard 30-day delay and is available on the free tier.

How do I screen for the best capture setups?

Rank upcoming ex-dates by historical recovery behavior using the recovered_within fields and days_to_recover_breakeven, and filter on recovery_status.

What does capture_yield_pct represent?

The dividend as a percentage of price, a quick gauge of how much yield the capture is worth before accounting for the ex-day give-back.

How far ahead can I look?

Up to 120 days by setting future_days. The default is 7 days if you do not pass the parameter.