---
title: "Form 4 event history and chart aggregates for one ticker"
method: GET
path: "/api/symbols/{ticker}/insider-trades/"
tags: ["symbols"]
---

# Form 4 event history and chart aggregates for one ticker

`GET /api/symbols/{ticker}/insider-trades/`

The complete per-ticker insider-trading payload behind
alphai.io/stock/{ticker}/insider-trades: the paginated Form 4 event
history plus everything a chart needs, in one request. One event is
a filing's whole tranche group (shares summed, the price
value-weighted, a 10b5-1 ladder is ONE event), same folding as the
feed's `insider` block.

The first page (no `cursor`) also carries the aggregates: `summary`
(3-month, 12-month and all-time windows plus the most active
insiders of the last 12 months), `series` (monthly buckets) and
`series_weekly` (Monday-keyed weekly buckets), both zero-filled up
to the current period and capped to the trailing 12 months, and
`chart_events` — every event of the trailing 12 months regardless of
pagination. The aggregates always cover both sides regardless of the
`side` filter, and they are `null` on cursor pages, which carry only
the next `events` chunk.

Side semantics on this surface follow the value flow: code P is
`buy`; codes S and D are both `sell`, because a code D sale back to
the issuer moves dollars off the insider's position like any sale.
This deliberately differs from the feed's `insider.side`, which
labels D as `other`; use `transaction_code` to tell a market sale
(S) from a sale to the issuer (D).

## Path parameters

- `ticker` string, required

## Query parameters

- `side` 'buy' | 'sell' | 'all'
- `cursor` string
- `page_size` integer

## Response `200`

One page of the event history. Empty arrays mean no recorded filings for a real listing; a ticker no symbol owns returns 404 instead.

- TickerInsiderTrades
  - `ticker` string, required
  - `coverage_start` string, date, nullable — Earliest recorded transaction date for this ticker; charts should not claim history from before it. `null` when nothing is recorded.
  - `summary` InsiderTradesSummary
    - `last_3m` InsiderTradesWindow, required — Event-level aggregates over one rolling window. Counts here are grouped EVENTS, not tranches, so they run lower than the transaction counts of `/api/symbols/{ticker}/insider-summary/`.
      - `buy_count` integer, required
      - `sell_count` integer, required
      - `buy_value_usd` string, nullable — Decimal string in USD; null when the window has no priced buys.
      - `sell_value_usd` string, nullable — Decimal string in USD; null when the window has no priced sells.
      - `unique_insiders` integer, required — Distinct reporting owners in the window.
      - `pct_10b5_1` integer, required — Share of the window's events executed under a pre-arranged 10b5-1 plan, in percent.
    - `last_12m` InsiderTradesWindow, required — Event-level aggregates over one rolling window. Counts here are grouped EVENTS, not tranches, so they run lower than the transaction counts of `/api/symbols/{ticker}/insider-summary/`.
      - `buy_count` integer, required
      - `sell_count` integer, required
      - `buy_value_usd` string, nullable — Decimal string in USD; null when the window has no priced buys.
      - `sell_value_usd` string, nullable — Decimal string in USD; null when the window has no priced sells.
      - `unique_insiders` integer, required — Distinct reporting owners in the window.
      - `pct_10b5_1` integer, required — Share of the window's events executed under a pre-arranged 10b5-1 plan, in percent.
    - `all_time` InsiderTradesWindow, required — Event-level aggregates over one rolling window. Counts here are grouped EVENTS, not tranches, so they run lower than the transaction counts of `/api/symbols/{ticker}/insider-summary/`.
      - `buy_count` integer, required
      - `sell_count` integer, required
      - `buy_value_usd` string, nullable — Decimal string in USD; null when the window has no priced buys.
      - `sell_value_usd` string, nullable — Decimal string in USD; null when the window has no priced sells.
      - `unique_insiders` integer, required — Distinct reporting owners in the window.
      - `pct_10b5_1` integer, required — Share of the window's events executed under a pre-arranged 10b5-1 plan, in percent.
    - `top_insiders` InsiderTradesTopInsider[], required — Most active reporters of the last 12 months, at most five.
      - `name` string, required
      - `title` string, required — Officer title from the filing; empty when the filer reports as a director only.
      - `event_count` integer, required
      - `net_value_usd` string, nullable — Buys minus sells in USD over the last 12 months, as a decimal string; positive means a net buyer.
  - `series` InsiderTradesMonthBucket[], nullable — Calendar-month buckets, zero-filled up to the current month and capped to the trailing 12 months. First page only; `null` on cursor pages.
    - `month` string, required — Calendar month, `YYYY-MM`.
    - `buy_count` integer, required
    - `sell_count` integer, required
    - `buy_value_usd` string, required — Decimal string in USD; `"0"` for a quiet side.
    - `sell_value_usd` string, required
  - `series_weekly` InsiderTradesWeekBucket[], nullable — ISO-week buckets keyed by their Monday, zero-filled up to the current week over the same 12-month horizon. First page only; `null` on cursor pages.
    - `week_start` string, date, required — Monday of the ISO week.
    - `buy_count` integer, required
    - `sell_count` integer, required
    - `buy_value_usd` string, required
    - `sell_value_usd` string, required
  - `chart_events` InsiderTradeEvent[], nullable — Every event of the trailing 12 months, both sides, independent of the paginated list below — a chart never shows a bar without its marks. First page only; `null` on cursor pages.
    - `side` 'buy' | 'sell', required — Value-flow label; `transaction_code` carries the raw code.
    - `transaction_code` string, required — Raw SEC Form 4 transaction code (`P`, `S`, `D`).
    - `ownership_form` 'D' | 'I', required — Direct or indirect holding pool.
    - `security_title` string — Security class from the filing; empty when unreported.
    - `shares` string, required — Total shares across the event's tranches (decimal string).
    - `avg_price_usd` string, nullable — Value-weighted average price per share over priced tranches. `null` when the filing prices no tranche.
    - `total_value_usd` string, nullable — Total USD value across priced tranches (a lower bound when some tranches are unpriced). `null` when no tranche is priced.
    - `tranche_count` integer, required — Fills folded into this event (a 10b5-1 ladder files many).
    - `stake_change_pct` string, nullable — Percent of the pre-event position this event moved, as a decimal string; sells are negative ("-26.0" = sold 26% of the stake). `null` when the pre-event position cannot be reconstructed.
    - `is_10b5_1` boolean, required — True when any tranche executed under a pre-arranged 10b5-1 plan.
    - `late_filing` boolean, required — The filing missed the SEC's two-business-day deadline, computed the same way as the feed's `InsiderEvent.late_filing`.
    - `insider_name` string, required
    - `insider_title` string, required
    - `is_officer` boolean, required
    - `is_director` boolean, required
    - `is_ten_percent_owner` boolean, required
    - `transaction_date` string, date, required — Date of the group's last fill (a ladder can span days).
    - `filed_at` string, date-time, required — When EDGAR accepted the filing (UTC).
    - `news_uid` string, required — Uid of the enriched news row fronting this event; matches `original.uid` in the feeds.
    - `news_title` string, required
    - `news_published` string, date-time, required — Publish time of the fronting news row.
    - `has_article` boolean, required — Whether the alphai.io article page for `news_uid` exists. Events ingested by the historical backfill have no enriched article; render those without a link.
  - `events` InsiderTradeEvent[], required — One page of the event history, newest first; honors `side`.
    - `side` 'buy' | 'sell', required — Value-flow label; `transaction_code` carries the raw code.
    - `transaction_code` string, required — Raw SEC Form 4 transaction code (`P`, `S`, `D`).
    - `ownership_form` 'D' | 'I', required — Direct or indirect holding pool.
    - `security_title` string — Security class from the filing; empty when unreported.
    - `shares` string, required — Total shares across the event's tranches (decimal string).
    - `avg_price_usd` string, nullable — Value-weighted average price per share over priced tranches. `null` when the filing prices no tranche.
    - `total_value_usd` string, nullable — Total USD value across priced tranches (a lower bound when some tranches are unpriced). `null` when no tranche is priced.
    - `tranche_count` integer, required — Fills folded into this event (a 10b5-1 ladder files many).
    - `stake_change_pct` string, nullable — Percent of the pre-event position this event moved, as a decimal string; sells are negative ("-26.0" = sold 26% of the stake). `null` when the pre-event position cannot be reconstructed.
    - `is_10b5_1` boolean, required — True when any tranche executed under a pre-arranged 10b5-1 plan.
    - `late_filing` boolean, required — The filing missed the SEC's two-business-day deadline, computed the same way as the feed's `InsiderEvent.late_filing`.
    - `insider_name` string, required
    - `insider_title` string, required
    - `is_officer` boolean, required
    - `is_director` boolean, required
    - `is_ten_percent_owner` boolean, required
    - `transaction_date` string, date, required — Date of the group's last fill (a ladder can span days).
    - `filed_at` string, date-time, required — When EDGAR accepted the filing (UTC).
    - `news_uid` string, required — Uid of the enriched news row fronting this event; matches `original.uid` in the feeds.
    - `news_title` string, required
    - `news_published` string, date-time, required — Publish time of the fronting news row.
    - `has_article` boolean, required — Whether the alphai.io article page for `news_uid` exists. Events ingested by the historical backfill have no enriched article; render those without a link.
  - `next_cursor` string, nullable, required — Opaque cursor for the next (older) page; `null` at the end of the recorded history.

## Other responses

- `400` — Malformed ticker
- `401` — Missing or invalid API key.
- `404` — No item with that identifier.
- `429` — Rate limit exceeded — either the per-minute burst cap or the per-day volume cap. The `Retry-After` header tells you how long to wait (a burst block is short, ≤60s; a day-cap block is capped at 3600s — the true reset is `X-RateLimit-Reset`). The `X-RateLimit-*` trio shows the daily volume budget. The body's `extra` names your tier, its `limit_per_minute` / `limit_per_day`, `retry_after_seconds`, and — below Pro — an `upgrade` block with the higher tiers' caps and the pricing URL.

---

[API](https://skmtc.net/alphai/apis/alphai-rest-api.md) · [All operations](https://skmtc.net/alphai/apis/alphai-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alphai/alphai-rest-api/revisions/d6f73c217935/schema)