/insider-module/api/insiders/holdings/snapshot/{snapshot_date}Point-in-time holdings snapshot as of a specific date.
Point-in-time holdings snapshot as of a specific date. Each row includes total_beneficial_ownership and sector/industry classification from Sharadar.
Why use this
Common use case
Time-machine view of insider holdings — reconstructs the position table AS OF a specific historical date passed as the REQUIRED {snapshot_date} path segment (ISO YYYY-MM-DD). Filter to one issuer with ticker (recommended for performance) and/or one insider with insider_cik.
Use cases: regulatory reconstructions ('what did insiders hold on 2025-09-15?'), backtesting ('compare insider conviction at quarter-ends'), audit trails for compliance teams. The implementation walks reported_date <= snapshot_date with per-vehicle MAX-date dedup, so a filing accepted AFTER snapshot_date but reporting an earlier transaction_date does NOT bleed into the snapshot — the snapshot reflects what was KNOWABLE on that date, not the post-amendment ground truth.
For live current holdings use GET /insider-module/api/insiders/holdings/by-ticker/{ticker}.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| snapshot_date | path | required | — | — | The as-of date in ISO `YYYY-MM-DD` format (REQUIRED path segment). Server walks `reported_date <= snapshot_date` with per-vehicle MAX-date dedup. Returns HTTP 400 on malformed dates. | 2026-04-01 |
| ticker | query | optional | — | — | Filter to a single issuer (recommended for performance — full-market snapshots can return many rows). When unset, scans every issuer with holdings on file. | AAPL |
| insider_cik | query | optional | — | — | Filter to a single insider (10-character zero-padded; shorter forms auto-padded). | 0001214156 |
| limit | query | optional | 100 | — | Maximum rows returned per page (1–1000). | 100 |
| offset | query | optional | 0 | — | Zero-based pagination offset. | 0 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| status | string | no | Always `success` on 2xx. |
| data | array | no | Array of insider holding rows reflecting the position table AS-OF the requested `snapshot_date`. One row per `(insider, security_title, ownership_nature, indirect_owner_name)` combination. Returns the most-recent reported holdings on or before `snapshot_date` per vehicle. Empty when the issuer has no holdings on file as of the snapshot date. |
| data[].holding_id | string | no | Stable internal UUID (serialized as a string). |
| data[].security_title | string | no | Title of the security. |
| data[].amount_owned | number | no | Number of shares (or contract units) held in this vehicle as of `snapshot_date`. |
| data[].ownership_nature | string | no | `'direct'` or `'indirect'`. |
| data[].reported_date | string | yes | ISO `YYYY-MM-DD` date of the source filing reporting this position. Always ≤ `snapshot_date`. |
| data[].indirect_owner_name | string | yes | Indirect-vehicle name when `ownership_nature='indirect'`. |
| data[].is_derivative | boolean | no | `true` for derivative positions; `false` for cash-equity. |
| data[].total_beneficial_ownership | number | yes | Aggregate shares this insider beneficially owned at this issuer across ALL vehicles AS OF `snapshot_date`. Null when the underlying filings do not report it. |
| data[].sector | string | yes | Sharadar sector classification. |
| data[].industry | string | yes | Sharadar industry classification. |
| data[].insider_name | string | yes | Reporting-person legal name. |
| data[].insider_cik | string | yes | Reporting-person CIK. |
| data[].is_entity | boolean | yes | `true` for entity reporters. |
| data[].is_director | boolean | no | Director relationship. |
| data[].is_officer | boolean | no | Officer relationship. |
| data[].is_ten_percent_owner | boolean | no | 10%-owner relationship. |
| data[].insider_title | string | yes | Officer title raw text. |
| data[].is_c_suite | boolean | no | C-suite indicator. |
| data[].ticker | string | yes | Issuer ticker. |
| data[].company_name | string | yes | Issuer name. |
| data[].issuer_cik | string | yes | Issuer CIK. |
| data[].accession_number | string | yes | Source filing accession number. |
| data[].filed_at | string | yes | ISO-8601 UTC filing acceptance timestamp. |
| meta | object | yes | Result metadata. |
| meta.snapshot_date | string | no | ISO `YYYY-MM-DD` echo of the path-parameter `snapshot_date` (verbatim — server doesn't re-format). Source of truth for the snapshot's as-of date. |
| meta.pagination | object | yes | Pagination sub-block: `{ total, limit, offset, has_more }`. |
| request_id | string | yes | Per-request UUID for log correlation. |
| timestamp | string | no | ISO-8601 UTC response timestamp. |
Sample response
- "status": "success"
- "data":
- "meta":
- "snapshot_date": "2026-04-01"
- "request_id": "c6e8b9a0-1d2e-4f3a-9b8a-2c4d5e6f7a8b"
- "timestamp": "2026-05-02T15:46:18.094Z"
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/holdings/snapshot/{snapshot_date}" \
-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).