# Insider Trading API — Finradar API > Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: fb0d940f > Fetch this file at: https://uat.finradarapi.com/llms/insider-trading-api.txt ## Authentication All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter. --- ## Insider Trading API Real-time analysis of Form 4 data. All transaction endpoints include total_beneficial_ownership — the sum of shares owned across all ownership vehicles (direct + indirect trusts/entities) per insider per company. ### GET /insider-module/api/insiders/transactions/latest Get latest live insider transactions. Each row includes total_beneficial_ownership aggregated across all ownership vehicles and sector/industry classification from Sharadar. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on a 2xx response. Use the HTTP status code (not this field) for error branching. - `data` (array): Array of transaction rows ordered by `filed_at DESC` (most recent filing first). One row per `(transaction × reporting_owner)` pair by default; one row per economic transaction when `dedup_owners=true`. Empty array when no rows match — never null. - `data[].transaction_id` (string (nullable)): Stable internal primary key from the `insiders_transactions` table, serialized as a string. Safe to use as a deduplication key on the client. When `dedup_owners=true`, this is the canonical winner of the joint-filer dedup partition (deterministic by lowest `transaction_id`). - `data[].transaction_date` (string (nullable)): ISO `YYYY-MM-DD` date the trade was executed (Form 4 Item 3, NOT the filing acceptance date). Trade dates can pre-date `filed_at` by up to 2 business days under the SEC's filing window. - `data[].transaction_code` (string (nullable)): Raw SEC Form 4 transaction code — `P` (open-market purchase), `S` (open-market sale), `A` (grant), `M` (exercise of derivative), `G` (gift), `F` (tax withholding), `D`/`J`/`K`/`L`. For the FinRadar-normalized 6-bucket version see `standard_type` on `/transactions/search`. - `data[].transaction_description` (string (nullable)): Human-readable description of the transaction code (e.g. 'Open-market purchase' for `P`). Joined from the `transaction_codes` lookup table. - `data[].acquired_disposed_code` (string (nullable)): `A` (Acquired) or `D` (Disposed) — the SEC's directional flag, orthogonal to `transaction_code`. - `data[].shares` (number): Share count for the transaction (split-adjusted to most recent split via Sharadar's split-adjustment factor). Always non-negative; direction encoded in `acquired_disposed_code`. For derivative exercises, this is the underlying-share count, not the option contract count. Defaults to `0.0` for filings missing this field. - `data[].price_per_share` (number (nullable)): Per-share transaction price in USD, rounded to 2 decimals (Form 4 Item 5). Null for code-A grants and code-G gifts (no consideration). Already split-adjusted to align with the `shares` field. - `data[].transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD, rounded to 2 decimals. Null when `price_per_share` is null. Use for `min_value`/`max_value` filtering — combine with `dedup_owners=true` for trading-flow analysis to avoid joint-filer double-counting. - `data[].shares_owned_following` (number (nullable)): Per-vehicle holdings after this transaction (the Form 4 Table I/II 'Amount of Securities Beneficially Owned Following Reported Transaction(s)' field). NOT the rolled-up cross-vehicle total — for that, query `/insider-module/api/insiders/insider/{insider_cik}` and read `ownership_summary`. - `data[].value_owned_following` (number (nullable)): Computed `shares_owned_following × price_per_share` in USD (rounded to 2 decimals). Null when either input is null. Approximation of position value at execution price — does NOT update with subsequent market movement. - `data[].ownership_nature` (string (nullable)): `D` (Direct — held in own name) or `I` (Indirect — held via trust, LLC, family member, etc.). Indirect positions surface a name in `indirect_owner_name`. - `data[].is_derivative` (boolean (nullable)): `true` for option exercises, RSU vests, warrant grants (Form 4 Table II); `false` for cash-equity transactions (Table I). Distinguishes underlying-share counts from option-contract counts. - `data[].is_rule_10b5_1` (boolean): `true` when the transaction was executed under a pre-planned 10b5-1 trading plan (flagged via Form 4 footnote heuristics). Defaults to `false` when not flagged. Combine with `exclude_10b5_1=true` (when calling supersets like `/transactions/search`) to drop noise from discretionary-conviction screens. - `data[].is_cashless_exercise` (boolean): `true` for option-exercise-and-immediate-sale patterns (computed at query time via the Phase-31 cashless-indicator helper). Cashless exercises net-zero the insider's share position and are noisy live signals. - `data[].excess_shares_sold` (number (nullable)): When `is_cashless_exercise=true`, the count of shares sold above the exercise count (the insider's actual net unwind). Null when not a cashless pattern. Indicates incremental conviction beyond the mechanical exercise. - `data[].insider_name` (string (nullable)): Reporting-person legal name as filed on Form 4 Item 1. May be an individual or an entity (LP, fund vehicle, trust). Casing preserved verbatim — do NOT use as a join key; `insider_cik` is the stable identifier. - `data[].insider_cik` (string (nullable)): SEC-issued reporting-person CIK as a 10-character zero-padded string. Same insider may file at multiple companies — combine `insider_cik + ticker` for per-issuer position tracking. - `data[].is_entity` (boolean (nullable)): `true` when the reporting owner is an entity (LP, fund vehicle, trust, family office); `false` for individuals. - `data[].is_director` (boolean): `true` if the insider's relationship to the issuer is `director` (Form 4 Item 1 checkbox). - `data[].is_officer` (boolean): `true` if the insider's relationship to the issuer is `officer`. - `data[].is_ten_percent_owner` (boolean): `true` if the insider holds ≥10% of any class of registered equity — triggers Section 16 disclosure obligations. - `data[].is_other` (boolean): `true` if the insider's relationship is the catch-all 'Other' (with free-text in `other_description`). - `data[].other_description` (string (nullable)): Free-text relationship label when `is_other=true` — e.g. 'Designee' or 'Trustee'. Null when not 'Other'. - `data[].beneficial_ownership_pct` (number (nullable)): Beneficial-ownership percentage of the registered class (0..100). Null when not disclosed (most non-10%-owner filings). - `data[].insider_title` (string (nullable)): Officer title as raw text from the filing (e.g. `'Chief Executive Officer'`, `'Sr VP, Engineering'`). Null when not an officer. - `data[].officer_title_standardized` (string (nullable)): Officer title normalized to FinRadar's controlled vocabulary (CEO/CFO/COO/CIO/CTO/General Counsel/etc.). Null when no canonical mapping exists. - `data[].is_c_suite` (boolean): `true` when `officer_title_standardized` resolves to a C-suite role. - `data[].seniority_rank` (integer (nullable)): Numeric seniority ranking (1=highest, e.g. CEO; lower numbers = higher rank). Null when no canonical title mapping. - `data[].is_section_16_officer` (boolean (nullable)): `true` for Section-16 officers (CEO/CFO/COO/President/principal-accounting-officer subset). - `data[].is_named_executive_officer` (boolean (nullable)): `true` for Named Executive Officers per the most-recent DEF 14A. Null for issuers without a recent proxy match. - `data[].title_category` (string (nullable)): Coarse title category — `executive`, `finance`, `legal`, `technology`, `operations`, etc. - `data[].ticker` (string (nullable)): Issuer ticker (canonical hyphen form, e.g. `BRK-A`). May be null for issuers whose primary exchange ticker has not been resolved. - `data[].company_name` (string (nullable)): Issuer name from the filings table. - `data[].sector` (string (nullable)): Sharadar sector classification. Null when the issuer ticker is unmapped. - `data[].industry` (string (nullable)): Sharadar industry classification. Null when unmapped. Em-dash characters preserved verbatim. - `data[].issuer_cik` (string (nullable)): Issuer CIK (10-character zero-padded). - `data[].security_type` (string (nullable)): Security title from the filing (e.g. `Common Stock`, `Class A Common Stock`, `Stock Option`). - `data[].security_class` (string (nullable)): Normalized security class (`Class A`, `Class B`, etc.) when discriminable from `security_type`. - `data[].is_common_stock` (boolean (nullable)): `true` for cash-equity common-stock rows; `false` for preferred / warrant / option / RSU rows. - `data[].share_class` (string (nullable)): Share class indicator for multi-class issuers (`A`, `B`, etc.). - `data[].accession_number` (string (nullable)): Source filing's SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/insider-module/api/insiders/filings/{accession_number}` for the full filing tree. - `data[].form_type` (string (nullable)): Form type: `3`, `4`, `5`, `4/A`, etc. Filtered server-side to insider-trading forms. - `data[].filing_date` (string (nullable)): ISO-8601 UTC timestamp mirroring `filed_at` (pre-Phase-65 alias kept for back-compat). - `data[].filed_at` (string (nullable)): ISO-8601 UTC timestamp the filing was accepted by SEC EDGAR. - `data[].accepted_at` (string (nullable)): ISO-8601 UTC timestamp of EDGAR acceptance (typically equal to or seconds after `filed_at`). - `data[].published_at` (string (nullable)): ISO-8601 UTC timestamp the filing first appeared in the SEC EDGAR RSS feed (the FinRadar ingestion-discovery moment). - `data[].rss_updated_at` (string (nullable)): ISO-8601 UTC timestamp of the most recent RSS update for this filing (re-fires when EDGAR re-publishes; rare). - `data[].updated_at` (string (nullable)): ISO-8601 UTC timestamp of the last FinRadar-side update (parser re-runs, ticker remapping). - `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` Form 4 Item 3 — the period this filing covers (typically the largest constituent trade date). - `data[].is_late` (boolean (nullable)): `true` when the filing was submitted past the SEC Section-16 2-business-day deadline. Null when timeliness data is unavailable. - `data[].business_days_to_file` (integer (nullable)): Business days between `transaction_date` and `filed_at`. Values >2 indicate late filings. - `data[].is_amendment` (boolean (nullable)): `true` for Form `*/A` amendments. Amendments supersede their original filing for downstream rollups. - `data[].indirect_owner_name` (string (nullable)): When `ownership_nature='I'`, the name of the indirect-ownership vehicle (e.g. `'GRAT Trust 2024'`, `'Family Limited Partnership'`). Null for direct ownership. - `data[].equity_swap_involved` (boolean): `true` when the transaction involved an equity-swap derivative (rare; relevant for total-return-swap unwind analysis). - `data[].xml_url` (string (nullable)): Direct URL to the SEC EDGAR XML primary document. Stable per-accession. - `data[].index_url` (string (nullable)): Direct URL to the SEC EDGAR filing index page (HTML). Lists all documents in the filing. - `data[].owner_id` (string (nullable)): Internal FinRadar `ReportingOwner` UUID (the unified-holder identifier). Distinct from `insider_cik` — `owner_id` survives CIK reassignments. - `data[].non_derivative_holding_count` (integer): Count of non-derivative holdings rows in the parent filing (Form 4 Table I holdings — positions held but not transacted). - `data[].derivative_holding_count` (integer): Count of derivative holdings rows in the parent filing (Form 4 Table II holdings). - `data[].footnote_count` (integer): Count of footnotes attached to the parent filing. Footnotes carry crucial qualifying context (10b5-1 plan dates, gift-recipient identities, transfer-on-death assignments) — for the full text query `/insider-module/api/insiders/filings/{accession_number}`. - `data[].co_owners` (array (nullable)): Present ONLY when `dedup_owners=true`. JSON array of `{name, cik, is_officer, is_director, is_ten_percent_owner}` objects representing the joint-filer co-owners collapsed into this canonical row. - `data[].co_owner_count` (integer (nullable)): Length of `co_owners`. Present ONLY when `dedup_owners=true`. `1` = single owner (no joint filing); ≥2 = joint filing. - `meta` (object (nullable)): Result metadata block carrying pagination state. - `meta.pagination` (object): Pagination sub-block: `{total, limit, offset, has_more}`. - `meta.pagination.total` (integer): Total matching rows for the full filter set (parallel COUNT query — not just the size of the returned page). - `meta.pagination.limit` (integer): Effective page size after server-side capping. - `meta.pagination.offset` (integer): Echo of the requested offset. - `meta.pagination.has_more` (boolean): `true` when `offset + limit < total` — i.e. another page is available. - `request_id` (string (nullable)): Per-request UUID for log correlation. Forward to support tickets to accelerate triage. - `timestamp` (string): ISO-8601 UTC timestamp the response was generated. **Since:** v1.0.0 **Utility:** Real-time feed of all insider trades as they are filed. **Use case:** Building a news terminal or algorithmic trading signal based on immediate insider activity. **Parameters:** - `limit` (query, optional, default: 50): Limit results - `standard_type` (query, optional): Normalized transaction-type filter — accepts `purchase` (SEC code P), `sale` (S), `grant` (A), `exercise` (M/X/C/O), `gift` (G), or `other` (every remaining code: F tax-withholding, D, J, K, …). FinRadar's mapping of the SEC's 10+ raw Form 4 codes into the 6 buckets analysts filter on. Omit to include all types; an unrecognized value returns HTTP 422. - `sector` (query, optional): Filter by sector (e.g., Technology, Healthcare). Case-sensitive, Sharadar classification. - `industry` (query, optional): Filter by industry (e.g., Software, Biotechnology). Case-sensitive, Sharadar classification. - `dedup_owners` (query, optional, default: false): When false (default) returns one row per (transaction × reporting_owner) — industry-standard per-owner shape, byte-identical to pre-Phase-65 production. When true, joint-filer rows are collapsed into a single canonical row per economic transaction; the response gains co_owners (JSON array of {name, cik, is_officer, is_director, is_ten_percent_owner}) and co_owner_count (int). Use this to avoid double-counting flow on PE LP+GP+manager / 13D group / SPAC sponsor filings. - `include_total` (query, optional, default: true): When `true` (default) `meta.pagination.total` is the exact total row count for the full matched set. Set `false` to skip that `COUNT(*)` — `total` is returned as `null` while `meta.pagination.has_more` stays exact (derived from a limit+1 probe). On wide market-wide / sector / industry windows the exact count is a multi-million-row scan that dominates latency; opting out returns the page in a fraction of the time. Entity-scoped queries (by-ticker) are already selective and ignore this flag. **Sample response:** ```json { "status": "success", "data": [ { "transaction_id": "9341128", "transaction_date": "2026-04-15", "transaction_code": "S", "transaction_description": "Open-market sale", "acquired_disposed_code": "D", "shares": 50000, "price_per_share": 175.25, "transaction_value": 8762500, "shares_owned_following": 3229012, "value_owned_following": 565884853, "ownership_nature": "D", "is_derivative": false, "is_rule_10b5_1": true, "is_cashless_exercise": false, "excess_shares_sold": null, "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_director": false, "is_officer": true, "is_ten_percent_owner": false, "is_other": false, "other_description": null, "beneficial_ownership_pct": null, "insider_title": "Chief Executive Officer", "officer_title_standardized": "CEO", "is_c_suite": true, "seniority_rank": 1, "is_section_16_officer": true, "is_named_executive_officer": true, "title_category": "executive", "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "security_type": "Common Stock", "security_class": null, "is_common_stock": true, "share_class": null, "accession_number": "0001127602-26-001234", "form_type": "4", "filing_date": "2026-04-15T20:14:32+00:00", "filed_at": "2026-04-15T20:14:32+00:00", "accepted_at": "2026-04-15T20:14:35+00:00", "period_of_report": "2026-04-15", "is_late": false, "business_days_to_file": 0, "is_amendment": false, "non_derivative_holding_count": 0, "derivative_holding_count": 0, "footnote_count": 1 } ], "meta": { "pagination": { "total": 1428, "limit": 50, "offset": 0, "has_more": true } }, "request_id": "f7c5a3a2-3c1c-4f3a-9b8a-2c4d5e6f7a8b", "timestamp": "2026-05-02T15:32:18.094Z" } ``` ### GET /insider-module/api/insiders/transactions/by-ticker/{ticker} Get insider transactions for a specific ticker. Each row includes total_beneficial_ownership and sector/industry classification from Sharadar. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of insider transaction rows scoped to the requested issuer ticker. Sorted by `filed_at DESC`. Empty array when the ticker exists but has no qualifying transactions in the date range — never null. Returns HTTP 404 when the ticker cannot be resolved to an issuer CIK at all. - `data[].transaction_id` (string (nullable)): Stable internal primary key. When `dedup_owners=true`, the canonical winner of the joint-filer dedup partition. - `data[].transaction_date` (string (nullable)): ISO `YYYY-MM-DD` trade execution date (Form 4 Item 3). - `data[].transaction_code` (string (nullable)): Raw SEC Form 4 transaction code (P/S/A/M/G/F/D/J/K/L). - `data[].transaction_description` (string (nullable)): Human-readable code description (e.g. 'Open-market purchase' for `P`). - `data[].acquired_disposed_code` (string (nullable)): `A` (Acquired) or `D` (Disposed). - `data[].shares` (number): Share count (split-adjusted to most recent split). - `data[].price_per_share` (number (nullable)): Per-share USD price, rounded to 2 decimals. Null for grants/gifts. - `data[].transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD. - `data[].shares_owned_following` (number (nullable)): Per-vehicle holdings after the transaction (NOT cross-vehicle total). - `data[].value_owned_following` (number (nullable)): Computed `shares_owned_following × price_per_share` in USD. - `data[].ownership_nature` (string (nullable)): `D` (Direct) or `I` (Indirect — held via trust/LLC/family). - `data[].is_derivative` (boolean (nullable)): `true` for option exercises, RSU vests, warrant grants (Form 4 Table II). - `data[].is_rule_10b5_1` (boolean): `true` when executed under a pre-planned 10b5-1 trading plan. - `data[].is_cashless_exercise` (boolean): `true` for option-exercise-and-immediate-sale patterns. - `data[].excess_shares_sold` (number (nullable)): Shares sold above the exercise count when `is_cashless_exercise=true`. - `data[].insider_name` (string (nullable)): Reporting-person legal name (verbatim from Form 4 Item 1). - `data[].insider_cik` (string (nullable)): Reporting-person CIK (10-character zero-padded). - `data[].is_entity` (boolean (nullable)): `true` for entity reporters (LP, fund, trust); `false` for individuals. - `data[].is_director` (boolean): Insider's director relationship to this issuer. - `data[].is_officer` (boolean): Insider's officer relationship to this issuer. - `data[].is_ten_percent_owner` (boolean): Insider's 10%-beneficial-owner relationship to this issuer. - `data[].is_other` (boolean): Insider's catch-all 'Other' relationship. - `data[].other_description` (string (nullable)): Free-text relationship label when `is_other=true`. - `data[].beneficial_ownership_pct` (number (nullable)): Beneficial-ownership percentage (0..100). Null when not disclosed. - `data[].insider_title` (string (nullable)): Officer title raw text from the filing. - `data[].officer_title_standardized` (string (nullable)): Officer title normalized to FinRadar's controlled vocabulary. - `data[].is_c_suite` (boolean): `true` for CEO/CFO/COO/CIO/CTO/General Counsel. - `data[].seniority_rank` (integer (nullable)): Numeric seniority ranking (1=highest). - `data[].is_section_16_officer` (boolean (nullable)): `true` for Section-16 officers. - `data[].is_named_executive_officer` (boolean (nullable)): `true` for Named Executive Officers per most-recent DEF 14A. - `data[].title_category` (string (nullable)): Coarse title category. - `data[].ticker` (string (nullable)): Issuer ticker — equals the requested path parameter (canonical hyphen form). - `data[].company_name` (string (nullable)): Issuer name. - `data[].sector` (string (nullable)): Sharadar sector classification. Null when unmapped. - `data[].industry` (string (nullable)): Sharadar industry classification. Null when unmapped. - `data[].issuer_cik` (string (nullable)): Issuer CIK (10-character zero-padded). - `data[].security_type` (string (nullable)): Security title (e.g. `Common Stock`, `Class A Common Stock`). - `data[].security_class` (string (nullable)): Normalized security class (`Class A`, `Class B`). - `data[].is_common_stock` (boolean (nullable)): `true` for cash-equity common-stock rows. - `data[].share_class` (string (nullable)): Share class indicator for multi-class issuers. - `data[].accession_number` (string (nullable)): Source filing accession number. - `data[].form_type` (string (nullable)): Form type (`3`, `4`, `5`, `4/A`, etc.). - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `data[].filing_date` (string (nullable)): Mirror of `filed_at` (back-compat alias). - `data[].accepted_at` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp. - `data[].published_at` (string (nullable)): ISO-8601 UTC RSS-publication timestamp. - `data[].rss_updated_at` (string (nullable)): ISO-8601 UTC most-recent RSS update. - `data[].updated_at` (string (nullable)): ISO-8601 UTC last FinRadar-side update. - `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` Form 4 Item 3 period. - `data[].is_late` (boolean (nullable)): `true` when filed past the 2-business-day deadline. - `data[].business_days_to_file` (integer (nullable)): Business days between trade and filing. - `data[].is_amendment` (boolean (nullable)): `true` for `*/A` amendments. - `data[].indirect_owner_name` (string (nullable)): Indirect-ownership vehicle name when `ownership_nature='I'`. - `data[].equity_swap_involved` (boolean): `true` for equity-swap derivative involvement. - `data[].xml_url` (string (nullable)): SEC EDGAR XML primary document URL. - `data[].index_url` (string (nullable)): SEC EDGAR filing index page URL. - `data[].owner_id` (string (nullable)): Internal ReportingOwner UUID. - `data[].non_derivative_holding_count` (integer): Form 4 Table I holdings count for the parent filing. - `data[].derivative_holding_count` (integer): Form 4 Table II holdings count for the parent filing. - `data[].footnote_count` (integer): Footnote count on the parent filing. - `data[].co_owners` (array (nullable)): Present ONLY when `dedup_owners=true`. Joint-filer co-owners array. - `data[].co_owner_count` (integer (nullable)): Length of `co_owners` (only when `dedup_owners=true`). - `meta` (object (nullable)): Result metadata block. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total matching rows for the filter set. - `meta.pagination.limit` (integer): Effective page size after server-side capping. - `meta.pagination.offset` (integer): Echo of the requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response generation timestamp. **Since:** v1.0.0 **Utility:** View all insider trades for one company. **Use case:** Analyzing insider activity for a specific stock like TSLA — see who bought/sold and their total holdings. **Parameters:** - `ticker` (path, required): Stock Ticker (e.g. TSLA) - `limit` (query, optional, default: 50): Limit results - `filed_at_days` (query, optional, default: 7): Filter by filing date (days ago). - `transaction_days` (query, optional): Filter by transaction date (days ago). - `standard_type` (query, optional): Normalized transaction-type filter — accepts `purchase` (SEC code P), `sale` (S), `grant` (A), `exercise` (M/X/C/O), `gift` (G), or `other` (every remaining code: F tax-withholding, D, J, K, …). FinRadar's mapping of the SEC's 10+ raw Form 4 codes into the 6 buckets analysts filter on. Omit to include all types; an unrecognized value returns HTTP 422. - `dedup_owners` (query, optional, default: false): Opt-in server-side joint-filer dedup. When true, collapses (transaction × reporting_owner) duplicates into one canonical row per economic transaction and adds co_owners JSON array + co_owner_count. Default-path response shape unchanged. **Sample response:** ```json { "status": "success", "data": [ { "transaction_id": "9341128", "transaction_date": "2026-04-15", "transaction_code": "S", "transaction_description": "Open-market sale", "acquired_disposed_code": "D", "shares": 50000, "price_per_share": 175.25, "transaction_value": 8762500, "shares_owned_following": 3229012, "value_owned_following": 565884853, "ownership_nature": "D", "is_derivative": false, "is_rule_10b5_1": true, "is_cashless_exercise": false, "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_officer": true, "is_director": false, "is_ten_percent_owner": false, "insider_title": "Chief Executive Officer", "officer_title_standardized": "CEO", "is_c_suite": true, "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "security_type": "Common Stock", "accession_number": "0001127602-26-001234", "form_type": "4", "filed_at": "2026-04-15T20:14:32+00:00", "period_of_report": "2026-04-15", "is_amendment": false, "footnote_count": 1 }, { "transaction_id": "9339884", "transaction_date": "2026-04-08", "transaction_code": "P", "transaction_description": "Open-market purchase", "acquired_disposed_code": "A", "shares": 12000, "price_per_share": 168.42, "transaction_value": 2021040, "shares_owned_following": 152841, "ownership_nature": "D", "is_derivative": false, "is_rule_10b5_1": false, "is_cashless_exercise": false, "insider_name": "MAESTRI LUCA", "insider_cik": "0001513362", "is_officer": true, "insider_title": "Chief Financial Officer", "officer_title_standardized": "CFO", "is_c_suite": true, "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "security_type": "Common Stock", "accession_number": "0001127602-26-001102", "form_type": "4", "filed_at": "2026-04-08T18:42:11+00:00", "period_of_report": "2026-04-08", "is_amendment": false } ], "meta": { "pagination": { "total": 47, "limit": 100, "offset": 0, "has_more": false } }, "request_id": "8a4d2e1c-bd8a-4f81-9e21-c32d40bf9e45", "timestamp": "2026-05-02T15:34:11.205Z" } ``` ### GET /insider-module/api/insiders/transactions/by-insider/{cik} Get all transactions by a specific insider (CIK). Each row includes total_beneficial_ownership and sector/industry classification from Sharadar. Response includes ownership_summary with per-company vehicle breakdown. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of transaction rows scoped to this insider across ALL issuers (or a single issuer when `ticker` is set). Sorted by `transaction_date DESC`. Empty array when the insider has no qualifying transactions in the date range — never null. Returns HTTP 404 when the insider CIK cannot be resolved at all. - `data[].transaction_id` (string (nullable)): Stable internal primary key. When `dedup_owners=true`, the canonical winner of the joint-filer dedup partition (only present for joint filings where THIS insider was the winner). - `data[].transaction_date` (string (nullable)): ISO `YYYY-MM-DD` trade execution date. - `data[].transaction_code` (string (nullable)): Raw SEC Form 4 transaction code. - `data[].transaction_description` (string (nullable)): Human-readable code description. - `data[].acquired_disposed_code` (string (nullable)): `A` (Acquired) or `D` (Disposed). - `data[].shares` (number): Share count (split-adjusted). - `data[].price_per_share` (number (nullable)): Per-share USD price, rounded to 2 decimals. - `data[].transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD. - `data[].shares_owned_following` (number (nullable)): Per-vehicle holdings after this transaction. - `data[].value_owned_following` (number (nullable)): Computed `shares_owned_following × price_per_share` in USD. - `data[].ownership_nature` (string (nullable)): `D` or `I`. - `data[].is_derivative` (boolean (nullable)): `true` for Form 4 Table II rows. - `data[].is_rule_10b5_1` (boolean): `true` for 10b5-1 plan executions. - `data[].is_cashless_exercise` (boolean): `true` for option-exercise-and-immediate-sale patterns. - `data[].insider_name` (string (nullable)): The reporting person's name (matches the `cik` path parameter for non-joint filings; may be a co-filer for joint filings on the dedup branch). - `data[].insider_cik` (string (nullable)): The reporting person's CIK (10-character zero-padded). - `data[].is_entity` (boolean (nullable)): `true` for entity reporters. - `data[].is_director` (boolean): Director relationship to this issuer. - `data[].is_officer` (boolean): Officer relationship to this issuer. - `data[].is_ten_percent_owner` (boolean): 10%-owner relationship to this issuer. - `data[].insider_title` (string (nullable)): Officer title raw text from the filing. - `data[].officer_title_standardized` (string (nullable)): Officer title normalized to FinRadar's vocabulary. - `data[].is_c_suite` (boolean): C-suite indicator. - `data[].ticker` (string (nullable)): Issuer ticker for THIS row (varies across rows when the insider files at multiple companies). - `data[].company_name` (string (nullable)): Issuer name for THIS row. - `data[].sector` (string (nullable)): Sharadar sector classification for the issuer. - `data[].industry` (string (nullable)): Sharadar industry classification for the issuer. - `data[].issuer_cik` (string (nullable)): Issuer CIK. - `data[].security_type` (string (nullable)): Security title. - `data[].is_common_stock` (boolean (nullable)): `true` for cash-equity common-stock rows. - `data[].accession_number` (string (nullable)): Source filing accession number. - `data[].form_type` (string (nullable)): Form type. - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `data[].is_amendment` (boolean (nullable)): `true` for `*/A` amendments. - `data[].co_owners` (array (nullable)): Present ONLY when `dedup_owners=true`. - `data[].co_owner_count` (integer (nullable)): Length of `co_owners` (only when `dedup_owners=true`). - `meta` (object (nullable)): Result metadata block — pagination + insider profile. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total matching rows for the filter set. - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `meta.insider` (object): Insider profile block — surfaces identity + cross-issuer reach (`total_companies`) so UIs don't need a separate `/insider/{insider_cik}` call to render the page header. - `meta.insider.cik` (string): Insider CIK (10-character zero-padded). - `meta.insider.name` (string (nullable)): Insider legal name (`name_as_filed` from the most-recent Form 4). - `meta.insider.is_entity` (boolean (nullable)): `true` for entity reporters. - `meta.insider.total_companies` (integer): Distinct count of issuers this insider has a current relationship with (from `OwnerRelationship` rows where `is_current=true`). Use this as a `n+1`-style hint when sizing UI tables. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Complete transaction history for one insider across all companies. **Use case:** Researching an insider like Elon Musk (CIK 1494730) — see all trades across TSLA, SpaceX, etc., with total shares owned per company. **Parameters:** - `cik` (path, required): Insider CIK number - `limit` (query, optional, default: 50): Limit results - `from_date` (query, optional): Start date (YYYY-MM-DD) - `to_date` (query, optional): End date (YYYY-MM-DD) - `dedup_owners` (query, optional, default: false): Opt-in server-side joint-filer dedup. When true, the response only includes the canonical winner of each natural-key partition (deterministic by lowest transaction_id) and adds co_owners + co_owner_count. The insider only appears for a joint filing if they were the canonical winner. Default-path response shape unchanged. **Sample response:** ```json { "status": "success", "data": [ { "transaction_id": "9341128", "transaction_date": "2026-04-15", "transaction_code": "S", "transaction_description": "Open-market sale", "acquired_disposed_code": "D", "shares": 50000, "price_per_share": 175.25, "transaction_value": 8762500, "shares_owned_following": 3229012, "value_owned_following": 565884853, "ownership_nature": "D", "is_derivative": false, "is_rule_10b5_1": true, "is_cashless_exercise": false, "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_officer": true, "is_director": false, "is_ten_percent_owner": false, "insider_title": "Chief Executive Officer", "officer_title_standardized": "CEO", "is_c_suite": true, "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "security_type": "Common Stock", "is_common_stock": true, "accession_number": "0001127602-26-001234", "form_type": "4", "filed_at": "2026-04-15T20:14:32+00:00", "is_amendment": false } ], "meta": { "pagination": { "total": 18, "limit": 50, "offset": 0, "has_more": false }, "insider": { "cik": "0001214156", "name": "COOK TIMOTHY D", "is_entity": false, "total_companies": 1 } }, "request_id": "1f6a2b3c-9d4e-4a5f-b6c7-8d9e0a1b2c3d", "timestamp": "2026-05-02T15:36:42.117Z" } ``` ### GET /insider-module/api/insiders/transactions/search Search insider transactions with advanced filters. Each row includes total_beneficial_ownership and sector/industry classification from Sharadar. **Token cost:** 10 tokens per call **Response fields:** - `status` (string): Always `success` on a 2xx response. - `data` (array): Array of matching transaction rows, ordered by `transaction_date DESC` (most recent first), tie-broken by `transaction_id DESC`. Empty array when no rows match — never null. One row per `(transaction × reporting_owner)` pair by default; one row per economic transaction when `dedup_owners=true`. - `data[].transaction_id` (integer): Stable internal primary key from the `insiders_transactions` table. When `dedup_owners=true` this is the canonical winner of the joint-filer dedup partition (deterministic by lowest `transaction_id` across the joint group). Stable across re-runs and re-parses — safe to use as a deduplication key on the client side. - `data[].ticker` (string): Issuer ticker (the company whose insider is trading), normalized to canonical hyphen form (e.g. `BRK-A`, `GOOG-L`). For multi-class issuers, the class actually traded on the Form 4 is preserved — NOT collapsed to the primary share class. - `data[].insider_name` (string): Reporting-person legal name as filed on Form 4 (Item 1). May be an individual or an entity (LP, fund vehicle, trust). Casing is preserved verbatim from the filing — do NOT use this as a join key; use `insider_cik` instead. For canonical resolution across name variants, see `/insider-module/api/insider/search`. - `data[].insider_cik` (string): SEC-issued reporting-person CIK as a 10-character zero-padded string. Same insider may file at multiple companies — combine `insider_cik + ticker` for per-issuer position tracking. Use as the join key against `/api/v1/ownership/holders/{uuid}/filing-history` once you've resolved CIK → unified-holder UUID. - `data[].shares` (number): Share count for the transaction (split-adjusted to most recent split via Sharadar's split-adjustment factor). For derivative transactions (exercise/grant of options), this is the number of underlying shares — NOT the option contract count. Always positive; direction (acquired vs disposed) is encoded in `acquired_disposed_code`. - `data[].price_per_share` (number (nullable)): Per-share transaction price in USD (Form 4 Item 5 column 4). Null for code-A grants and code-G gifts where there is no consideration. Already split-adjusted to match the `shares` field. For derivative transactions, this is the strike or exercise price, not the spot price of the underlying. - `data[].transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD (rounded to nearest cent). Null when `price_per_share` is null (grants/gifts have no dollar value). Useful for `min_value` filtering and aggregate-flow analysis — combine with `dedup_owners=true` to avoid joint-filer double-counting. - `data[].transaction_date` (string): ISO `YYYY-MM-DD` date the trade was executed (Form 4 Item 3, NOT the filing acceptance date). For the date the filing was disclosed publicly, see the parent filing's `filed_date`. Trade dates can pre-date filing dates by up to 2 business days under the SEC's filing window. - `data[].total_beneficial_ownership` (number (nullable)): Aggregate shares owned by this insider across ALL ownership vehicles (direct + indirect trusts, LLCs, joint accounts) for this issuer, AS OF this transaction. Computed from the `shares_owned_following` field plus a roll-up across vehicles. Null when the underlying filing does not report ownership (rare). Use this as a conviction proxy: a $5M sale that's 60% of holdings ≠ a $5M sale that's 2% of holdings. - `data[].sector` (string (nullable)): Sharadar sector classification for the issuer (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when the ticker is unmapped in Sharadar (private CUSIPs, recently-listed issuers, foreign issuers without ADRs). - `data[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector` — e.g. `Software—Application`, `Biotechnology`, `Semiconductors`). Null when unmapped. Em-dash characters are preserved verbatim — be careful with URL encoding when round-tripping. - `data[].co_owners` (array (nullable)): Present only when `dedup_owners=true`. JSON array of joint-filer co-owners collapsed into this canonical row, each entry shape `{name, cik, is_officer, is_director, is_ten_percent_owner}`. Use to surface 'this trade was filed jointly by 3 entities' in UIs, or to enumerate the legal participants for compliance audit. - `data[].co_owner_count` (integer (nullable)): Length of `co_owners` array. Present only when `dedup_owners=true`. A value of `1` means there were no joint filers (single owner). Values ≥2 mean a joint filing — `2` is the most common (LP+GP), but PE filings with `count: 9+` exist (e.g. LGN Form 4 with $514M × 9 owners). - `meta` (object): Result metadata block: pagination state plus a verbatim echo of the applied filters. Use it to drive UI page counters AND to confirm server-side parameter coercion (e.g. ticker normalization to canonical hyphen form is reflected in `meta.applied_filters.ticker` if returned). - `meta.total` (integer): Total matching rows for the full filter set, computed via a parallel `COUNT(*)` query (NOT just the size of the returned page). Use for UI page counters; for cursor-only iteration the per-page array length is sufficient. - `meta.limit` (integer): Effective page size after server-side capping. Mirrors the `limit` query parameter when it was within bounds, OR is set to the server-side cap (currently 1000) when the requested limit exceeded the cap. Always check this rather than echoing the requested limit. **Since:** v1.5.0 **Utility:** The screening workhorse for insider activity: filter every Form 4 transaction in our database by ticker, insider name, transaction type (purchase/sale/grant/exercise/gift), date range, minimum dollar value, C-suite-only, and Sharadar sector/industry. Built for fund analysts and quant researchers running thesis-driven screens like 'all CEO open-market purchases over $1M in Healthcare in the last 30 days' or 'all Form 4 sales over 100K shares from S&P 500 issuers this quarter'. Each row carries the insider's `total_beneficial_ownership` so you can immediately gauge conviction (a $5M sale that's 2% of holdings is a different signal than a $5M sale that's 60% of holdings). Pair the `dedup_owners=true` flag with `min_value` filtering to avoid the +112-223% aggregate-flow inflation that joint-filer rows introduce on PE LP+GP+manager and 13D-group filings. **Use case:** Finding all C-suite purchases over $1M in the last 30 days across all companies. **Parameters:** - `query` (query, required): REQUIRED free-text search (min 2 chars), matched case-insensitively in ONE field (`ILIKE '%query%'`) against ticker symbol, company name, AND insider name — e.g. `AAPL`, `Apple`, or `Buffett`. There is no separate `ticker`/`insider_name` param; this single field covers all three. - `filed_at_days` (query, optional, default: 7): Look back this many days by FILING date (when the Form 4 landed on EDGAR). Default 7, range 1–3650. - `transaction_days` (query, optional): Look back this many days by TRANSACTION (trade-execution) date. Range 1–365. Omit to bound only by filing date. - `transaction_code` (query, optional): Filter by raw SEC Form 4 transaction code (`P` purchase, `S` sale, `A` grant, `M` exercise, …); comma-separated for multiple. For the normalized 6-bucket version use `standard_type`. - `max_value` (query, optional): Maximum dollar value (`shares × price_per_share`). - `is_officer` (query, optional): When `true`, restrict to Section 16 officers. - `is_director` (query, optional): When `true`, restrict to directors. - `is_ten_percent_owner` (query, optional): When `true`, restrict to 10% beneficial owners. - `exclude_10b5_1` (query, optional, default: false): When `true`, exclude pre-planned Rule 10b5-1 trades (keep only discretionary activity). - `exclude_cashless` (query, optional, default: false): When `true`, exclude cashless option exercises. - `exclude_sell_to_cover` (query, optional, default: false): When `true`, exclude RSU sell-to-cover (tax-withholding) sales. - `standard_type` (query, optional): Normalized transaction type — accepts `purchase`, `sale`, `grant`, `exercise`, `gift`, `other`. This is FinRadar's mapping of the SEC's 10+ Form 4 transaction codes (P, S, A, M, G, F, etc.) into 6 buckets analysts actually filter on. Omit to include all types. - `min_value` (query, optional): Minimum dollar value (`shares × price_per_share`) — rows with null price (code A grants) are EXCLUDED when this is set. Use to focus on material trades; `1000000` removes most exercise-and-immediate-sale noise. Always combined with the `dedup_owners=true` flag for trading-flow analysis to avoid double-counting joint-filer rows. - `is_c_suite` (query, optional): When `true`, restricts to C-suite officers (CEO/CFO/COO/CIO/CTO/General Counsel) — heuristic match against the `officer_title` field. Setting `false` is treated the same as omitting (i.e. NOT a 'non-C-suite-only' filter; it's an opt-in narrowing). Useful for screening insider conviction signals where lower-rank insider trades are noisier. - `limit` (query, optional, default: 50): Maximum rows returned (default 50, capped at 1000 server-side). Combine with `filed_at_days`/`transaction_days` to widen the window; the endpoint does not currently support cursor pagination so for full backfills prefer date-range chunking over `offset` pagination. - `sector` (query, optional): Sharadar sector classification, case-sensitive (e.g. `Technology`, `Healthcare`, `Financial Services`, `Industrials`, `Consumer Cyclical`). Joins via `cusip → ticker → Sharadar SF1 sector`. Rows whose ticker has no Sharadar mapping are excluded when this filter is set. - `industry` (query, optional): Sharadar industry classification, case-sensitive (more specific than `sector` — e.g. `Software—Application`, `Biotechnology`, `Semiconductors`). Use the `/financials/tickers` endpoint to enumerate exact valid values, since some Sharadar industry strings contain em-dashes that must be URL-encoded. - `dedup_owners` (query, optional, default: false): Opt-in server-side joint-filer dedup (introduced v3.17.0). When `true`, collapses joint-filer rows (PE LP+GP+manager, 13D groups, SPAC sponsors) into one canonical row per economic transaction and exposes `co_owners` (JSON array) + `co_owner_count` (int). Eliminates the +112-223% aggregate-flow inflation observed across joint Form 4 filings. When `false` or omitted, response is byte-identical to pre-3.17.0 (no new keys appear). **Sample response:** ```json { "status": "success", "data": [ { "transaction_id": 9341128, "ticker": "AAPL", "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "shares": 50000, "price_per_share": 175.25, "transaction_value": 8762500, "transaction_date": "2026-04-15", "total_beneficial_ownership": 3279012, "sector": "Technology", "industry": "Consumer Electronics" } ], "meta": { "total": 14, "limit": 100 } } ``` ### GET /insider-module/api/insiders/transactions/top Get largest transactions by value. Each row includes total_beneficial_ownership and sector/industry classification from Sharadar. **Token cost:** 10 tokens per call **Response fields:** - `status` (string): Always `success` on a 2xx response. - `data` (array): 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): 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): 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): 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): 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 (nullable)): 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): 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): 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 (nullable)): 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 (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar. - `data[].co_owners` (array (nullable)): 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): Result metadata block. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer (nullable)): Total matching rows for the filter set. Null when `include_total=false`. - `meta.pagination.limit` (integer): Effective page size after server-side capping. - `meta.pagination.offset` (integer): Echo of the requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available (derived from a limit+1 probe, exact regardless of `include_total`). - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response generation timestamp. **Since:** v1.5.0 **Utility:** 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. **Use case:** Spotting 'whale' activity to see where high-conviction money is moving. **Parameters:** - `direction` (query, optional, default: 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. - `limit` (query, optional, default: 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. - `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. - `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. - `dedup_owners` (query, optional, default: 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). - `include_total` (query, optional, default: 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. **Sample response:** ```json { "status": "success", "data": [ { "transaction_id": 9341128, "ticker": "LGN", "insider_name": "GENERATION INVESTMENT MANAGEMENT LP", "shares": 19400000, "price_per_share": 26.5, "transaction_value": 514100000, "transaction_date": "2026-04-22", "sector": "Industrials", "industry": "Specialty Chemicals" } ], "meta": { "pagination": { "total": 14, "limit": 50, "offset": 0, "has_more": false } } } ``` ### POST /insider-module/api/insiders/query SEC-API compatible filing query. Returns structured nested JSON — a top-level `{ total, transactions }` object where each `transactions[]` entry is a whole filing (issuer, reportingOwner, nonDerivativeTable, derivativeTable, footnotes). **Token cost:** 10 tokens per call **Response fields:** - `total` (object): sec-api.io-compatible pagination total: `{ value: integer, relation: 'eq' | 'gte' }`. `relation` is `'eq'` when `value < 10000` (exact count) and `'gte'` otherwise (lower bound). Use `value` for UI page counters; use `relation` to detect when you need to switch to date-range chunking for deeper backfills. - `transactions` (array): Array of matching filings — one entry per FILING (NOT one entry per transaction), despite the field name. Each entry carries the full sec-api.io-shaped nested tree (issuer, reportingOwner, nonDerivativeTable, derivativeTable, footnotes). Empty array when no filings match — never null. - `transactions[].id` (string): Deterministic document ID (MD5 hash of the accession number). Stable across re-runs. Matches sec-api.io's `id` field. - `transactions[].accessionNo` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Matches sec-api.io's `accessionNo` naming. Pass to `GET /insider-module/api/insiders/filings/{accession_number}` to retrieve the same filing in FinRadar's flatter row-oriented shape. - `transactions[].filedAt` (string (nullable)): ISO-8601 timestamp the filing was accepted by SEC EDGAR (with timezone offset). Distinct from `periodOfReport` (the trade date) — `filedAt` can be up to 2 business days after the trade under the SEC Section 16 filing window. - `transactions[].schemaVersion` (string (nullable)): Form 4 XML schema version (e.g. `X0306`). Defaults to `X0306` when not present on the filing. - `transactions[].documentType` (string): Form type as filed — typically `4` (statement of changes in beneficial ownership), `4/A` (amendment), `3` (initial statement), `5` (annual statement). Filtered server-side to insider-trading forms only — 13F/13D/13G filings never appear here. Matches sec-api.io's `documentType` naming (NOT `formType`). - `transactions[].periodOfReport` (string (nullable)): ISO `YYYY-MM-DD` Form 4 Item 3 period. Multi-trade filings preserve individual `transactionDate` values inside the nested transaction objects. - `transactions[].notSubjectToSection16` (boolean): `true` when the reporting person is not subject to Section 16. Defaults to `false`. - `transactions[].issuer` (object): Issuer block: `{ cik: string (leading zeros stripped), name: string, tradingSymbol: string }`. The company whose securities the insider transacted in. Matches sec-api.io's `issuer` shape. - `transactions[].reportingOwner` (object (nullable)): SINGLE reporting-owner object (NOT an array) — sec-api.io returns the first reporter for multi-owner filings. Shape: `{ cik, name, address: { street1, street2, city, state, zipCode }, relationship: { isDirector, isOfficer, officerTitle, isTenPercentOwner, isOther } }`. `null` when the filing has no reporter. - `transactions[].nonDerivativeTable` (object): Non-derivative table: `{ transactions: [...], holdings: [...] }`. Each transaction has nested `securityTitle`, `transactionDate`, `coding.{formType, code, equitySwapInvolved, footnoteId}`, `amounts.{shares, pricePerShare, acquiredDisposedCode}`, `postTransactionAmounts.{sharesOwnedFollowingTransaction, valueOwnedFollowingTransaction}`, and `ownershipNature.{directOrIndirectOwnership, natureOfOwnership}`. Arrays are empty (not null) when the filing has no non-derivative rows. - `transactions[].derivativeTable` (object): Derivative table: `{ transactions: [...], holdings: [...] }`. Same nested shape as the non-derivative transactions plus derivative-specific fields: `conversionOrExercisePrice`, `exerciseDate`, `expirationDate`, `underlyingSecurity.{title, shares}`. Arrays are empty (not null) when the filing has no derivative rows. - `transactions[].footnotes` (array): Filing footnotes — array of `{ id: string, text: string }`. Empty array when the filing has no footnotes. - `transactions[].remarks` (string (nullable)): Free-text remarks from the Form 4 (verbatim). - `transactions[].ownerSignatureName` (string (nullable)): Name of the person signing the filing. - `transactions[].ownerSignatureNameDate` (string (nullable)): ISO `YYYY-MM-DD` date the filing was signed. **Since:** v1.4.0 **Utility:** Drop-in migration target for customers moving off sec-api.io: accepts a Lucene-style query string (e.g. `ticker:TSLA AND formType:4 AND filedAt:[2026-01-01 TO 2026-04-01]`) and returns SEC-API-shaped nested JSON. The response is `{ total: { value, relation }, transactions: [...] }` where each entry is a filing — issuer block, single reportingOwner object, nonDerivativeTable / derivativeTable each with nested transactions + holdings (securityTitle / coding / amounts / postTransactionAmounts / ownershipNature). The shape is compatible with sec-api.io's `/insider-trading` query endpoint, so existing client code that parses sec-api.io responses Just Works. For lighter row-shaped queries that integrate better with SQL/relational tooling, prefer the flatter `/transactions/search` endpoint. **Use case:** Fetching structured Form 4 filings for programmatic analysis — each filing returns the reporting owner, non-derivative/derivative tables with nested amounts, ownership details, and footnotes. **Parameters:** - `query` (body, required): Lucene-style query string in sec-api.io syntax. Supported fields: `ticker`, `formType` (3, 4, 5, 4/A, etc.), `cik`, `accessionNo`, `filedAt` (ISO date or `[from TO to]` range), `issuer.name`, `reporters.name`. Boolean operators: `AND`, `OR`, `NOT`. Examples: `ticker:TSLA AND formType:4`, `formType:4 AND filedAt:[2026-01-01 TO 2026-04-01]`. Bare-word queries (e.g. `apple`) match against issuer.name + reporters.name. - `from` (body, optional, default: 0): Zero-based pagination offset (NOT a date — despite the name overlap with sec-api.io's date-range syntax). Increment by `size` to walk pages: `from=0` → page 1, `from=10` → page 2 (when `size=10`). Capped at 10000 server-side; for deeper backfill use date-range chunking via the `query` field. - `size` (body, optional, default: 50): Results per page (1–10000). Each row carries a heavy nested sec-api.io-shaped transaction tree, so keep page sizes modest for cost predictability. For bulk export workflows use `/api/insiders/bulk/form-4/{year}/{filename}` instead. **Sample response:** ```json { "total": { "value": 14, "relation": "eq" }, "transactions": [ { "id": "9f8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d", "accessionNo": "0001127602-26-001234", "filedAt": "2026-04-15T20:14:32+00:00", "schemaVersion": "X0306", "documentType": "4", "periodOfReport": "2026-04-15", "notSubjectToSection16": false, "issuer": { "cik": "320193", "name": "APPLE INC", "tradingSymbol": "AAPL" }, "reportingOwner": { "cik": "1214156", "name": "COOK TIMOTHY D", "address": { "street1": "ONE APPLE PARK WAY", "street2": null, "city": "CUPERTINO", "state": "CA", "zipCode": "95014" }, "relationship": { "isDirector": false, "isOfficer": true, "officerTitle": "Chief Executive Officer", "isTenPercentOwner": false, "isOther": false } }, "nonDerivativeTable": { "transactions": [ { "securityTitle": "Common Stock", "transactionDate": "2026-04-15", "deemedExecutionDate": null, "coding": { "formType": "4", "code": "S", "equitySwapInvolved": false, "footnoteId": [] }, "timeliness": null, "amounts": { "shares": 50000, "pricePerShare": 175.25, "acquiredDisposedCode": "D" }, "postTransactionAmounts": { "sharesOwnedFollowingTransaction": 3229012, "valueOwnedFollowingTransaction": null }, "ownershipNature": { "directOrIndirectOwnership": "D", "natureOfOwnership": null } } ], "holdings": [] }, "derivativeTable": { "transactions": [], "holdings": [] }, "footnotes": [], "remarks": null, "ownerSignatureName": "COOK TIMOTHY D", "ownerSignatureNameDate": "2026-04-16" } ] } ``` ### GET /insider-module/api/insiders/clusters Detect cluster buying/selling. Each cluster includes sector/industry classification from Sharadar. **Token cost:** 10 tokens per call **Response fields:** - `[]` (array): 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 (nullable)): Issuer ticker exhibiting cluster activity (canonical hyphen form). The natural primary key together with `cluster_type`. - `[].company_name` (string): Issuer name (from CompanyStub). - `[].sector` (string (nullable)): 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 (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar. - `[].issuer_cik` (string (nullable)): Issuer CIK for the clustered company. - `[].insider_count` (integer): 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): 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): 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): 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): 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): 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): 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): 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). **Since:** v1.5.0 **Utility:** 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. **Use case:** Identifying high-signal events where the CEO, CFO, and Directors all buy stock in the same week. **Parameters:** - `days` (query, optional, default: 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. - `min_insiders` (query, optional, default: 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. - `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. - `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. - `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`). **Sample response:** ```json [ { "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": [ "COOK TIMOTHY D", "MAESTRI LUCA", "ADAMS KATHERINE L", "O'BRIEN DEIRDRE" ], "cluster_type": "BUY" } ] ``` ### GET /insider-module/api/insiders/screen Screen for specific insider criteria. Supports sector/industry filtering from Sharadar classification. **Token cost:** 10 tokens per call **Response fields:** - `results` (array): Array of per-COMPANY aggregate rows (one entry per ticker with activity in the window) — NOT per-transaction rows. Sorted by `sort_by`. Empty array when no company matches the filters. - `results[].ticker` (string): Issuer ticker (canonical hyphen form). - `results[].company_name` (string): Issuer name. - `results[].issuer_cik` (string): Issuer CIK (10-character zero-padded). - `results[].sector` (string (nullable)): Sharadar sector classification for the issuer. Null when the ticker is unmapped. - `results[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped. - `results[].total_transactions` (integer): Total transactions matching filters. - `results[].total_buys` (integer): Total buy transactions matching filters. - `results[].total_sells` (integer): Total sell transactions matching filters. - `results[].total_buy_value` (number): Total buy value (USD) matching filters. - `results[].total_sell_value` (number): Total sell value (USD) matching filters. - `results[].net_value` (number): Net value (buy − sell, USD) matching filters. - `results[].total_buy_shares` (number): Total shares bought matching filters. - `results[].total_sell_shares` (number): Total shares sold matching filters. - `results[].net_shares` (number): Net shares (buy − sell) matching filters. - `results[].unique_insiders` (integer): Count of unique insiders matching filters. - `results[].unique_buyers` (integer): Count of unique buyers matching filters. - `results[].unique_sellers` (integer): Count of unique sellers matching filters. - `results[].rule_10b5_1_buy_count` (integer): ACTUAL 10b5-1 buy-plan count (transparency — NOT affected by `exclude_10b5_1`). - `results[].rule_10b5_1_sell_count` (integer): ACTUAL 10b5-1 sell-plan count (transparency). - `results[].rule_10b5_1_buy_value` (number): ACTUAL 10b5-1 buy value, USD (transparency). - `results[].rule_10b5_1_sell_value` (number): ACTUAL 10b5-1 sell value, USD (transparency). - `results[].csuite_buy_count` (integer): C-suite buy count matching filters. - `results[].csuite_sell_count` (integer): C-suite sell count matching filters. - `results[].csuite_buy_value` (number): C-suite buy value, USD, matching filters. - `results[].csuite_sell_value` (number): C-suite sell value, USD, matching filters. - `results[].csuite_net_value` (number): C-suite net value, USD, matching filters. - `results[].officer_buy_value` (number): Officer buy value, USD, matching filters. - `results[].officer_sell_value` (number): Officer sell value, USD, matching filters. - `results[].director_buy_value` (number): Director buy value, USD, matching filters. - `results[].director_sell_value` (number): Director sell value, USD, matching filters. - `results[].buy_sell_ratio` (number): Ratio of buys to sells. - `results[].sentiment_score` (number): Count-based sentiment in [-1, +1]. - `results[].value_sentiment_score` (number): Value-based sentiment in [-1, +1]. - `results[].csuite_sentiment_score` (number): C-suite count-based sentiment in [-1, +1]. - `results[].value_csuite_sentiment_score` (number): C-suite value-based sentiment in [-1, +1]. - `results[].filing_count` (integer): Distinct filings count for the company in the window. - `results[].latest_transaction_date` (string (nullable)): ISO `YYYY-MM-DD` of the company's latest transaction in the window. Null when empty. - `meta` (object): InsiderScreenMeta result-metadata block. - `meta.total_results` (integer): Total matching companies (pre-pagination). - `meta.returned` (integer): Number of company rows returned on this page. - `meta.limit` (integer): Echo of the effective limit. - `meta.offset` (integer): Echo of the requested offset. - `meta.has_more` (boolean): `true` when another page is available. - `meta.request_id` (string (nullable)): Per-request UUID for log correlation. - `meta.timestamp` (string): ISO-8601 UTC response timestamp. - `meta.filters_applied` (object): Verbatim echo of the applied filter set. **Since:** v1.5.0 **Utility:** Finviz-style insider screener — narrower and more deduplicated than `/transactions/search`. Pre-aggregates duplicate rows for the same insider on the same day (so a CEO that filed three back-to-back code-S sales on one date appears as one row), and is optimized for ≤500-row screening result sets that drive 'who's selling NVDA today?' tables on retail dashboards. Lacks the heavier filters of `/transactions/search` (no `min_value`, no `is_c_suite`, no `dedup_owners` flag) so use this when you want a fast clean ticker/sector/date-range screen, and use `/transactions/search` when you need the full filter matrix. **Use case:** Finding companies with net insider buying in the Technology sector within the last week, sorted by sentiment. **Parameters:** - `filed_at_days` (query, optional, default: 7): Look back this many days by FILING date (when the Form 4 landed on EDGAR). Range 1–3650. - `transaction_days` (query, optional): Look back this many days by TRANSACTION (trade-execution) date. Range 1–365. Omit to derive the transaction window from `filed_at_days` (with a 2-week filing-delay buffer). - `sentiment_gt` (query, optional): Keep only companies whose count-based `sentiment_score` is greater than this (range -1.0 to 1.0). E.g. `0.5` = strong net buying. - `sentiment_lt` (query, optional): Keep only companies whose count-based `sentiment_score` is less than this (range -1.0 to 1.0). E.g. `-0.5` = strong net selling. - `net_value_gt` (query, optional): Keep only companies whose `net_value` (buy USD − sell USD) is greater than this. - `net_value_lt` (query, optional): Keep only companies whose `net_value` is less than this. - `min_transactions` (query, optional, default: 1): Minimum number of transactions a company must have to appear in results. - `min_insiders` (query, optional, default: 1): Minimum number of distinct insiders a company must have to appear in results. - `csuite_only` (query, optional, default: false): When `true`, restrict the aggregation to C-suite (CEO/CFO/COO/CIO/CTO/General Counsel) activity. - `exclude_10b5_1` (query, optional, default: false): When `true`, exclude pre-planned Rule 10b5-1 trades from the filtered totals (the `rule_10b5_1_*` transparency fields are unaffected). - `exclude_cashless` (query, optional, default: false): When `true`, exclude cashless option exercises from the filtered totals. - `exclude_sell_to_cover` (query, optional, default: false): When `true`, exclude RSU sell-to-cover (tax-withholding) sales from the filtered totals. - `limit` (query, optional, default: 100): Maximum number of company rows to return (1–1000). - `offset` (query, optional, default: 0): Zero-based pagination offset. - `sort_by` (query, optional, default: abs_sentiment): Sort key. `abs_sentiment`/`abs_net_value` rank by magnitude regardless of direction (most-active first); `sentiment`/`net_value` rank signed (most-bullish first); `total_transactions` ranks by activity volume. - `sector` (query, optional): Sharadar sector classification, case-sensitive (e.g. `Technology`, `Healthcare`, `Financial Services`). Restricts the screen to one sector. Tickers without Sharadar mappings are excluded. - `industry` (query, optional): Sharadar industry classification, case-sensitive (more specific than `sector`). Em-dash characters require URL-encoding when round-tripping. Use the `/financials/tickers` endpoint to enumerate exact valid values. **Sample response:** ```json { "results": [ { "ticker": "NVDA", "company_name": "NVIDIA CORP", "issuer_cik": "0001045810", "sector": "Technology", "industry": "Semiconductors", "total_transactions": 24, "total_buys": 3, "total_sells": 21, "total_buy_value": 1240000, "total_sell_value": 142865500, "net_value": -141625500, "total_buy_shares": 9100, "total_sell_shares": 815700, "net_shares": -806600, "unique_insiders": 9, "unique_buyers": 2, "unique_sellers": 8, "rule_10b5_1_buy_count": 0, "rule_10b5_1_sell_count": 14, "rule_10b5_1_buy_value": 0, "rule_10b5_1_sell_value": 89412000, "csuite_buy_count": 0, "csuite_sell_count": 6, "csuite_buy_value": 0, "csuite_sell_value": 71840500, "csuite_net_value": -71840500, "officer_buy_value": 0, "officer_sell_value": 71840500, "director_buy_value": 1240000, "director_sell_value": 0, "buy_sell_ratio": 0.14, "sentiment_score": -0.75, "value_sentiment_score": -0.98, "csuite_sentiment_score": -1, "value_csuite_sentiment_score": -1, "filing_count": 18, "latest_transaction_date": "2026-04-12" } ], "meta": { "total_results": 87, "returned": 1, "limit": 100, "offset": 0, "has_more": false, "request_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "timestamp": "2026-05-02T15:36:42.117Z", "filters_applied": { "sector": "Technology", "exclude_10b5_1": false, "csuite_only": false, "min_transactions": 1, "min_insiders": 1 } } } ``` ### GET /insider-module/api/insiders/summary/by-ticker/{ticker} Get insider sentiment summary for a ticker. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (object): SummaryStatsSchema — single object with rolled-up insider sentiment metrics for the requested ticker over the lookback window. Returns HTTP 404 when the ticker cannot be resolved to an issuer CIK at all. - `data.ticker` (string): Echo of the requested ticker (canonical hyphen form post-normalization). - `data.company_name` (string): Issuer name. Falls back to `'Unknown'` for issuers missing a CompanyStub row. - `data.issuer_cik` (string): Issuer CIK (10-character zero-padded). - `data.days` (integer (nullable)): Echo of the (deprecated) `days` parameter; null when unset. - `data.total_transactions` (integer): Count of qualifying transactions in the window. Excludes 10b5-1 trades when `exclude_10b5_1=true`; excludes cashless-exercise sales when `exclude_cashless=true`. - `data.total_buys` (integer): Count of buy-side transactions (`acquired_disposed_code='A'`). - `data.total_sells` (integer): Count of sell-side transactions (`acquired_disposed_code='D'`). - `data.total_buy_value` (number): Sum of `shares × price_per_share` across all buy transactions, USD. Always non-negative. - `data.total_sell_value` (number): Sum of `shares × price_per_share` across all sell transactions, USD. Always non-negative. - `data.total_buy_shares` (number): Sum of share count across buys (split-adjusted). - `data.total_sell_shares` (number): Sum of share count across sells (split-adjusted). - `data.unique_insiders` (integer): Distinct count of reporting persons (post-canonical-owner dedup — multiple LLC/trust vehicles of the same beneficial owner count as one). - `data.latest_transaction_date` (string (nullable)): ISO `YYYY-MM-DD` of the most recent qualifying transaction. Null when the window is empty. - `data.net_shares` (number): `total_buy_shares - total_sell_shares` (signed). Positive = net buying, negative = net selling. - `data.net_value` (number): `total_buy_value - total_sell_value` (signed USD). The headline conviction-magnitude metric for sentiment dashboards. - `data.unique_buyers` (integer): Distinct count of insiders who bought in the window. Use the ratio `unique_buyers / unique_insiders` as a buy-breadth metric. - `data.unique_sellers` (integer): Distinct count of insiders who sold in the window. - `data.rule_10b5_1_buy_count` (integer): ACTUAL count of buy transactions executed under a 10b5-1 plan (TRANSPARENCY metric — NOT affected by the `exclude_10b5_1` filter, so consumers can compare with/without). - `data.rule_10b5_1_sell_count` (integer): ACTUAL count of sell transactions under a 10b5-1 plan (transparency). - `data.rule_10b5_1_buy_value` (number): ACTUAL USD buy value under 10b5-1 plans (transparency). - `data.rule_10b5_1_sell_value` (number): ACTUAL USD sell value under 10b5-1 plans (transparency). - `data.csuite_buy_count` (integer): Count of buys by C-suite insiders (CEO/CFO/COO/CIO/CTO/General Counsel). The conviction-density metric — high `csuite_buy_count` with positive `csuite_net_value` is the strongest insider-sentiment signal. - `data.csuite_sell_count` (integer): Count of sells by C-suite insiders. - `data.csuite_buy_value` (number): USD buy value by C-suite insiders. - `data.csuite_sell_value` (number): USD sell value by C-suite insiders. - `data.csuite_net_value` (number): `csuite_buy_value - csuite_sell_value` (signed USD). - `data.officer_buy_value` (number): USD buy value by all officers (broader than C-suite). - `data.officer_sell_value` (number): USD sell value by all officers. - `data.director_buy_value` (number): USD buy value by directors (board-only insiders). - `data.director_sell_value` (number): USD sell value by directors. - `data.buy_sell_ratio` (number): `total_buys / total_sells` (count-based). `Infinity` when there are no sells; `0` when there are no buys. Useful as a quick-glance sentiment chip. - `data.sentiment_score` (number): COUNT-based sentiment in [-1, +1]: `(total_buys - total_sells) / (total_buys + total_sells)`. +1 = all buys, -1 = all sells, 0 = balanced or empty window. - `data.value_sentiment_score` (number): VALUE-based sentiment in [-1, +1]: `(total_buy_value - total_sell_value) / (total_buy_value + total_sell_value)`. Weights large-dollar trades more heavily than the count-based score — preferred for dashboards. - `data.csuite_sentiment_score` (number): C-suite COUNT-based sentiment in [-1, +1]: `(csuite_buy_count - csuite_sell_count) / total`. Higher signal-to-noise than the all-insiders sentiment because routine 10%-owner unwinds and director RSU vesting are excluded. - `data.value_csuite_sentiment_score` (number): C-suite VALUE-based sentiment in [-1, +1]. Strongest single sentiment number for dashboards — combine with `csuite_buy_count >= 3` as a 'strong-conviction' threshold. - `data.filing_count` (integer): Distinct Form 4 filings (one filing can carry multiple transactions). Use the ratio `total_transactions / filing_count` to gauge whether activity comes from many filings or a few multi-line ones. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Quickly assess insider sentiment for a stock. **Use case:** Displaying a 'Bullish/Bearish' insider signal on a stock quote page. **Parameters:** - `ticker` (path, required): Stock Ticker - `filed_at_days` (query, optional, default: 7): Look back this many days by FILING date (when the Form 4 landed on EDGAR). Range 1–3650. This is the real lookback control. - `transaction_days` (query, optional): Look back this many days by TRANSACTION (trade-execution) date. Range 1–365. Omit to bound only by filing date. - `days` (query, optional): DEPRECATED — use `filed_at_days` and `transaction_days`. When set, it overrides both. Defaults to unset (null). - `is_c_suite` (query, optional): When `true`, restrict the summary to C-suite (CEO/CFO/COO/CIO/CTO/General Counsel) activity. - `exclude_10b5_1` (query, optional, default: false): When `true`, exclude pre-planned Rule 10b5-1 trades from the headline totals (the `rule_10b5_1_*` transparency fields are unaffected). - `exclude_cashless` (query, optional, default: false): When `true`, exclude cashless option exercises from the totals. **Sample response:** ```json { "status": "success", "data": { "ticker": "AAPL", "company_name": "APPLE INC", "issuer_cik": "0000320193", "days": null, "total_transactions": 47, "total_buys": 12, "total_sells": 35, "total_buy_value": 9854220, "total_sell_value": 142865500, "total_buy_shares": 58420, "total_sell_shares": 815700, "unique_insiders": 18, "latest_transaction_date": "2026-04-15", "net_shares": -757280, "net_value": -133011280, "unique_buyers": 4, "unique_sellers": 14, "rule_10b5_1_buy_count": 0, "rule_10b5_1_sell_count": 22, "rule_10b5_1_buy_value": 0, "rule_10b5_1_sell_value": 89412000, "csuite_buy_count": 1, "csuite_sell_count": 8, "csuite_buy_value": 2021040, "csuite_sell_value": 71840500, "csuite_net_value": -69819460, "officer_buy_value": 2021040, "officer_sell_value": 89125000, "director_buy_value": 7833180, "director_sell_value": 53740500, "buy_sell_ratio": 0.342857, "sentiment_score": -0.489362, "value_sentiment_score": -0.871022, "csuite_sentiment_score": -0.777778, "value_csuite_sentiment_score": -0.945272, "filing_count": 38 }, "request_id": "3a2f1b4c-9c6d-4f7e-8a5b-c1d2e3f4a5b6", "timestamp": "2026-05-02T15:38:09.412Z" } ``` ### GET /insider-module/api/insiders/insider/{insider_cik} Get detailed insider profile. Returns current_roles with per-company total_beneficial_ownership, ownership_summary with per-company vehicle breakdown (direct/indirect shares), and recent_transactions with total_beneficial_ownership per row. Transactions include sector/industry classification from Sharadar. **Token cost:** 5 tokens per call **Response fields:** - `cik` (string): Insider CIK (10-character zero-padded). Echo of the resolved path parameter. - `name` (string (nullable)): Insider legal name (`name_as_filed` from the most-recent Form 4). - `is_entity` (boolean): `true` for entity reporters (LP, fund vehicle, trust); `false` for individuals. - `current_roles` (array): Array of currently-active issuer relationships (one entry per `(insider, issuer)` pair where `OwnerRelationship.is_current=true`). Empty when the insider has no active relationships (e.g. retired). - `current_roles[].ticker` (string (nullable)): Issuer ticker for this role (canonical hyphen form). - `current_roles[].company` (string (nullable)): Issuer name. - `current_roles[].roles` (array): Array of role labels — `'Director'`, `'Officer ({raw_title})'`, `'10% Owner'`. May contain multiple entries when the insider holds multiple roles at the same issuer. - `current_roles[].total_beneficial_ownership` (number (nullable)): Aggregate shares this insider beneficially owns at this issuer (rolled up across all direct + indirect ownership vehicles). Null when the underlying filings do not report ownership. - `ownership_summary` (object (nullable)): Aggregate ownership totals + per-issuer vehicle breakdown. Most useful for rendering 'Total holdings: 3.2M shares (2.1M direct, 1.1M indirect)' chips on profile pages. - `ownership_summary.total_shares_direct` (number): Sum of share counts across all direct-ownership vehicles (own name). - `ownership_summary.total_shares_indirect` (number): Sum of share counts across all indirect-ownership vehicles (trust, LLC, family member). - `ownership_summary.total_beneficial` (number): `total_shares_direct + total_shares_indirect` — the all-vehicles aggregate. - `ownership_summary.companies` (object): Map keyed by `issuer_cik` → `{total_beneficial_ownership, vehicles[]}`. Each `vehicles[]` entry: `{ownership_nature, indirect_owner_name, shares}`. Empty object when the insider has no holdings. - `total_transactions_365d` (integer): Count of all transactions (across all issuers) in the trailing 365 days. - `total_buy_value_365d` (number): Sum of buy-side `shares × price` across all issuers in the trailing 365 days, USD. Defaults to `0` when no qualifying buys. - `total_sell_value_365d` (number): Sum of sell-side `shares × price` across all issuers in the trailing 365 days, USD. - `latest_transaction_date` (string (nullable)): ISO `YYYY-MM-DD` of the insider's most recent transaction across any issuer. Null when no qualifying transactions in the 365-day window. - `recent_transactions` (array): Up to 20 most-recent transactions (across all issuers), sorted by `transaction_date DESC`. The same transaction shape as `/transactions/by-insider/{cik}` plus a `total_beneficial_ownership` enrichment per row. - `recent_transactions[].transaction_id` (string (nullable)): Stable internal primary key. - `recent_transactions[].transaction_date` (string (nullable)): ISO `YYYY-MM-DD` trade execution date. - `recent_transactions[].transaction_code` (string (nullable)): Raw SEC Form 4 transaction code. - `recent_transactions[].acquired_disposed_code` (string (nullable)): `A` (Acquired) or `D` (Disposed). - `recent_transactions[].shares` (number): Share count (split-adjusted). - `recent_transactions[].price_per_share` (number (nullable)): Per-share USD price. - `recent_transactions[].transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD. - `recent_transactions[].shares_owned_following` (number (nullable)): Per-vehicle holdings after this transaction. - `recent_transactions[].total_beneficial_ownership` (number (nullable)): Aggregate shares owned by this insider at this issuer across ALL vehicles, AS OF this transaction. The conviction-magnitude proxy — a $5M sale that's 60% of `total_beneficial_ownership` is a different signal from a $5M sale that's 2%. - `recent_transactions[].is_rule_10b5_1` (boolean): `true` for 10b5-1 plan executions. - `recent_transactions[].is_cashless_exercise` (boolean): `true` for option-exercise-and-immediate-sale patterns. - `recent_transactions[].insider_name` (string (nullable)): The reporting person's name. - `recent_transactions[].insider_cik` (string (nullable)): The reporting person's CIK. - `recent_transactions[].is_entity` (boolean (nullable)): `true` for entity reporters. - `recent_transactions[].is_director` (boolean): Director relationship to the issuer for THIS transaction's row. - `recent_transactions[].is_officer` (boolean): Officer relationship for this row. - `recent_transactions[].is_ten_percent_owner` (boolean): 10%-owner relationship for this row. - `recent_transactions[].insider_title` (string (nullable)): Officer title raw text. - `recent_transactions[].officer_title_standardized` (string (nullable)): Officer title normalized. - `recent_transactions[].is_c_suite` (boolean): C-suite indicator. - `recent_transactions[].ticker` (string (nullable)): Issuer ticker for this row (varies across rows). - `recent_transactions[].company_name` (string (nullable)): Issuer name. - `recent_transactions[].sector` (string (nullable)): Sharadar sector classification. - `recent_transactions[].industry` (string (nullable)): Sharadar industry classification. - `recent_transactions[].issuer_cik` (string (nullable)): Issuer CIK. - `recent_transactions[].security_type` (string (nullable)): Security title. - `recent_transactions[].accession_number` (string (nullable)): Source filing accession number. - `recent_transactions[].form_type` (string (nullable)): Form type. - `recent_transactions[].filing_date` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. **Since:** v1.0.0 **Utility:** Complete insider profile with aggregated ownership data. **Use case:** Building an insider profile page showing Elon Musk's roles, total shares per company (direct + trust holdings), and recent trades. **Parameters:** - `insider_cik` (path, required): Insider CIK number **Sample response:** ```json { "cik": "0001214156", "name": "COOK TIMOTHY D", "is_entity": false, "current_roles": [ { "ticker": "AAPL", "company": "APPLE INC", "roles": [ "Officer (Chief Executive Officer)" ], "total_beneficial_ownership": 3279012 } ], "ownership_summary": { "total_shares_direct": 3229012, "total_shares_indirect": 50000, "total_beneficial": 3279012, "companies": { "0000320193": { "total_beneficial_ownership": 3279012, "vehicles": [ { "ownership_nature": "D", "indirect_owner_name": null, "shares": 3229012 }, { "ownership_nature": "I", "indirect_owner_name": "GRAT Trust 2024", "shares": 50000 } ] } } }, "total_transactions_365d": 18, "total_buy_value_365d": 0, "total_sell_value_365d": 142865500, "latest_transaction_date": "2026-04-15", "recent_transactions": [ { "transaction_id": "9341128", "transaction_date": "2026-04-15", "transaction_code": "S", "acquired_disposed_code": "D", "shares": 50000, "price_per_share": 175.25, "transaction_value": 8762500, "shares_owned_following": 3229012, "total_beneficial_ownership": 3279012, "is_rule_10b5_1": true, "is_cashless_exercise": false, "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_officer": true, "is_director": false, "is_ten_percent_owner": false, "insider_title": "Chief Executive Officer", "officer_title_standardized": "CEO", "is_c_suite": true, "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "security_type": "Common Stock", "accession_number": "0001127602-26-001234", "form_type": "4", "filing_date": "2026-04-15T20:14:32+00:00" } ] } ``` ### GET /insider-module/api/insiders/holdings/by-ticker/{ticker} Current insider holdings for a ticker. Each row includes total_beneficial_ownership aggregated across all ownership vehicles and sector/industry classification from Sharadar. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of unique-position holding rows for the requested issuer. One row per `(insider, security_title, ownership_nature, indirect_owner_name)` combination — the most-recent reported snapshot per vehicle. Combines Form 4 Table I (non-derivative) and Table II (derivative) when `include_derivative=true` (default). Empty array when the ticker has no insider holdings on file. Returns HTTP 404 when the ticker cannot be resolved at all. - `data[].holding_id` (string): Stable internal UUID for this holding row, serialized as a string. Safe to use as a deduplication key on the client. - `data[].security_title` (string): Title of the security (e.g. `Common Stock`, `Class A Common Stock`, `Stock Option`, `Restricted Stock Unit`). For derivatives the underlying is in `underlying_security_title`. - `data[].amount_owned` (number): Number of shares (or contract units, for derivatives) currently owned in this vehicle. Defaults to `0` for filings missing the value. Split-adjusted to match transaction rows. - `data[].ownership_nature` (string): `'direct'` (held in own name) or `'indirect'` (held via trust, LLC, family). Defaults to `'direct'` when the source filing's nature field is missing. - `data[].reported_date` (string (nullable)): ISO `YYYY-MM-DD` date of the source Form 3/4/5 filing that reported this position (the snapshot's as-of date). Subsequent transactions in newer filings supersede. - `data[].indirect_owner_name` (string (nullable)): When `ownership_nature='indirect'`, the name of the indirect-ownership vehicle (e.g. `'GRAT Trust 2024'`, `'Family Limited Partnership'`). Null for direct ownership. - `data[].is_derivative` (boolean): `true` for option/warrant/RSU positions (Form 4 Table II); `false` for cash-equity positions (Table I). - `data[].conversion_or_exercise_price` (number (nullable)): Exercise/conversion price in USD for derivatives (the strike). Null for non-derivative rows. - `data[].expiration_date` (string (nullable)): ISO `YYYY-MM-DD` expiration date for derivatives. Null for non-derivative rows or perpetual instruments. - `data[].underlying_security_title` (string (nullable)): For derivatives, the underlying security title (e.g. `'Common Stock'` for an option). Null for non-derivatives. - `data[].total_beneficial_ownership` (number (nullable)): Aggregate shares this insider beneficially owns at this issuer across ALL vehicles (direct + indirect; the cross-vehicle rollup). Null when the underlying filings do not report it. Distinct from `amount_owned` (per-vehicle) — use this for conviction-magnitude analysis. - `data[].sector` (string (nullable)): Sharadar sector classification for the issuer. Null when unmapped. - `data[].industry` (string (nullable)): Sharadar industry classification for the issuer. Null when unmapped. - `data[].insider_name` (string (nullable)): Reporting-person legal name (verbatim from the most-recent filing reporting this position). - `data[].insider_cik` (string (nullable)): Reporting-person CIK (10-character zero-padded). - `data[].is_entity` (boolean (nullable)): `true` for entity reporters (LP, fund vehicle, trust). - `data[].is_director` (boolean): Director relationship to the issuer (current). - `data[].is_officer` (boolean): Officer relationship to the issuer (current). - `data[].is_ten_percent_owner` (boolean): 10%-beneficial-owner relationship (current). - `data[].insider_title` (string (nullable)): Officer title raw text (e.g. `'Chief Financial Officer'`). - `data[].is_c_suite` (boolean): C-suite indicator. - `data[].accession_number` (string (nullable)): Source filing's SEC accession number. - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `data[].accepted_at` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp. - `data[].published_at` (string (nullable)): ISO-8601 UTC RSS-publication timestamp. - `data[].rss_updated_at` (string (nullable)): ISO-8601 UTC most-recent RSS update. - `meta` (object (nullable)): Result metadata block — pagination + company profile + holdings summary. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total combined holdings rows (non-derivative + derivative). - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `meta.company` (object): Company profile block (ticker, name, cik) — surfaces issuer identity so UIs don't need a separate company-info call. - `meta.company.ticker` (string): Issuer ticker (canonical hyphen form). Falls back to the upper-cased path parameter when the issuer has no CompanyStub row. - `meta.company.name` (string): Issuer name. Falls back to `'Unknown'` when missing. - `meta.company.cik` (string): Issuer CIK. - `meta.summary` (object): Holdings summary block computed across the CURRENT PAGE (not the entire filtered set) — direct/indirect totals + unique-insider count. Use as a quick UI chip; for full-set totals run `total_beneficial_ownership` aggregation client-side. - `meta.summary.total_insiders` (integer): Distinct count of insiders with positions in the current page. - `meta.summary.total_shares_direct` (number): Sum of `amount_owned` across non-derivative direct rows in the current page. - `meta.summary.total_shares_indirect` (number): Sum of `amount_owned` across non-derivative indirect rows in the current page. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** See who currently holds shares as an insider for a company. **Use case:** Viewing all insider positions in AAPL — direct holdings, trust holdings, and total beneficial ownership per insider. **Parameters:** - `ticker` (path, required): Stock Ticker - `limit` (query, optional, default: 50): Limit results **Sample response:** ```json { "status": "success", "data": [ { "holding_id": "8e3b5f2a-1c4d-4f9e-a7b8-c3d4e5f6a7b8", "security_title": "Common Stock", "amount_owned": 3229012, "ownership_nature": "direct", "reported_date": "2026-04-15", "indirect_owner_name": null, "is_derivative": false, "conversion_or_exercise_price": null, "expiration_date": null, "underlying_security_title": null, "total_beneficial_ownership": 3279012, "sector": "Technology", "industry": "Consumer Electronics", "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_director": false, "is_officer": true, "is_ten_percent_owner": false, "insider_title": "Chief Executive Officer", "is_c_suite": true, "accession_number": "0001127602-26-001234", "filed_at": "2026-04-15T20:14:32+00:00" }, { "holding_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "security_title": "Common Stock", "amount_owned": 50000, "ownership_nature": "indirect", "reported_date": "2026-04-15", "indirect_owner_name": "GRAT Trust 2024", "is_derivative": false, "total_beneficial_ownership": 3279012, "sector": "Technology", "industry": "Consumer Electronics", "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_director": false, "is_officer": true, "is_c_suite": true, "accession_number": "0001127602-26-001234", "filed_at": "2026-04-15T20:14:32+00:00" } ], "meta": { "pagination": { "total": 24, "limit": 50, "offset": 0, "has_more": false }, "company": { "ticker": "AAPL", "name": "APPLE INC", "cik": "0000320193" }, "summary": { "total_insiders": 18, "total_shares_direct": 12420518, "total_shares_indirect": 1842300 } }, "request_id": "5b7d3c1a-8f2e-4a6b-9d4e-c5b6a7d8e9f0", "timestamp": "2026-05-02T15:42:18.703Z" } ``` ### GET /insider-module/api/insiders/holdings/by-insider/{cik} Current holdings for a specific insider across all companies. Returns ownership_summary with per-company vehicle breakdown including total_beneficial_ownership. Includes sector/industry classification from Sharadar. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of insider holdings rows scoped to ONE reporting person (across all issuers, or a single issuer when `ticker` is set). Sorted by `reported_date DESC` (most recent snapshot first). Empty array when the insider has no holdings on file. Returns HTTP 404 when the CIK cannot be resolved at all. - `data[].holding_id` (string): Stable internal UUID, serialized as a string. - `data[].security_title` (string): Title of the security (e.g. `Common Stock`, `Stock Option`). - `data[].amount_owned` (number): Number of shares (or contract units, for derivatives) currently owned in this vehicle. - `data[].ownership_nature` (string): `'direct'` or `'indirect'`. Defaults to `'direct'` when source filing's nature field is missing. - `data[].reported_date` (string (nullable)): ISO `YYYY-MM-DD` date of the source filing reporting this position. - `data[].ticker` (string (nullable)): Issuer ticker (varies across rows when the insider holds positions at multiple issuers). - `data[].company_name` (string (nullable)): Issuer name. - `data[].sector` (string (nullable)): Sharadar sector classification for the issuer. - `data[].industry` (string (nullable)): Sharadar industry classification for the issuer. - `data[].issuer_cik` (string (nullable)): Issuer CIK. - `data[].is_derivative` (boolean): `true` for derivative positions; `false` for cash-equity. - `data[].total_beneficial_ownership` (number (nullable)): Aggregate shares this insider beneficially owns at THIS row's issuer across ALL vehicles. Null when the underlying filings do not report it. - `data[].accession_number` (string (nullable)): Source filing accession number. - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `data[].accepted_at` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp. - `data[].published_at` (string (nullable)): ISO-8601 UTC RSS-publication timestamp. - `data[].rss_updated_at` (string (nullable)): ISO-8601 UTC most-recent RSS update. - `meta` (object (nullable)): Result metadata block — pagination + insider profile + per-issuer ownership_summary. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total non-derivative holdings rows for the filter set (note: count is from the non-derivative query only — derivative inclusion is handled at row-emit time). - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `meta.insider` (object): Insider profile block. - `meta.insider.cik` (string): Insider CIK. - `meta.insider.name` (string (nullable)): Insider legal name. - `meta.insider.is_entity` (boolean (nullable)): `true` for entity reporters. - `meta.insider.total_companies` (integer): Distinct count of issuers this insider has holdings at (independent of pagination — full-set count). - `meta.ownership_summary` (object): Map keyed by `issuer_cik` → `{total_shares_direct, total_shares_indirect, total_beneficial, ownership_vehicles[]}`. The vehicle-level breakdown the UI uses to render 'AAPL: 3.2M direct + 50K via GRAT Trust 2024' tooltips. - `meta.ownership_summary.{cik}.total_shares_direct` (number): Sum of shares across direct-ownership vehicles for this issuer. - `meta.ownership_summary.{cik}.total_shares_indirect` (number): Sum of shares across indirect-ownership vehicles for this issuer. - `meta.ownership_summary.{cik}.total_beneficial` (number): Aggregate beneficial ownership rolled up across all vehicles. Defaults to `0` when missing. - `meta.ownership_summary.{cik}.ownership_vehicles` (array): Array of `{nature, name, shares, as_of}` per vehicle. `nature='direct'|'indirect'`; `name` is the indirect-vehicle label (null for direct); `shares` = current vehicle holdings; `as_of` = ISO date the vehicle was most-recently observed. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Complete holdings portfolio for one insider. **Use case:** Seeing all current stock positions for an insider across every company they're associated with, broken down by ownership vehicle. **Parameters:** - `cik` (path, required): Insider CIK number **Sample response:** ```json { "status": "success", "data": [ { "holding_id": "8e3b5f2a-1c4d-4f9e-a7b8-c3d4e5f6a7b8", "security_title": "Common Stock", "amount_owned": 3229012, "ownership_nature": "direct", "reported_date": "2026-04-15", "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "is_derivative": false, "total_beneficial_ownership": 3279012, "accession_number": "0001127602-26-001234", "filed_at": "2026-04-15T20:14:32+00:00" }, { "holding_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "security_title": "Common Stock", "amount_owned": 50000, "ownership_nature": "indirect", "reported_date": "2026-04-15", "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "is_derivative": false, "total_beneficial_ownership": 3279012, "accession_number": "0001127602-26-001234", "filed_at": "2026-04-15T20:14:32+00:00" } ], "meta": { "pagination": { "total": 2, "limit": 50, "offset": 0, "has_more": false }, "insider": { "cik": "0001214156", "name": "COOK TIMOTHY D", "is_entity": false, "total_companies": 1 }, "ownership_summary": { "0000320193": { "total_shares_direct": 3229012, "total_shares_indirect": 50000, "total_beneficial": 3279012, "ownership_vehicles": [ { "nature": "direct", "name": null, "shares": 3229012, "as_of": "2026-04-15" }, { "nature": "indirect", "name": "GRAT Trust 2024", "shares": 50000, "as_of": "2026-04-15" } ] } } }, "request_id": "ab3c5d7e-9f1a-4b2c-8d6e-7f9a0b1c2d3e", "timestamp": "2026-05-02T15:44:33.018Z" } ``` ### GET /insider-module/api/insiders/holdings/snapshot/{snapshot_date} Point-in-time holdings snapshot as of a specific date. Each row includes total_beneficial_ownership and sector/industry classification from Sharadar. **Token cost:** 0 (EXEMPT — auth / billing / account / admin / health) **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): 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): Stable internal UUID (serialized as a string). - `data[].security_title` (string): Title of the security. - `data[].amount_owned` (number): Number of shares (or contract units) held in this vehicle as of `snapshot_date`. - `data[].ownership_nature` (string): `'direct'` or `'indirect'`. - `data[].reported_date` (string (nullable)): ISO `YYYY-MM-DD` date of the source filing reporting this position. Always ≤ `snapshot_date`. - `data[].indirect_owner_name` (string (nullable)): Indirect-vehicle name when `ownership_nature='indirect'`. - `data[].is_derivative` (boolean): `true` for derivative positions; `false` for cash-equity. - `data[].total_beneficial_ownership` (number (nullable)): 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 (nullable)): Sharadar sector classification. - `data[].industry` (string (nullable)): Sharadar industry classification. - `data[].insider_name` (string (nullable)): Reporting-person legal name. - `data[].insider_cik` (string (nullable)): Reporting-person CIK. - `data[].is_entity` (boolean (nullable)): `true` for entity reporters. - `data[].is_director` (boolean): Director relationship. - `data[].is_officer` (boolean): Officer relationship. - `data[].is_ten_percent_owner` (boolean): 10%-owner relationship. - `data[].insider_title` (string (nullable)): Officer title raw text. - `data[].is_c_suite` (boolean): C-suite indicator. - `data[].ticker` (string (nullable)): Issuer ticker. - `data[].company_name` (string (nullable)): Issuer name. - `data[].issuer_cik` (string (nullable)): Issuer CIK. - `data[].accession_number` (string (nullable)): Source filing accession number. - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `meta` (object (nullable)): Result metadata. - `meta.snapshot_date` (string): 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 (nullable)): Pagination sub-block: `{ total, limit, offset, has_more }`. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** View insider holdings as of a specific date. **Use case:** Reconstructing insider ownership on a specific date for regulatory or research purposes. **Parameters:** - `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. - `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. - `insider_cik` (query, optional): Filter to a single insider (10-character zero-padded; shorter forms auto-padded). - `limit` (query, optional, default: 100): Maximum rows returned per page (1–1000). - `offset` (query, optional, default: 0): Zero-based pagination offset. **Sample response:** ```json { "status": "success", "data": [ { "holding_id": "8e3b5f2a-1c4d-4f9e-a7b8-c3d4e5f6a7b8", "security_title": "Common Stock", "amount_owned": 3279012, "ownership_nature": "direct", "reported_date": "2026-03-31", "indirect_owner_name": null, "is_derivative": false, "total_beneficial_ownership": 3279012, "sector": "Technology", "industry": "Consumer Electronics", "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "is_entity": false, "is_officer": true, "is_director": false, "is_ten_percent_owner": false, "insider_title": "Chief Executive Officer", "is_c_suite": true, "ticker": "AAPL", "company_name": "APPLE INC", "issuer_cik": "0000320193", "accession_number": "0001127602-26-001134", "filed_at": "2026-03-31T20:14:32+00:00" } ], "meta": { "snapshot_date": "2026-04-01" }, "request_id": "c6e8b9a0-1d2e-4f3a-9b8a-2c4d5e6f7a8b", "timestamp": "2026-05-02T15:46:18.094Z" } ``` ### GET /insider-module/api/insiders/filings/latest Get latest insider filings across all companies. Returns filing summaries with issuer details including sector and industry. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of filing-summary rows ordered by `filed_at DESC`. One row per filing (NOT per transaction — a single filing can carry many transactions; query `/filings/{accession_number}` for the full tree). Excludes superseded amendments via the `is_superseded=false` server-side filter. - `data[].filing_id` (string): Internal FinRadar UUID for the filing, serialized as a string. Stable across re-parses; safe to use as a deduplication key. - `data[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/filings/{accession_number}` for the full nested filing tree. - `data[].form_type` (string): Form type as filed — `3` (initial Section 16 statement), `4` (statement of changes), `5` (annual statement), or amendment variants `3/A`/`4/A`/`5/A`. - `data[].filed_at` (string (nullable)): ISO-8601 UTC timestamp the filing was accepted by SEC EDGAR. Primary sort key (DESC). - `data[].accepted_at` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp. Typically equal to or seconds after `filed_at`. - `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period covered by the filing (Form 4 Item 3 — typically the largest constituent transaction date). - `data[].is_amendment` (boolean): `true` for `*/A` amendments. Defaults to `false`. - `data[].is_late` (boolean (nullable)): `true` when filed past the SEC Section-16 2-business-day deadline. Null when timeliness data is unavailable for the filing. - `data[].business_days_to_file` (integer (nullable)): Business days between the underlying transaction date and `filed_at`. Values >2 indicate late filings. - `data[].issuer` (object): Issuer block: `{cik, name, trading_symbol, sector, industry}`. Pre-joined to avoid N+1 calls when rendering a filings table. - `data[].issuer.cik` (string): Issuer CIK (10-character zero-padded). - `data[].issuer.name` (string (nullable)): Issuer name (CompanyStub.name; falls back to InsiderFiling.issuer_name when stub missing). - `data[].issuer.trading_symbol` (string (nullable)): Issuer ticker (canonical hyphen form). - `data[].issuer.sector` (string (nullable)): Sharadar sector classification. Null when unmapped. - `data[].issuer.industry` (string (nullable)): Sharadar industry classification. Null when unmapped. - `data[].owner_count` (integer): Total number of reporting persons on the filing. `1` for typical individual filings; ≥2 for joint filings (PE LP+GP+manager / 13D groups / SPAC sponsors). - `data[].non_derivative_transaction_count` (integer): Count of Form 4 Table I (non-derivative / cash-equity) transactions on the filing. - `data[].derivative_transaction_count` (integer): Count of Form 4 Table II (derivative — option/RSU/warrant) transactions on the filing. - `data[].non_derivative_holding_count` (integer): Count of Form 4 Table I holdings (positions held but not transacted) on the filing. - `data[].derivative_holding_count` (integer): Count of Form 4 Table II holdings on the filing. - `data[].footnote_count` (integer): Count of footnotes attached to the filing. Footnotes carry crucial qualifying context (10b5-1 plan dates, gift-recipient identities). - `data[].xml_url` (string (nullable)): Direct URL to the SEC EDGAR XML primary document. - `data[].index_url` (string (nullable)): Direct URL to the SEC EDGAR filing index page (HTML). - `meta` (object (nullable)): Result metadata block. - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total matching filings for the filter set. - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Browse recent Form 3/4/5 filings with sector/industry filtering. **Use case:** Monitoring insider filing activity in the Technology sector or filtering amendments. **Parameters:** - `limit` (query, optional, default: 50): Limit results (max 1000) - `offset` (query, optional, default: 0): Pagination offset - `form_type` (query, optional): Filter by form type (3, 4, 5, 3/A, 4/A, 5/A) - `ticker` (query, optional): Filter by company ticker - `from_date` (query, optional): Start date (YYYY-MM-DD) - `to_date` (query, optional): End date (YYYY-MM-DD) - `is_amendment` (query, optional): Filter amendments only (true/false) - `sector` (query, optional): Filter by sector (e.g., Technology, Healthcare). Case-sensitive, Sharadar classification. - `industry` (query, optional): Filter by industry (e.g., Software, Biotechnology). Case-sensitive, Sharadar classification. **Sample response:** ```json { "status": "success", "data": [ { "filing_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "accession_number": "0001127602-26-001234", "form_type": "4", "filed_at": "2026-04-15T20:14:32+00:00", "accepted_at": "2026-04-15T20:14:35+00:00", "period_of_report": "2026-04-15", "is_amendment": false, "is_late": false, "business_days_to_file": 0, "issuer": { "cik": "0000320193", "name": "APPLE INC", "trading_symbol": "AAPL", "sector": "Technology", "industry": "Consumer Electronics" }, "owner_count": 1, "non_derivative_transaction_count": 1, "derivative_transaction_count": 0, "non_derivative_holding_count": 0, "derivative_holding_count": 0, "footnote_count": 1, "xml_url": "https://www.sec.gov/Archives/edgar/data/320193/000112760226001234/wf-form4_178834567890.xml", "index_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=4" } ], "meta": { "pagination": { "total": 4218, "limit": 50, "offset": 0, "has_more": true } }, "request_id": "d6e8f9a0-1b2c-4d3e-5f6a-7b8c9d0e1f2a", "timestamp": "2026-05-02T15:48:11.521Z" } ``` ### GET /insider-module/api/insiders/aggregation/by-sector Aggregate insider activity by sector or industry. Returns metrics per group: transaction count, filing count, unique insiders (counted as distinct canonical owners — one per economic transaction, not raw distinct ReportingOwner names; matches /clusters.insider_count semantics), unique issuers, buy/sell counts, buy/sell values, net value, buy/sell shares, and net shares. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of one row per `(group_by)` partition meeting the filter set. Sorted by `sort_by` parameter (default `abs_net_value DESC` — largest absolute net flow first, regardless of direction). When `sector` or `industry` filter is set, the array contains a single row. - `data[].group` (string (nullable)): Sector name (when `group_by=sector`) or industry name (when `group_by=industry`). Null for tickers without a Sharadar classification — these accumulate into a single 'unclassified' bucket so the ratios remain consistent. - `data[].transaction_count` (integer): Total qualifying transactions in the group (post-filter). Excludes 10b5-1 trades when `exclude_10b5_1=true`; excludes cashless-exercise sales when `exclude_cashless=true`. - `data[].filing_count` (integer): Distinct Form 4 filings represented in the group (one filing can have many transactions; this is the unique-filing count). - `data[].unique_insiders` (integer): Distinct count of reporting persons in the group (post-canonical-owner dedup — multiple LLC/trust vehicles of the same beneficial owner count as one). Use as a breadth metric — high `unique_insiders / unique_issuers` ratio = signal spread across many insiders rather than concentrated in a few. - `data[].unique_issuers` (integer): Distinct count of issuer companies in the group. Combined with `unique_insiders` and `transaction_count`, gives a 3-way density view of the group's activity. - `data[].buy_count` (integer): Count of acquisition transactions (`acquired_disposed_code='A'`). - `data[].sell_count` (integer): Count of disposition transactions (`acquired_disposed_code='D'`). - `data[].buy_value` (number): Sum of `shares × price_per_share` across all buy-side transactions in the group, USD. Always non-negative. - `data[].sell_value` (number): Sum of `shares × price_per_share` across all sell-side transactions in the group, USD. Always non-negative. - `data[].net_value` (number): `buy_value - sell_value` (signed USD). The headline magnitude metric — positive = net buying, negative = net selling. Sort by `abs_net_value` to get the most-active groups regardless of direction. - `data[].buy_shares` (number): Sum of shares acquired (split-adjusted). Always non-negative. - `data[].sell_shares` (number): Sum of shares disposed. Always non-negative. - `data[].net_shares` (number): `buy_shares - sell_shares` (signed). - `meta` (object (nullable)): Result metadata block — pagination + applied filters echo. - `meta.total` (integer): Total distinct groups matching the filter set (full count, not just the returned page). - `meta.limit` (integer): Effective page size (capped at 500 server-side). - `meta.offset` (integer): Echo of the requested offset. - `meta.has_more` (boolean): `true` when another page is available. - `meta.group_by` (string): Echo of the resolved `group_by` parameter (`'sector'` or `'industry'`). Source of truth for clients rendering 'Grouped by Sector'-style headings. - `meta.filed_at_days` (integer (nullable)): Echo of the resolved lookback window (defaults to 30 when unset). Useful for clients to render 'Last 30 days' annotations. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.5.0 **Utility:** Sector-level insider sentiment analysis and heatmap data. **Use case:** Building a sector heatmap showing where insider buying/selling is concentrated, or comparing insider activity across Technology vs Healthcare vs Energy sectors. **Parameters:** - `group_by` (query, optional, default: sector): Group by 'sector' or 'industry' - `sector` (query, optional): Filter to a specific sector - `industry` (query, optional): Filter to a specific industry - `filed_at_days` (query, optional, default: 30): Lookback window in days (1-3650) - `transaction_days` (query, optional): Filter by transaction date (days ago, 1-365) - `min_value` (query, optional): Minimum transaction value - `max_value` (query, optional): Maximum transaction value - `transaction_code` (query, optional): Filter by transaction code (P, S, M, etc.) - `acquired_disposed_code` (query, optional): Filter by A (Acquired) or D (Disposed) - `is_officer` (query, optional): Filter to officers only - `is_director` (query, optional): Filter to directors only - `is_ten_percent_owner` (query, optional): Filter to 10%+ owners only - `is_c_suite` (query, optional): Filter to C-suite executives only - `exclude_10b5_1` (query, optional, default: false): Exclude pre-planned 10b5-1 trades - `exclude_cashless` (query, optional, default: false): Exclude cashless exercise sales - `limit` (query, optional, default: 50): Max groups to return (max 500) - `offset` (query, optional, default: 0): Pagination offset - `sort_by` (query, optional, default: abs_net_value): Sort by: abs_net_value, net_value, total_value, transaction_count, or unique_insiders **Sample response:** ```json { "status": "success", "data": [ { "group": "Technology", "transaction_count": 142, "filing_count": 89, "unique_insiders": 67, "unique_issuers": 34, "buy_count": 45, "sell_count": 97, "buy_value": 12500000, "sell_value": 87300000, "net_value": -74800000, "buy_shares": 350000, "sell_shares": 1200000, "net_shares": -850000 } ], "meta": { "total": 11, "limit": 50, "offset": 0, "has_more": false, "group_by": "sector", "filed_at_days": 30 } } ``` ### GET /insider-module/api/insiders/recommendations/daily Algorithmic daily Buy/Sell recommendations based on insider cluster analysis. STRONG BUY: >2 unique insiders buying in last 7 days + >$100k total volume. STRONG SELL: >2 unique insiders selling in last 7 days + >$500k total volume. Deduplicated to prevent joint-filing inflation. **Token cost:** 10 tokens per call **Response fields:** - `buy` (array): Array of STRONG BUY signal rows (top 5 by aggregate value), sorted by `total_value DESC`. Empty array on quiet days when no ticker meets the deterministic buy threshold (>2 unique insiders buying in the last 7 days AND aggregate volume ≥ $100k). - `buy[].ticker` (string (nullable)): Issuer ticker firing the buy recommendation (canonical hyphen form). - `buy[].signal` (string): Recommendation literal — always `STRONG BUY` for entries in this array. - `buy[].insider_count` (integer): Distinct UNIQUE BENEFICIAL OWNERS (post-v3.1.1 dedup) buying during the 7-day window. Always ≥3 to qualify. - `buy[].total_value` (number): Aggregate USD buy value across all qualifying transactions in the 7-day window (`SUM(shares × price_per_share)`, post joint-filer dedup). Always ≥ $100k. - `buy[].price_avg` (number): Average per-share price across the qualifying buy transactions (USD). - `buy[].latest_date` (string (nullable)): ISO-8601 timestamp of the most recent qualifying filing in the cluster (the freshest signal data point). Null when unavailable. - `sell` (array): Array of STRONG SELL signal rows (top 5 by aggregate value), sorted by `total_value DESC`. Empty array when no ticker meets the deterministic sell threshold (>2 unique insiders selling in the last 7 days AND aggregate volume ≥ $500k). RSU sell-to-cover (tax-withholding) sales are excluded so they never form a false SELL signal. - `sell[].ticker` (string (nullable)): Issuer ticker firing the sell recommendation (canonical hyphen form). - `sell[].signal` (string): Recommendation literal — always `STRONG SELL` for entries in this array. - `sell[].insider_count` (integer): Distinct UNIQUE BENEFICIAL OWNERS selling during the 7-day window. Always ≥3 to qualify. - `sell[].total_value` (number): Aggregate USD sell value across all qualifying transactions in the 7-day window. Always ≥ $500k. - `sell[].price_avg` (number): Average per-share price across the qualifying sell transactions (USD). - `sell[].latest_date` (string (nullable)): ISO-8601 timestamp of the most recent qualifying filing in the cluster. Null when unavailable. - `meta` (object): Computation metadata block. - `meta.strategy` (string): Strategy label — `Cluster Analysis`. - `meta.period` (string): Lookback window label — `7 days`. - `meta.generated_at` (string): ISO-8601 UTC timestamp when this list was computed (per-request, not cached). **Since:** v3.14.0 **Utility:** The productized buy/sell signal — FinRadar's algorithmic distillation of cluster-detection logic into a small daily list of high-conviction tickers, refreshed at 09:30 UTC. Deterministic thresholds: STRONG BUY = >2 unique insiders buying in the last 7 days AND aggregate volume >$100k; STRONG SELL = >2 unique insiders selling in the last 7 days AND aggregate volume >$500k. Joint-filer rows are deduplicated upstream (post-v3.1.1 fix) so the signal does not fire on artificially inflated joint-filing volume. Use this endpoint when you want a small ready-to-act list; use `GET /insider-module/api/insiders/clusters` when you want the underlying clusters with full configurability (custom `min_insiders`, custom `min_value`, custom `days` window). **Use case:** Building a daily trading signal dashboard or automated alert system based on insider cluster activity. **Sample response:** ```json { "buy": [ { "ticker": "AAPL", "signal": "STRONG BUY", "insider_count": 4, "total_value": 1240000, "price_avg": 174.65, "latest_date": "2026-05-01T20:14:32+00:00" } ], "sell": [ { "ticker": "NVDA", "signal": "STRONG SELL", "insider_count": 5, "total_value": 26856000, "price_avg": 111.9, "latest_date": "2026-05-01T18:02:11+00:00" } ], "meta": { "strategy": "Cluster Analysis", "period": "7 days", "generated_at": "2026-05-01T09:30:00.000Z" } } ``` ### GET /insider-module/api/insiders/stats/global Global market insider activity statistics: total buy/sell volume ($), transaction counts, top active tickers by volume, and recent significant trades. All data is deduplicated across joint filings. **Token cost:** 1 token per call **Response fields:** - `period_days` (integer): Echo of the resolved `days` parameter (default `1` — 'today's activity'). Source of truth for clients rendering 'Last 7 days' annotations. - `volume` (object): Aggregate market-wide volume block. All counts and values are deduplicated across joint Form 4 filings (per-canonical-owner) so an LGN $514M × 9-owner sale shows up at $514M, not the inflated 9× sum. - `volume.buy_volume` (number): Sum of `shares × price_per_share` across ALL purchase transactions (`P` code) in the window, USD. Excludes filings with anomalous prices (≤0 or ≥$100k/share — the data-quality guard for splits and parsing errors). - `volume.sell_volume` (number): Sum of sell-side volume in the window, USD. Excludes anomalous prices. - `volume.buy_count` (integer): Count of qualifying purchase transactions (post-dedup). - `volume.sell_count` (integer): Count of qualifying sell transactions (post-dedup). - `top_tickers` (array): Top-5 tickers by total dollar volume (buys + sells combined) in the window. Sorted by `total_value DESC`. Empty array on quiet days/weekends. - `top_tickers[].ticker` (string (nullable)): Issuer ticker (canonical hyphen form). - `top_tickers[].total_value` (number): Sum of `shares × price` for this ticker in the window, USD. - `recent_large_tx` (array): Top-10 most-recent insider transactions over $500k, sorted by `filed_at DESC`. The 'ticker tape' for dashboards. Anomalous-price filter applied. - `recent_large_tx[].ticker` (string (nullable)): Issuer ticker. - `recent_large_tx[].date` (string (nullable)): ISO `YYYY-MM-DD` transaction execution date. - `recent_large_tx[].type` (string): `'Buy'` (when `acquired_disposed_code='A'`) or `'Sell'` (when `'D'`). Display-friendly direction. - `recent_large_tx[].value` (number): Transaction USD value (`shares × price_per_share`). Always >$500k for entries in this list. - `recent_large_tx[].insider` (string (nullable)): Reporting-person legal name (verbatim from Form 4 Item 1). - `daily_trend` (array): Daily buy/sell volume trend for the trailing 14 days (NOT the `days` window — fixed at 14 to drive line-chart visualizations). One entry per calendar date with non-zero activity. - `daily_trend[].date` (string): ISO `YYYY-MM-DD` date. - `daily_trend[].buy` (number): Buy-side USD volume on this date (post-dedup). - `daily_trend[].sell` (number): Sell-side USD volume on this date (post-dedup). - `top_insiders` (array): Top-5 most-active insider BUYERS in the window (purchases only — code `P`). Use as the 'who's buying?' panel on dashboards. - `top_insiders[].insider` (string (nullable)): Reporting-person name. - `top_insiders[].ticker` (string (nullable)): Issuer ticker (when an insider buys at multiple issuers, each `(insider, ticker)` pair is a distinct row). - `top_insiders[].total_value` (number): Total USD purchase value attributed to this `(insider, ticker)` pair. - `recent_clusters` (array): Top-5 cluster signals — tickers where >1 distinct beneficial owners executed BUYS in the window. Sorted by `total_value DESC`. Uses canonical-owner dedup (multiple LLC/trust vehicles of the same person count as one). - `recent_clusters[].ticker` (string (nullable)): Issuer ticker exhibiting cluster activity. - `recent_clusters[].insiders` (integer): Distinct unique beneficial owners buying in the cluster (always ≥2). - `recent_clusters[].value` (number): Aggregate USD value of cluster purchases. - `recent_clusters[].last_active` (string (nullable)): ISO-8601 UTC timestamp of the most-recent filing in the cluster. **Since:** v1.0.0 **Utility:** Dashboard-level insider market overview with buy/sell ratio. **Use case:** Building an insider activity dashboard showing overall market sentiment (buy vs sell volume), top active tickers, and notable recent trades. **Parameters:** - `days` (query, optional, default: 1): Lookback period in days (1-30) **Sample response:** ```json { "period_days": 1, "volume": { "buy_volume": 18420000, "sell_volume": 142865500, "buy_count": 142, "sell_count": 287 }, "top_tickers": [ { "ticker": "AAPL", "total_value": 89125000 }, { "ticker": "NVDA", "total_value": 42810000 }, { "ticker": "TSLA", "total_value": 28615000 }, { "ticker": "MSFT", "total_value": 18420000 }, { "ticker": "GOOG-L", "total_value": 12815000 } ], "recent_large_tx": [ { "ticker": "AAPL", "date": "2026-04-15", "type": "Sell", "value": 8762500, "insider": "COOK TIMOTHY D" }, { "ticker": "NVDA", "date": "2026-04-15", "type": "Buy", "value": 5240000, "insider": "DALLY WILLIAM J" } ], "daily_trend": [ { "date": "2026-04-15", "buy": 18420000, "sell": 142865500 }, { "date": "2026-04-14", "buy": 12815000, "sell": 98214000 } ], "top_insiders": [ { "insider": "ELLISON LAWRENCE J", "ticker": "ORCL", "total_value": 7842500 }, { "insider": "DALLY WILLIAM J", "ticker": "NVDA", "total_value": 5240000 } ], "recent_clusters": [ { "ticker": "PLTR", "insiders": 4, "value": 12420000, "last_active": "2026-04-15T18:42:11+00:00" }, { "ticker": "ENPH", "insiders": 3, "value": 8215000, "last_active": "2026-04-14T16:32:08+00:00" } ] } ``` ### GET /insider-module/api/insiders/filings/by-ticker/{ticker} Get all insider filings for a specific company. Returns filing summaries with issuer details, owner counts, transaction/holding counts, and SEC document URLs. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array of filing-summary rows for the requested issuer, ordered by `filed_at DESC`. Excludes superseded amendments. Returns HTTP 404 when the ticker cannot be resolved at all. - `data[].filing_id` (string): Internal FinRadar UUID for the filing. - `data[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. - `data[].form_type` (string): Form type (`3`/`4`/`5`/`3/A`/`4/A`/`5/A`). - `data[].filed_at` (string (nullable)): ISO-8601 UTC filing acceptance timestamp. - `data[].accepted_at` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp. - `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period covered by the filing (Form 4 Item 3). - `data[].is_amendment` (boolean): `true` for `*/A` amendments. - `data[].is_late` (boolean (nullable)): `true` when filed past the 2-business-day deadline. - `data[].business_days_to_file` (integer (nullable)): Business days between trade and filing. - `data[].issuer` (object): Issuer block — same value across all rows since this endpoint is ticker-scoped. - `data[].issuer.cik` (string): Issuer CIK. - `data[].issuer.name` (string (nullable)): Issuer name. - `data[].issuer.trading_symbol` (string (nullable)): Issuer ticker. - `data[].owner_count` (integer): Number of reporting persons on the filing. - `data[].non_derivative_transaction_count` (integer): Form 4 Table I transaction count. - `data[].derivative_transaction_count` (integer): Form 4 Table II transaction count. - `data[].non_derivative_holding_count` (integer): Form 4 Table I holdings count. - `data[].derivative_holding_count` (integer): Form 4 Table II holdings count. - `data[].footnote_count` (integer): Footnote count on the filing. - `data[].xml_url` (string (nullable)): SEC EDGAR XML document URL. - `data[].index_url` (string (nullable)): SEC EDGAR filing index URL. - `meta` (object (nullable)): Result metadata block — pagination + company profile (the same `meta.company` shape as `/holdings/by-ticker`). - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total matching filings for the issuer + filter set. - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `meta.company` (object): Company profile block (ticker / name / cik). - `meta.company.ticker` (string): Issuer ticker (canonical hyphen form). Falls back to upper-cased path parameter when CompanyStub missing. - `meta.company.name` (string): Issuer name. Falls back to `'Unknown'` when missing. - `meta.company.cik` (string): Issuer CIK. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Browse all Form 3/4/5 filings for a single company with filtering. **Use case:** Building a company insider filing history page, filtering to see only a specific insider's filings for a company, or finding amendments. **Parameters:** - `ticker` (path, required): Stock ticker (e.g. AAPL) - `limit` (query, optional, default: 50): Limit results (1-1000) - `offset` (query, optional, default: 0): Pagination offset - `form_type` (query, optional): Filter by form type (3, 4, 5, 3/A, 4/A, 5/A) - `from_date` (query, optional): Start date (YYYY-MM-DD) - `to_date` (query, optional): End date (YYYY-MM-DD) - `insider_cik` (query, optional): Filter by insider CIK (10-digit zero-padded) **Sample response:** ```json { "status": "success", "data": [ { "filing_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "accession_number": "0001127602-26-001234", "form_type": "4", "filed_at": "2026-04-15T20:14:32+00:00", "accepted_at": "2026-04-15T20:14:35+00:00", "period_of_report": "2026-04-15", "is_amendment": false, "is_late": false, "business_days_to_file": 0, "issuer": { "cik": "0000320193", "name": "APPLE INC", "trading_symbol": "AAPL" }, "owner_count": 1, "non_derivative_transaction_count": 1, "derivative_transaction_count": 0, "non_derivative_holding_count": 0, "derivative_holding_count": 0, "footnote_count": 1, "xml_url": "https://www.sec.gov/Archives/edgar/data/320193/000112760226001234/wf-form4_178834567890.xml", "index_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=4" } ], "meta": { "pagination": { "total": 287, "limit": 50, "offset": 0, "has_more": true }, "company": { "ticker": "AAPL", "name": "APPLE INC", "cik": "0000320193" } }, "request_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "timestamp": "2026-05-02T15:52:18.094Z" } ``` ### GET /insider-module/api/insiders/filings/{accession_number} Get complete filing details by accession number. Returns full nested structure matching SEC-API.io format: issuer info, all reporting owners with relationships and officer titles, non-derivative/derivative transactions and holdings, all footnotes, and owner signature. **Token cost:** 5 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (object): Full filing detail object matching the sec-api.io nested shape — issuer block + reporting owners + non-derivative/derivative tables (transactions + holdings) + footnotes + signature. Returns HTTP 404 when the accession number cannot be resolved. - `data.id` (string): Internal FinRadar UUID for the filing (string-serialized). - `data.accessionNo` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Path-parameter input is normalized server-side: `0000320193-25-000123` and `000032019325000123` both resolve to the same filing. - `data.documentType` (string): Form type (`3`/`4`/`5`/`*/A`). Aliased name preserves sec-api.io compatibility. - `data.filedAt` (string (nullable)): ISO-8601 UTC timestamp the filing was accepted by SEC EDGAR. - `data.acceptedAt` (string (nullable)): ISO-8601 UTC EDGAR acceptance timestamp (typically equal to or seconds after `filedAt`). - `data.periodOfReport` (string (nullable)): ISO `YYYY-MM-DD` period covered by the filing (Form 4 Item 3). - `data.dateOfOriginalSubmission` (string (nullable)): Reserved for future use — currently always null. The original-submission date for amendments is exposed via `originalAccessionNo` instead. - `data.schemaVersion` (string): SEC EDGAR XBRL schema version (e.g. `'X0306'`). Defaults to `'X0306'` when missing. - `data.notSubjectToSection16` (boolean): `true` when the filing was made by a non-Section-16 reporter (rare). Defaults to `false`. - `data.noSecuritiesOwned` (boolean): `true` for filings explicitly indicating no securities are owned (Form 3 starter filings sometimes). - `data.isAmendment` (boolean): `true` for `*/A` amendment filings. - `data.amendmentType` (string (nullable)): Amendment classification (`'restatement'`, `'addition'`, etc.) when discriminable from filing metadata; null for non-amendment filings. - `data.originalAccessionNo` (string (nullable)): For amendments, the accession number of the original filing being amended. Null for non-amendments. - `data.supersededByAccessionNo` (string (nullable)): When set, indicates this filing has been superseded by a later amendment with the given accession number. Use to traverse the amendment chain. - `data.isSuperseded` (boolean): `true` when a later amendment supersedes this filing (i.e. `supersededByAccessionNo` is set). Listing endpoints filter these out by default. - `data.isLate` (boolean (nullable)): `true` when the filing was submitted past the SEC Section-16 2-business-day deadline. - `data.businessDaysToFile` (integer (nullable)): Business days between transaction date and `filedAt`. - `data.indexUrl` (string (nullable)): Direct URL to the SEC EDGAR filing index page (HTML). - `data.xmlUrl` (string (nullable)): Direct URL to the SEC EDGAR XML primary document. - `data.issuer` (object): Issuer block: `{cik, name, tradingSymbol, tradingSymbolAtFiling}`. `tradingSymbolAtFiling` preserves the symbol as it was at filing time (in case of post-filing ticker changes). - `data.issuer.cik` (string): Issuer CIK (10-character zero-padded). - `data.issuer.name` (string (nullable)): Issuer name. Falls back to `InsiderFiling.issuer_name` when CompanyStub missing; further fallback to `'Unknown'`. - `data.issuer.tradingSymbol` (string (nullable)): CURRENT issuer ticker (canonical hyphen form). Use this for joins to today's market data. - `data.issuer.tradingSymbolAtFiling` (string (nullable)): Issuer ticker AS-OF the filing date — preserves what was current then. Diverges from `tradingSymbol` for issuers that changed ticker post-filing (rare; relevant for historical analysis). - `data.reportingOwners` (array): Array of all reporting persons on the filing — one entry per `FilingReporter`. Most filings have one reporter; joint filings (PE LP+GP+manager / 13D groups / SPAC sponsors) have 2-9+. Each entry includes identity + relationship + address (full sec-api.io-shaped nested object). - `data.nonDerivativeTable` (object): Form 4 Table I (cash-equity) sub-tree: `{transactions: [], holdings: []}`. Always present even when empty. - `data.nonDerivativeTable.transactions` (array): Cash-equity transactions on the filing — open-market buys/sells, grants, gifts. Each entry has nested `securityTitle`, `transactionDate`, `transactionCoding`, `transactionAmounts`, `postTransactionAmounts` (sec-api.io shape). - `data.nonDerivativeTable.holdings` (array): Cash-equity holdings on the filing (positions held but not transacted). Used by Form 3 starter filings and supplementary holdings disclosures. - `data.derivativeTable` (object): Form 4 Table II (derivative — option / RSU / warrant) sub-tree. - `data.derivativeTable.transactions` (array): Derivative transactions — option exercises, RSU vests, warrant grants. Each entry has the cash-equity transaction shape PLUS derivative-specific fields: `conversionOrExercisePrice`, `exerciseDate`, `expirationDate`, `underlyingSecurity`. - `data.derivativeTable.holdings` (array): Derivative holdings — outstanding option / RSU / warrant positions. - `data.footnotes` (array): Filing footnotes — array of `{id, text}` objects. Footnotes carry crucial qualifying context: 10b5-1 plan adoption dates, gift-recipient identities, transfer-on-death assignments, vesting schedules. Use the `id` to cross-reference `footnoteIds` arrays in transaction objects. - `data.remarks` (string (nullable)): Free-text remarks from the filing's 'Remarks' section. Often contains 10b5-1 plan adoption-date references that supplement the footnote graph. - `data.ownerSignatureName` (string (nullable)): Name of the person signing the filing (Form 4 Item 6). Often a power-of-attorney signer rather than the insider themselves. - `data.ownerSignatureDate` (string (nullable)): ISO `YYYY-MM-DD` date of the filing signature. Distinct from `filedAt` — signature is typically the same calendar day or 1 day before. - `data.processingMetadata` (object): FinRadar processing metadata: `{createdAt, updatedAt, processingState}`. Distinct from SEC-side timestamps (`filedAt`, `acceptedAt`) — these are for FinRadar pipeline observability. - `data.processingMetadata.createdAt` (string (nullable)): ISO-8601 UTC when FinRadar first ingested this filing. - `data.processingMetadata.updatedAt` (string (nullable)): ISO-8601 UTC of the most-recent FinRadar-side update (parser re-run, ticker remap). - `data.processingMetadata.processingState` (string): FinRadar processing state — `'COMPLETED'` (normal), `'PROCESSING'` (in-flight), `'FAILED'` (parse error). Defaults to `'COMPLETED'`. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** Full Form 3/4/5 filing detail with SEC-API.io compatible structure. **Use case:** Building a filing detail view that shows every transaction, holding, derivative position, and footnote for a specific SEC insider filing. **Parameters:** - `accession_number` (path, required): SEC accession number (e.g. 0001067983-24-000123 or 000106798324000123) **Sample response:** ```json { "status": "success", "data": { "id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "accessionNo": "0001127602-26-001234", "documentType": "4", "filedAt": "2026-04-15T20:14:32+00:00", "acceptedAt": "2026-04-15T20:14:35+00:00", "periodOfReport": "2026-04-15", "dateOfOriginalSubmission": null, "schemaVersion": "X0306", "notSubjectToSection16": false, "noSecuritiesOwned": false, "isAmendment": false, "amendmentType": null, "originalAccessionNo": null, "supersededByAccessionNo": null, "isSuperseded": false, "isLate": false, "businessDaysToFile": 0, "indexUrl": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=4", "xmlUrl": "https://www.sec.gov/Archives/edgar/data/320193/000112760226001234/wf-form4_178834567890.xml", "issuer": { "cik": "0000320193", "name": "APPLE INC", "tradingSymbol": "AAPL", "tradingSymbolAtFiling": "AAPL" }, "reportingOwners": [ { "name": "COOK TIMOTHY D", "cik": "0001214156", "relationship": { "isOfficer": true, "officerTitle": "Chief Executive Officer", "isDirector": false, "isTenPercentOwner": false, "isOther": false } } ], "nonDerivativeTable": { "transactions": [ { "securityTitle": { "value": "Common Stock" }, "transactionDate": { "value": "2026-04-15" }, "transactionCoding": { "transactionCode": "S", "equitySwapInvolved": false }, "transactionAmounts": { "transactionShares": { "value": 50000 }, "transactionPricePerShare": { "value": 175.25 }, "transactionAcquiredDisposedCode": { "value": "D" } }, "postTransactionAmounts": { "sharesOwnedFollowingTransaction": { "value": 3229012 } }, "ownershipNature": { "directOrIndirectOwnership": { "value": "D" } } } ], "holdings": [] }, "derivativeTable": { "transactions": [], "holdings": [] }, "footnotes": [ { "id": "F1", "text": "Sale executed under a Rule 10b5-1 trading plan adopted on 2025-08-15." } ], "remarks": null, "ownerSignatureName": "Sam Whittington", "ownerSignatureDate": "2026-04-15", "processingMetadata": { "createdAt": "2026-04-15T20:15:08+00:00", "updatedAt": "2026-04-15T20:15:08+00:00", "processingState": "COMPLETED" } }, "request_id": "f5e8a3b1-9c4d-4f7e-8a5b-c1d2e3f4a5b6", "timestamp": "2026-05-02T15:54:18.094Z" } ``` ### GET /insider-module/api/insiders/insider/search Search for insider individuals and entities by name or CIK. Returns matching insiders with their latest company affiliation and list of active tickers where they are current insiders. **Token cost:** 1 token per call **Response fields:** - `[].cik` (string): Insider CIK (10-character zero-padded). Pass directly to `/insider/{insider_cik}` for the full profile. - `[].name` (string (nullable)): Insider legal name (`name_as_filed` from the most-recent filing). Casing preserved verbatim. May be an individual or an entity. - `[].is_entity` (boolean): `true` for entity reporters (LP, fund vehicle, trust); `false` for individuals. Useful for splitting search results into 'People' vs 'Entities' tabs in autocomplete UIs. - `[].latest_company` (string (nullable)): Issuer name from the insider's MOST RECENT Form 3/4/5 filing (whichever issuer they last filed at). Null when the insider has no filings on record. Useful as the autocomplete-row subtitle (e.g. `'TIM COOK — Apple Inc.'`). - `[].active_tickers` (array): List of CURRENT issuer tickers where this insider has an active OwnerRelationship row (`is_current=true`). Empty array when the insider has no current relationships (e.g. retired). Useful for rendering ticker chips in autocomplete (e.g. an insider holding board seats at 3 companies shows 3 ticker chips). **Since:** v1.0.0 **Utility:** Insider person/entity search with autocomplete-friendly output. **Use case:** Building an insider search/autocomplete UI where typing 'Elon' finds Elon Musk with his active tickers (TSLA, XCOM, etc.), or searching by CIK for regulatory lookups. **Parameters:** - `query` (query, required): Search term (min 2 chars). Matches against insider name or CIK. - `limit` (query, optional, default: 50): Max results (1-100) **Sample response:** ```json [ { "cik": "0001214156", "name": "COOK TIMOTHY D", "is_entity": false, "latest_company": "APPLE INC", "active_tickers": [ "AAPL" ] }, { "cik": "0001494730", "name": "MUSK ELON", "is_entity": false, "latest_company": "TESLA, INC.", "active_tickers": [ "TSLA" ] } ] ``` ### GET /api/insiders/holdings/snapshot/{snapshot_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). **Token cost:** 10 tokens per call **Response fields:** - `status` (string): Always `success` on 2xx. - `data` (array): Array 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_id` (string): Internal UUID for the holding row, serialized as a string. - `data[].security_title` (string): Title of the security (e.g. `Common Stock`). - `data[].amount_owned` (number): Number of shares held in this vehicle as of `snapshot_date`. Defaults to `0` for filings missing the value. - `data[].ownership_nature` (string): `'direct'` or `'indirect'`. Defaults to `'direct'` when source filing's nature field is missing. - `data[].reported_date` (string (nullable)): ISO `YYYY-MM-DD` date of the source filing reporting this position. Always ≤ `snapshot_date`. - `data[].indirect_owner_name` (string (nullable)): Indirect-vehicle name when `ownership_nature='indirect'`. - `data[].ticker` (string (nullable)): Issuer ticker (canonical hyphen form). - `data[].company_name` (string (nullable)): Issuer name. - `data[].sector` (string (nullable)): Sharadar sector classification. - `data[].industry` (string (nullable)): Sharadar industry classification. - `data[].issuer_cik` (string (nullable)): Issuer CIK. - `data[].insider_name` (string (nullable)): Reporting-person legal name (verbatim from the source filing). - `data[].insider_cik` (string (nullable)): Reporting-person CIK. - `data[].total_beneficial_ownership` (number (nullable)): Aggregate shares this insider beneficially owned at this issuer across ALL vehicles AS OF the snapshot. Null when the underlying filings do not report it. - `meta` (object (nullable)): Result metadata block. - `meta.snapshot_date` (string): ISO `YYYY-MM-DD` echo of the path-parameter `snapshot_date` (verbatim — server doesn't re-format). - `meta.pagination` (object): Pagination sub-block. - `meta.pagination.total` (integer): Total matching holding rows for the filter set. - `meta.pagination.limit` (integer): Effective page size. - `meta.pagination.offset` (integer): Echo of requested offset. - `meta.pagination.has_more` (boolean): `true` when another page is available. - `request_id` (string (nullable)): Per-request UUID for log correlation. - `timestamp` (string): ISO-8601 UTC response timestamp. **Since:** v1.0.0 **Utility:** 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. **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. **Parameters:** - `snapshot_date` (path, required): 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. - `ticker` (query, optional): Filter to a single issuer (recommended for performance — full-market snapshots can return 100K+ rows). When unset, scans every issuer with holdings on file. - `insider_cik` (query, optional): 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'). - `limit` (query, optional, default: 100): Maximum rows returned per page (capped at 1000). - `offset` (query, optional, default: 0): Zero-based pagination offset. Walk pages with `offset += limit`. **Sample response:** ```json { "status": "success", "data": [ { "holding_id": "8e3b5f2a-1c4d-4f9e-a7b8-c3d4e5f6a7b8", "security_title": "Common Stock", "amount_owned": 3279012, "ownership_nature": "direct", "reported_date": "2026-03-31", "indirect_owner_name": null, "ticker": "AAPL", "company_name": "APPLE INC", "sector": "Technology", "industry": "Consumer Electronics", "issuer_cik": "0000320193", "insider_name": "COOK TIMOTHY D", "insider_cik": "0001214156", "total_beneficial_ownership": 3279012 } ], "meta": { "snapshot_date": "2026-04-01", "pagination": { "total": 1, "limit": 100, "offset": 0, "has_more": false } }, "request_id": "9d4e6f7a-8b1c-4d2e-3f5a-6b7c8d9e0f1a", "timestamp": "2026-05-02T15:58:32.105Z" } ``` ### POST /api/insiders/sync Trigger an on-demand insider data sync. Re-runs the Form 4 RSS poller and writes any newly-discovered transactions to the insiders tables. Idempotent — re-runs are no-ops if nothing new is in the EDGAR feed. **Token cost:** 25 tokens per call **Response fields:** - `job_id` (string): Celery task UUID assigned to the sync job. Surface this in support tickets when a sync appears to have hung — operations can grep this directly out of `flower` / Celery logs to trace the worker, queue, and per-step duration. - `queued_at` (string): ISO-8601 UTC timestamp at which the job entered the `sec_insiders` Celery queue (NOT the timestamp at which a worker started executing it). For end-to-end latency measurement, compare this against the `last_synced_at` value returned by subsequent reads. - `status` (string): Always the literal string `"queued"` on a successful enqueue. The sync itself is asynchronous — this endpoint never returns `"completed"`. To detect completion, poll `GET /insider-module/api/insiders/transactions/latest` and compare its `last_synced_at` against `queued_at`, or subscribe to the WebSocket push stream. - `estimated_seconds` (integer): Server-side ETA (in whole seconds) for the sync to complete, computed from current EDGAR feed depth and worker concurrency. Typical range 30-90s in steady state; 120-300s during 13F deadline windows when the insider worker shares CPU with form_13f workers. Treat as a hint, not a contract — schedule a re-poll at `queued_at + 1.5 × estimated_seconds`. **Since:** v1.0.0 **Utility:** Force a fresh poll of the SEC EDGAR Form 4 RSS feed instead of waiting for the next scheduled 60-second tick. Most useful for trading desks that want to confirm an insider transaction is in our system before acting on a Bloomberg or news-wire alert (lag-sensitive workflows where 30-60s of polling delay is material). The job is enqueued on the `sec_insiders` Celery queue and runs asynchronously — re-poll `GET /insider-module/api/insiders/transactions/latest` until you see the new accession number, or subscribe to the WebSocket stream at `/insider-module/socket.io` for push delivery. Idempotent and rate-limited (10 req/min per API key) so accidental retries are cheap. **Sample response:** ```json { "job_id": "8f1a2b30-c4d5-46e7-9f01-23456789abcd", "queued_at": "2026-05-01T20:55:12.000Z", "status": "queued", "estimated_seconds": 60 } ```