--- title: "Api Insiders" method: GET path: "/api/insiders" --- # Api Insiders `GET /api/insiders` ## Request - Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from) - URL: `https://www.oxfordledge.com/api/insiders` - Auth: none declared Insider trading data via live EDGAR Form 4 parsing. SOFT tier-gated in the handler body (lines below): paid users get the full transaction list; free / anonymous users get truncated to 3 transactions plus a `locked: true` upgrade nudge. The body-level truncation at line ~128 enforces the limit for anonymous curl too — so a hard `require_min_tier` decorator is NOT needed and would break the free-tier insider chip + first-3-rows preview that the ticker view depends on (P0 incident 2026-04-26 evening: hard gate at decorator caused tier-gate.js to short-circuit the call, rendering "Unable to load insider activity" for every anonymous visitor on every ticker). Response includes `float` so the frontend chip can compute its 1%-of-float net-buy threshold. NOTE: the value is shares_OUTSTANDING from the latest annual filing, NOT true free float (we don't carry a free-float figure). Outstanding >= free float, so the threshold is a slightly CONSERVATIVE proxy — the chip is marginally less likely to fire than a true-float denominator would make it (the safe direction: no false "INSIDERS BUYING"). The wire key stays `float` for frontend compat (Run 2 item 1; BOARD CYCLE 2026-05-22 P2 honesty). ## Query parameters - `ticker` string, nullable ## Response `200` Successful Response - InsidersResponse: `GET /api/insiders` response. Three required fields enforce the contract that bit us in the 2026-04-26 incident: ticker echo, `float` (shares_outstanding for chip threshold math; nullable when no annual filing on file), transactions list (may be empty), summary (always populated). The Python attribute is `float_shares` because the wire-format key `float` shadows the builtin `float` type, which breaks Pydantic v2's annotation resolution. The `alias="float"` keeps JSON key stable; `populate_by_name=True` (inherited from _Base) lets handler code construct the dict using either the alias or the attribute name. - `ticker` string, required - `float` integer, nullable: Shares outstanding from the latest annual filing. Frontend chip uses this for the 1%-of-float net-buy threshold. None when no annual filing is on file — chip renders FLAT with `Insider net-flow unavailable`. - `transactions` InsiderTransaction[], required - `insiderName` string, nullable - `position` string, nullable - `title` string, nullable - `transType` string, nullable - `shares` number, nullable - `pricePerShare` number, nullable - `totalValue` number, nullable - `filingDate` string, nullable - `sharesOwned` number, nullable - `url` string, nullable - `issuerSelfFiled` boolean, nullable: True when the reporting-owner CIK equals the issuer's CIK: filed under the company's own SEC ID, so the reporting-owner field names the company, not a person (footnotes may still name the officer). Shown, labelled, and never counted in any buy/sell summary, net figure or cluster. False when a CIK is missing. - `securityTitle` string, nullable: Form 4 security title as filed (Common Stock, Call option (obligation to sell), 4.250 pct Notes). NULL when the filing did not say. - `isCommonStock` boolean, nullable: CHAOS 2026-10-11 MF-2: True when the row is in `summary`'s common-stock population (pg_db/queries/insiders.py form4_row_is_common: not a derivative, no preferred / note / bond / debenture / warrant title). False rows are listed and labelled, never counted. - `isDerivative` boolean, nullable: True for a Form 4 Table II (derivative) row: option, warrant, right, convertible. Never in `summary`; its pricePerShare/totalValue are NULL when the filed price is not a plausible per-unit price (data/form4_value_plausibility.derivative_value_withheld). NULL when unclassified -- never read as False. - `summary` InsiderSummary, required - `net90dayValue` number: Buy minus sell values (P/S only, COMMON STOCK only since 2026-10-11 -- no derivative, preferred, note or warrant row; no ABS) over the trailing `windowDays` window, summed IN SQL over every in-window filing. 2026-09-08: was a Python sum over an unbounded newest-100 page, so a thinly-filed issuer's whole decade shipped as '90-day' activity. Name kept (renaming a live wire key strands cached clients); it is now true, and `windowDays` is the authority. - `buys` integer: Count of P (purchase) common-stock transactions in the `windowDays` window. - `sells` integer: Count of S (sale) common-stock transactions in the `windowDays` window. - `total` integer: Transactions in the returned FEED (newest-N, NOT date-bounded, post-truncation) -- it drives the anonymous 'N more transactions' nudge. The one field here that claims no window. - `buyShares` number: #45: common shares bought (P) over the whole `windowDays` window, never the truncated page. A magnitude (>= 0). - `sellShares` number: #45: common shares sold (S) over the whole `windowDays` window, never the truncated page. A magnitude (>= 0) since 2026-10-19; it was served NEGATIVE before (the store keeps a disposition as negative shares), so a client netting buyShares - sellShares added the sales. - `derivativeExcluded` integer: 2026-10-11 CRWV P1: in-window P/S Form 4 Table II rows (options, warrants, convertibles) left out of every figure here and counted. A call option's notional once summed to -$214B. - `otherSecuritiesExcluded` integer: In-window P/S non-derivative rows whose security title is preferred, a note, a bond, a debenture or a warrant: not common stock, left out of every figure here and counted. - `windowDays` integer: The trailing window in calendar days the server ENFORCED for every other field here. Echoed so a label reads the number the query used; a label carrying a number the query does not enforce is the 2026-09-08 defect. Never hard-code it client-side. - `dataSource` string, nullable - `latestFilingDate` string, nullable - `fetchedAt` string, nullable - `locked` boolean, nullable - `locked_total` integer, nullable - `upgrade` InsiderUpgrade - `tier` string, nullable - `tier_name` string, nullable - `price` string, nullable - `url` string, nullable - `message` string, nullable - `error` string, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)