# GET /v2/events?kind=dividend

**Dividends**

Cash-dividend declarations, one event per declaration, timestamped at the ex-dividend date.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `kind` | query | string | yes | Fix to `dividend` for this view (comma-combine kinds to merge timelines). Example: `dividend`. |
| `ticker` | query | string | no | Single symbol. Beats `tickers` when both are passed. Example: `NVDA`. |
| `tickers` | query | string[] | no | Comma-separated symbols, up to 50. Not combinable with `universe`; `ticker` wins when both are passed. Example: `AAPL,MSFT`. |
| `universe` | query | string | no | System or caller-owned universe slug. Example: `top_100`. |
| `from` | query | string | no | `YYYY-MM-DD` or ISO timestamp (inclusive). Set to today for the calendar read. `since` is accepted as an alias. Example: `2026-09-14`. |
| `to` | query | string | no | `YYYY-MM-DD` or ISO timestamp — a bare `YYYY-MM-DD` means through the end of that day; timestamps are exclusive. `until` is accepted as an alias. Example: `2026-06-28`. |
| `q` | query | string | no | SQL filter. This kind's payload fields are first-class typed columns here: `amount`, `frequency` (numeric), `ex_date`, `pay_date`, `record_date`, `declared_date` (date), `dividend_type` (text) — e.g. `amount > 1 AND frequency = 4`. `payload->>'…'` works too. Base columns: `ticker`, `ts`, `kind`, `payload`. Example: `amount > 1 AND frequency = 4`. |
| `limit` | query | integer | no | Rows per page. Max 1000. Default: `50`. Example: `5`. |
| `cursor` | query | string | no | Opaque cursor from the previous response. |

## Returns

- `as_of` (string) — Server time this response was assembled (ISO 8601).
- `query` (object) — Your filters, echoed.
- `count` (number) — Rows in this page.
- `next_cursor` (string) — Opaque token for the next page; `null` on the last page. Pass it back as `cursor`.
- `results` (array) — One row per event, newest first.
  - `ticker` (string) — Symbol the declaration belongs to.
  - `ts` (string) — Ex-dividend date as an ISO timestamp — the event's timeline position.
  - `kind` (string) — Always `dividend` on this view.
  - `payload` (object) — The declaration.
    - `amount` (number) — Cash amount per share (USD).
    - `ex_date` (string) — Ex-dividend date (same day as `ts`).
    - `pay_date` (string, optional) — Payment date.
    - `record_date` (string, optional) — Record date.
    - `declared_date` (string, optional) — Declaration date.
    - `dividend_type` (string, optional) — `CD` (regular cash) or `SC` (special); some rows carry `recurring`.
    - `frequency` (number, optional) — Payments per year (4 = quarterly).

## Sample response

```json
{
  "as_of": "2026-07-30T18:20:11.000Z",
  "query": { "kind": "dividend", "universe": "top_100", "since": "2026-07-30T00:00:00.000Z", "limit": 50 },
  "count": 2,
  "next_cursor": null,
  "results": [
    { "ticker": "JNJ", "ts": "2026-08-25T00:00:00.000Z", "kind": "dividend",
      "payload": { "amount": 1.30, "ex_date": "2026-08-25", "pay_date": "2026-09-09",
                   "record_date": "2026-08-25", "declared_date": "2026-07-14",
                   "dividend_type": "CD", "frequency": 4 } },
    { "ticker": "PG", "ts": "2026-08-14T00:00:00.000Z", "kind": "dividend",
      "payload": { "amount": 1.05, "ex_date": "2026-08-14", "pay_date": "2026-09-02",
                   "record_date": "2026-08-14", "declared_date": "2026-07-08",
                   "dividend_type": "CD", "frequency": 4 } }
  ]
}
```

## More examples

### Special dividends over $1/share, this year

Request:

```shell
curl -G "https://api.tickerbot.io/v2/events" \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "kind=dividend" \
  --data-urlencode "from=2026-02-18" \
  --data-urlencode "q=payload->>'dividend_type'='SC' AND (payload->>'amount')::numeric > 1"
```

Response (`200`):

```json
// Same envelope — only rows whose payload matches the filter.
```

## Notes

- This is [`GET /v2/events`](/docs/endpoints/events/query) with `kind=dividend`; it has its own page because the payload is its own contract. The full query grammar (`q`, `group_by`/`select`/`having`, `join=state`, cursor rules) lives there and applies here unchanged.
- Future-dated declarations appear as soon as they are announced, so the stream doubles as a dividend calendar. Latency: daily, via the evening ET ingestion pipeline.
- To be pushed instead of polling, create an event-trigger webhook: [`POST /v2/webhooks`](/docs/endpoints/webhooks/create) with `trigger.kinds=dividend`.
- Single-ticker scope: pass `ticker=X` here. (The legacy per-symbol spelling [`GET /v2/tickers/{ticker}/events`](/docs/endpoints/tickers/events) is deprecated with a 2026-10-31 sunset.)

---

Interactive sandbox + parameter editor: https://tickerbot.io/docs/endpoints/events/dividends