/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 from Sharadar.
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 | — | — | Sharadar 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 Sharadar mapping are excluded when this filter is set. | Technology |
| industry | query | optional | — | — | Sharadar 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 |
| 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 | no | 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 | integer | no | 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 | no | 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 | no | 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 (split-adjusted to most recent split via Sharadar's split-adjustment factor). Always positive; direction (acquired vs disposed) is encoded in `acquired_disposed_code`. For derivative exercises, this is the underlying-share count, not the option contract 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). Already split-adjusted to align with the `shares` field. |
| data[].transaction_value | number | no | 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 | no | 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 | Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Industrials`). Null when the issuer ticker is unmapped in Sharadar (private CUSIPs, recently-listed issuers, foreign issuers without ADRs). |
| data[].industry | string | yes | Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar. |
| 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. |
| meta | object | no | Result metadata block. |
| meta.pagination | object | no | Pagination sub-block. |
| meta.pagination.total | integer | yes | Total matching rows for the filter set. Null when `include_total=false`. |
| 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 another page is available (derived from a limit+1 probe, exact regardless of `include_total`). |
| request_id | string | yes | Per-request UUID for log correlation. |
| timestamp | string | no | ISO-8601 UTC response generation timestamp. |
Sample response
·
- "status": "success"
- "data":
- "meta":
- "pagination":
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" \
-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).