/insider-module/api/insiders/transactions/topGet largest transactions by value.
Get largest transactions by value. Each row includes total_beneficial_ownership and sector/industry classification.
10 tokensSince v1.5.0
Why use this
The 'whale activity' leaderboard — returns the largest insider buys or sells by absolute USD value over the recent rolling window, sorted descending by `transaction_value`. Drives high-conviction signal panels for retail dashboards and quant pre-screens looking for outsized cluster anchors. The cardinal-direction filter (`direction=BUY` vs `direction=SELL`) is the most-used lever; sector/industry let you drill into 'biggest tech sells this week' or 'biggest healthcare buys'. Always set `dedup_owners=true` for trading-flow analysis to avoid joint-filer inflation (an LGN $514M × 9-owner sale will show up 9× without it). Pair with `GET /insider-module/api/insiders/clusters` when you want coordinated multi-insider activity rather than individual whales.
Common use case
Spotting 'whale' activity to see where high-conviction money is moving.
Largest insider transactions by absolute value over the recent window — drives "whale activity" feeds and high-conviction signal panels. Pass dedup_owners=true to collapse joint-filer rows into one canonical row (e.g. an LGN $514M × 9-owner sale shows up at $514M, not the inflated 9× sum). Note: derivative-exercise rows with transaction_value=0 are still included and are NOT collapsed by the dedup flag — that is a separate quality issue tracked under the v3.17.0 known-limitations callout. Pair with GET /insider-module/api/insiders/clusters when you want coordinated activity instead of individual whales.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| direction | query | optional | BUY | — | Direction of trades to rank — accepts `BUY` (returns largest purchase + exercise transactions sorted by `transaction_value DESC`) or `SELL` (returns largest sale transactions). Case-insensitive. Aliases `up`/`down` are accepted for backward compatibility but `BUY`/`SELL` are canonical. | BUY |
| limit | query | optional | 50 | — | Number of top rows to return (capped at 200 server-side). Most callers want 10-50; values >100 typically only useful for backfill or CSV-export workflows. The largest individual filings can be 100-500× the median, so even small limits surface the most material flows. | 20 |
| sector | query | optional | — | — | Sector classification, case-sensitive (e.g. `Technology`, `Healthcare`, `Energy`). Restricts the leaderboard to one sector — useful for sector-rotation thesis confirmation ('which Energy names are insiders dumping?'). Rows whose ticker has no sector mapping are excluded when this filter is set. | Technology |
| industry | query | optional | — | — | Industry classification, case-sensitive (more specific than `sector` — e.g. `Software—Application`, `Biotechnology`, `Semiconductors`). Em-dash characters require URL-encoding when round-tripping. Use the `/financials/tickers` endpoint to enumerate exact valid values. | Consumer Electronics |
| dedup_owners | query | optional | false | — | Opt-in server-side joint-filer dedup (introduced v3.17.0). When `true`, joint filings collapse to one canonical row (an LGN $514M × 9-owner sale appears once at $514M, not 9× inflated to $4.6B) and gain `co_owners` + `co_owner_count` fields. CRITICAL for any trading-flow analysis — without this flag the leaderboard's top entries are dominated by joint-filer artifacts. Note: derivative-exercise rows with `transaction_value=0` are still included and are NOT collapsed by this flag (separate v3.17.0 known-limitation). | true |
| collapse_joint_filers | query | optional | false | — | Within-filing variant of `dedup_owners` (mirrors `/transactions/latest`). Collapses joint-filer rows of the SAME economic transaction reported on ONE Form 4 into a single canonical row (deterministic min `transaction_id` survivor) with an additive integer `co_owner_count` (no `co_owners` array). On this leaderboard it stops one joint trade (e.g. LGN $514M × 9 owners) from occupying 9 slots. If both `dedup_owners` and this are set, `dedup_owners` wins. Default false → byte-identical per-owner shape. | true |
| include_total | query | optional | true | — | When `true` (default) `meta.pagination.total` is the exact total row count. Set `false` to skip that `COUNT(*)` — `total` is returned as `null` while `meta.pagination.has_more` stays exact (derived from a limit+1 probe). Use on wide market-wide / sector / industry windows where the exact count would otherwise dominate latency. | false |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | Always `success` on a 2xx response. |
| data | array | yes | Top-N largest transactions, sorted by `transaction_value DESC` (largest dollar value first), tie-broken by `transaction_date DESC` then `transaction_id DESC`. Empty array if no transactions match the filters — never null. Excludes any rows where `transaction_value` is null (grants/gifts), since they have no dollar value to rank by. |
| data[].transaction_id | string | yes | Stable internal primary key from `insiders_transactions`. When `dedup_owners=true`, this is the canonical winner of the joint-filer dedup partition. Use as a deterministic deduplication key on the client side across re-runs. |
| data[].ticker | string | yes | Issuer ticker (the company whose insider is selling/buying), normalized to canonical hyphen form (e.g. `BRK-A`). Multi-class issuers preserve the class actually traded — NOT collapsed to the primary share class. |
| data[].insider_name | string | yes | Reporting-person legal name as filed on Form 4 Item 1. May be an individual or an entity (LP, fund vehicle, trust, family office). Casing preserved verbatim from the filing — do NOT use as a join key; `insider_cik` is the stable identifier. Whale-list entries are commonly entities (e.g. `GENERATION INVESTMENT MANAGEMENT LP`). |
| data[].shares | number | no | Share count for the transaction exactly as filed on the Form 4 — NOT split-adjusted server-side (preserves the as-filed view); no split-adjusted insider surface exists. Always positive; direction (acquired vs disposed) is encoded in `acquired_disposed_code`. Form 4 Table II rows are always included on this endpoint and carry the derivative transaction amount, so the value can be an option/RSU contract count rather than a common-share count. |
| data[].price_per_share | number | yes | Per-share transaction price in USD. Null only for code-A grants and code-G gifts (which are excluded from this endpoint anyway since `transaction_value` would be null). NOT split-adjusted — the as-filed price, on the same as-filed basis as the `shares` field. On Form 4 Table II rows this is the price of the derivative security itself (Table II column 8), never the strike — exercises and conversions leave column 8 blank per the SEC's instructions, so code-M rows can serve 0 here (0 is not null, so such rows are not excluded); the strike lives in the row's `conversion_or_exercise_price`. |
| data[].transaction_value | number | yes | Computed `shares × price_per_share` in USD — the sort key for this leaderboard. Always non-null on this endpoint (rows with null value are filtered out before sorting). Never adjusted for joint-filer inflation unless `dedup_owners=true` is set — read the `co_owner_count` field carefully when comparing against external sources. |
| data[].transaction_date | string | yes | ISO `YYYY-MM-DD` date the trade was executed (NOT the filing date — Form 4 has a 2-business-day disclosure window, so very recent leaderboard entries may have `transaction_date` 1-2 days before today). |
| data[].sector | string | yes | Sector classification (e.g. `Technology`, `Healthcare`, `Industrials`). Null when the issuer ticker is unmapped (private CUSIPs, recently-listed issuers, foreign issuers without ADRs). |
| data[].industry | string | yes | Industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim. |
| data[].co_owners | array | yes | Joint-filer co-owners collapsed into this canonical row. Present ONLY when `dedup_owners=true`. JSON array of `{name, cik, is_officer, is_director, is_ten_percent_owner}` objects. Length 1 = single owner; length ≥2 = joint filing. Critical for trading-flow analysis — without inspecting `co_owners` you cannot tell whether a $500M sale represents one decision-maker or nine. |
| data[].co_owner_count | integer | yes | Number of reporting owners collapsed into this canonical row. Present when `dedup_owners=true` (= length of `co_owners`) OR when `collapse_joint_filers=true` (within-filing count; no `co_owners` array). `1` = single owner; ≥2 = joint filing. |
| meta | object | yes | Result metadata block. |
| meta.pagination | object | no | Pagination sub-block. |
| meta.pagination.total | integer | yes | Total matching rows when include_total=true; null when the count is skipped. |
| meta.pagination.limit | integer | no | Effective page size after server-side capping. |
| meta.pagination.offset | integer | no | Echo of the requested offset. |
| meta.pagination.has_more | boolean | no | True when the bounded page fetch finds another matching row after this page. |
| request_id | string | yes | Per-request UUID for log correlation. |
| timestamp | string | no | ISO-8601 UTC response generation timestamp; the runtime can omit the timezone offset. |
Sample response
·
- "status": "success"
- "data":
- "meta":
- "pagination":
- "error": null
- "request_id": null
- "timestamp": "2026-05-02T15:32:18.094000"
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/insider-module/api/insiders/transactions/top?api_Token=YOUR_API_KEY&direction=BUY&limit=20§or=Technology&industry=Consumer+Electronics&dedup_owners=true&collapse_joint_filers=true&include_total=false" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).