Skip to content
/api/insiders/holdings/snapshot/{snapshot_date}

Holdings snapshot at a specific historical date.

Holdings snapshot at a specific historical date. Returns the rolled-up insider holdings table as it stood on that date (after applying all Form 4 transactions filed up to and including that date).

10 tokensSince v1.0.0

Why use this

Time-machine view of insider holdings — reconstructs the position table for ANY ticker (or insider, or both) AS OF the requested calendar date. The dated path-parameter form (e.g. `/snapshot/2025-09-15`) is the REST-idiomatic shape preferred for caching and audit URLs.

Common use case

Regulatory reconstructions ('what did insiders hold on the day before the leak?'), backtesting historical cluster signals, building 'change since last quarter' diff views.

Time-machine view of insider holdings — reconstructs the position table for ANY ticker (or insider, or both) AS OF the requested calendar date. The dated path-parameter form (e.g. /snapshot/2025-09-15) is the REST-idiomatic shape preferred for caching and audit URLs.

The implementation walks reported_date <= snapshot_date with per-vehicle MAX-date dedup, so a transaction filed 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. This matters for compliance audits where 'what did the world know on day X' is the relevant question.

Use cases:

  • Regulatory reconstruction — 'reproduce the insider holdings table as it stood on the day of the trading halt'.
  • Backtest cluster signals — pair with GET /insider-module/api/insiders/clusters on a different days window to see what holdings looked like at signal-fire time.
  • Quarter-end diffs — call twice with snapshot_date=2025-12-31 and snapshot_date=2026-03-31 and diff client-side.

For live current holdings (today's view) use GET /insider-module/api/insiders/holdings/by-ticker/{ticker}; for the alias variant with query-parameter as_of see GET /insider-module/api/insiders/holdings/snapshot.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
snapshot_datepathrequired——The as-of date in ISO `YYYY-MM-DD` format. Server walks `reported_date <= snapshot_date` with per-vehicle MAX-date dedup. Returns HTTP 400 on malformed dates.2026-04-01
tickerqueryoptional——Filter to a single issuer (recommended for performance — full-market snapshots can return 100K+ rows). When unset, scans every issuer with holdings on file.AAPL
insider_cikqueryoptional——Filter to a single insider (10-character zero-padded; shorter forms auto-padded). Combine with `ticker` for very narrow drill-downs (e.g. 'Cook's AAPL position on 2025-09-15').0001214156
limitqueryoptional100—Maximum rows returned per page (capped at 1000).100
offsetqueryoptional0—Zero-based pagination offset. Walk pages with `offset += limit`.0

Response schema

FieldTypeNullableDescription
statusstringnoAlways `success` on 2xx.
dataarraynoArray of insider holding rows reflecting the position table AS-OF `snapshot_date`. One row per `(insider, security_title, ownership_nature, indirect_owner_name)` combination — the most-recent reported snapshot per vehicle on or before `snapshot_date`. Sorted by `(issuer_cik, insider_name)`. Empty when no qualifying holdings.
data[].holding_idstringnoInternal UUID for the holding row, serialized as a string.
data[].security_titlestringnoTitle of the security (e.g. `Common Stock`).
data[].amount_ownednumbernoNumber of shares held in this vehicle as of `snapshot_date`. Defaults to `0` for filings missing the value.
data[].ownership_naturestringno`'direct'` or `'indirect'`. Defaults to `'direct'` when source filing's nature field is missing.
data[].reported_datestringyesISO `YYYY-MM-DD` date of the source filing reporting this position. Always ≤ `snapshot_date`.
data[].indirect_owner_namestringyesIndirect-vehicle name when `ownership_nature='indirect'`.
data[].tickerstringyesIssuer ticker (canonical hyphen form).
data[].company_namestringyesIssuer name.
data[].sectorstringyesSharadar sector classification.
data[].industrystringyesSharadar industry classification.
data[].issuer_cikstringyesIssuer CIK.
data[].insider_namestringyesReporting-person legal name (verbatim from the source filing).
data[].insider_cikstringyesReporting-person CIK.
data[].total_beneficial_ownershipnumberyesAggregate shares this insider beneficially owned at this issuer across ALL vehicles AS OF the snapshot. Null when the underlying filings do not report it.
metaobjectyesResult metadata block.
meta.snapshot_datestringnoISO `YYYY-MM-DD` echo of the path-parameter `snapshot_date` (verbatim — server doesn't re-format).
meta.paginationobjectnoPagination sub-block.
meta.pagination.totalintegernoTotal matching holding rows for the filter set.
meta.pagination.limitintegernoEffective page size.
meta.pagination.offsetintegernoEcho of requested offset.
meta.pagination.has_morebooleanno`true` when another page is available.
request_idstringyesPer-request UUID for log correlation.
timestampstringnoISO-8601 UTC response timestamp.

Sample response

·
  • "status": "success"
  • "data":
    ]
  • "meta":
    • "snapshot_date": "2026-04-01"
    • "pagination":
    }
  • "request_id": "9d4e6f7a-8b1c-4d2e-3f5a-6b7c8d9e0f1a"
  • "timestamp": "2026-05-02T15:58:32.105Z"
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/insiders/holdings/snapshot/{snapshot_date}?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).