/insider-module/api/insiders/clustersDetect cluster buying/selling.
Detect cluster buying/selling. Each cluster includes sector/industry classification from Sharadar.
10 tokensSince v1.5.0
Why use this
Surface high-conviction insider events: tickers where multiple distinct insiders (CEO + CFO + Directors, etc.) traded in the same direction within a recent window. The most-watched institutional signal in insider analytics — when 3+ unrelated insiders all buy in the same month, the historical hit-rate for outsized 6-month forward returns is materially higher than for single-insider signals (academic literature: Cohen-Malloy-Pomorski 2012, Lakonishok-Lee 2001). Configure the cluster strictness via `min_insiders` (default 3) and `min_value` (default $0). v3.1.1 fixed an inflation bug where multiple ownership vehicles of the same beneficial owner were counted as separate insiders — `insider_count` now correctly counts unique people, not unique entity rows. Pair with `GET /insider-module/api/insiders/recommendations/daily` for the productized buy/sell signals built on top of this detector.
Common use case
Identifying high-signal events where the CEO, CFO, and Directors all buy stock in the same week.
Detects coordinated cluster buying or selling — events where multiple distinct insiders trade the same ticker within a configurable window. Cluster definition: ≥min_insiders unique insiders trading the same ticker within the last days days, with aggregate value ≥min_value. Each cluster carries Sharadar sector/industry classification and the v3.1.1 fix that counts unique transactions (not distinct owner entities) so multiple ownership vehicles of the same beneficial owner do not inflate the cluster size. Pair with GET /insider-module/api/insiders/recommendations/daily for productized buy/sell signals built on top of cluster detection.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| days | query | optional | 30 | — | Lookback window in days (1-365). Common values: `7` (intra-week clusters, lowest noise), `30` (default — monthly clusters, standard equity-research cadence), `90` (quarterly clusters, captures slower-moving signals). Larger windows allow more transactions to qualify but dilute the time-coincidence signal. | 30 |
| min_insiders | query | optional | 3 | — | Minimum number of distinct insiders that must trade for a ticker to qualify as a cluster. `2` is permissive (catches CEO+CFO pairs); `3` (default) matches academic literature; `5+` is for very high-conviction screens. Counts UNIQUE BENEFICIAL OWNERS (post-v3.1.1 fix) — multiple LLC vehicles of the same owner count as one. | 3 |
| min_value | query | optional | — | — | Minimum aggregate USD value (`SUM(shares × price)`) across all transactions in the cluster. Use to filter out small option-exercise clusters. `1000000` (1MM) eliminates most noise; `10000000` (10MM) typically returns only material conviction events. Omit (or `0`) to include all clusters meeting the insider-count threshold. | 1000000 |
| sector | query | optional | — | — | Sharadar sector filter, case-sensitive (e.g. `Technology`, `Healthcare`, `Energy`). Restricts the cluster scan to one sector — useful for sector-rotation thesis confirmation. Tickers without Sharadar mappings are excluded when this filter is set. | Technology |
| industry | query | optional | — | — | Sharadar industry filter, case-sensitive (more specific than `sector`). Em-dash characters require URL-encoding. Most useful for niche thematic screens (e.g. all clusters in `Biotechnology` or `Semiconductors`). | Consumer Electronics |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| [] | array | no | Bare JSON array (NOT wrapped in a `data`/`status`/`meta` envelope) of detected cluster rows — one row per `(ticker, cluster_type)` pair that meets the `min_insiders` + `min_value` thresholds. Sorted by aggregate value DESC. A single ticker can appear twice if it has both BUY and SELL clusters in the window. Empty array when no qualifying clusters detected. |
| [].ticker | string | yes | Issuer ticker exhibiting cluster activity (canonical hyphen form). The natural primary key together with `cluster_type`. |
| [].company_name | string | no | Issuer name (from CompanyStub). |
| [].sector | string | yes | Sharadar sector classification for the issuer (e.g. `Technology`, `Healthcare`). Null when the ticker is unmapped in Sharadar. Useful for cluster-by-sector roll-ups (e.g. 'Healthcare had 12 buy clusters this week vs. 2 sell'). |
| [].industry | string | yes | Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar. |
| [].issuer_cik | string | yes | Issuer CIK for the clustered company. |
| [].insider_count | integer | no | Distinct UNIQUE BENEFICIAL OWNERS in the cluster (post-v3.1.1 fix — multiple LLC/trust vehicles of the same person count as one). Always ≥`min_insiders`. The signal-density metric — values of 4-5 in a `days=30` window with no overlapping 10b5-1 plans is the strongest cluster signal. |
| [].total_value | number | no | Aggregate USD value (`SUM(shares × price_per_share)`) across all transactions in the cluster. Excludes transactions with null `price_per_share` (grants, gifts). Always ≥`min_value` parameter. Use the per-cluster `total_value` ÷ ticker market cap to gauge signal materiality (whale clusters are 0.01-0.1% of mcap; routine 10b5-1 noise is < 0.01%). |
| [].net_shares | number | no | Net shares for the cluster — positive for BUY clusters, negative for SELL clusters (the sign encodes direction). Magnitude is the total share count aggregated across the cluster's transactions. |
| [].transaction_count | integer | no | Total Form 4 transaction rows aggregated into the cluster. Always ≥`insider_count` (each insider contributes ≥1 transaction). High `transaction_count` per `insider_count` ratios (e.g. 10:3) indicate either a multi-day staggered buy program or 10b5-1 grid execution — inspect individual transaction dates before alerting. |
| [].first_date | string | no | ISO `YYYY-MM-DD` of the EARLIEST transaction in the cluster window. Together with `last_date` defines the cluster's time-coincidence span — narrower spans (1-3 days) indicate higher-conviction coordinated decisions; wider spans (15-30 days) may reflect rolling executions on a pre-set plan. |
| [].last_date | string | no | ISO `YYYY-MM-DD` of the LATEST transaction in the cluster window. The closer this is to today, the more actionable the signal — clusters with `last_date` within the last 5 trading days are the typical alert target. |
| [].insiders | array | no | Participant list: array of insider NAME strings (`List[str]`, NOT objects). Length equals `insider_count`. Use to render 'who bought' tooltips in cluster-detection dashboards. |
| [].cluster_type | string | no | Cluster direction — literal string `BUY` (cluster of acquisitions) or `SELL` (cluster of dispositions). BUY clusters are typically the higher-signal direction; SELL clusters can include high-noise routine 10b5-1 plan executions and tax-withholding sales (code F). |
Sample response
·
- "ticker": "AAPL"
- "company_name": "APPLE INC"
- "sector": "Technology"
- "industry": "Consumer Electronics"
- "issuer_cik": "0000320193"
- "insider_count": 4
- "total_value": 1240000
- "net_shares": 7100
- "transaction_count": 7
- "first_date": "2026-04-09"
- "last_date": "2026-04-15"
- "insiders":
- "cluster_type": "BUY"
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/clusters?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).