# GET /v2/events?kind=insider

**Insider transactions**

Officer and director trades — one event per reported Form 4 transaction.

## Query / path parameters

| Name | In | Type | Required | Description |
|------|----|----|----------|-------------|
| `kind` | query | string | yes | Fix to `insider` for this view (comma-combine kinds to merge timelines). Example: `insider`. |
| `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). `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: `shares`, `price`, `value` (numeric), `action`, `executive`, `title`, `security_type` (text) — e.g. `value > 1000000 AND action = 'S'`. `payload->>'…'` works too. Base columns: `ticker`, `ts`, `kind`, `payload`. Example: `value > 1000000 AND action = 'S'`. |
| `group_by` | query | string[] | no | Switch to aggregate mode. Columns (`ticker`, `kind`) and payload fields (`action`, or the explicit `payload->>'action'`) both roll up; name a key with `AS` to choose its JSON key, or let it be named for you — see [All events](/docs/endpoints/events/query). Example: `ticker`. |
| `select` | query | string[] | no | Aggregate output items (requires `group_by`). Default: group keys + `COUNT(*) AS events`. Example: `ticker, COUNT(*) AS events`. |
| `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 filing belongs to.
  - `ts` (string) — Transaction date as an ISO timestamp.
  - `kind` (string) — Always `insider` on this view.
  - `payload` (object) — The transaction.
    - `executive` (string) — Filer name.
    - `title` (string, optional) — Filer role (CEO, Director, …).
    - `action` (string) — `A` (acquisition) or `D` (disposal).
    - `shares` (number) — Shares in the transaction.
    - `price` (number) — Per-share price; 0 for grants/awards.
    - `value` (number) — `shares × price`, rounded to cents.
    - `security_type` (string, optional) — Security class (`Common Stock`, …) — part of the filing's key; two same-day filings by one executive can differ only here.

## Sample response

```json
{
  "as_of": "2026-07-30T18:20:11.000Z",
  "query": { "kind": "insider", "universe": "top_100", "since": "2026-07-01T00:00:00.000Z", "limit": 50 },
  "count": 1,
  "next_cursor": null,
  "results": [
    { "ticker": "NVDA", "ts": "2026-07-24T00:00:00.000Z", "kind": "insider",
      "payload": { "executive": "J. Doe", "title": "EVP", "action": "D",
                   "shares": 25000, "price": 176.4, "value": 4410000,
                   "security_type": "Common Stock" } }
  ]
}
```

## More examples

### Who's buying the most? (aggregate mode)

Request:

```shell
curl -G "https://api.tickerbot.io/v2/events" \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "kind=insider" \
  --data-urlencode "from=2026-08-17" \
  --data-urlencode "q=payload->>'action'='A'" \
  --data-urlencode "group_by=ticker" \
  --data-urlencode "select=ticker, SUM((payload->>'value')::numeric) AS bought"
```

Response (`200`):

```json
// Aggregate rows: { ticker, bought } sorted by the rollup.
```

## Notes

- This is [`GET /v2/events`](/docs/endpoints/events/query) with `kind=insider`; it has its own page because the payload is its own contract. The full query grammar lives there and applies here unchanged, including aggregate mode (`group_by`/`select`) for "who is buying the most" rollups.
- Cast payload numerics to filter on size. 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=insider`.

---

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