# Finradar API Documentation (Full Reference)
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 2d596dd5
> Fetch this file at: https://uat.finradarapi.com/llms-full.txt

## Changelog
- 2026-06-19 (v3.61.0): **Fixes MCP tools that bricked every Anthropic MCP client.** Several endpoints documented query params with placeholder/alias shorthand in the literal `name` field — `/financials/screen` (`{metric}_gt`/`{metric}_lt`), `/form-13f/aggregation/by-ticker` (`min_{col} / max_{col}`), and pagination on `/form-13f/fund/{cik}` + `/fund/bulk` (`limit / size`, `from / offset`). These names flow verbatim into the generated OpenAPI spec and the MCP tool schemas, where the `{` `}` / space / `/` characters violate Anthropic's `input_schema.properties` key rule `^[a-zA-Z0-9_.-]{1,64}$` — so the Messages API returns HTTP 400 on the ENTIRE request and bricks any MCP session the moment such a tool enters the tools list (confirmed: `screen_stocks_by_financials` froze a client with repeated identical 400s and no recovery). Replaced all of them with the real identifiers the backend accepts: `/financials/screen` now lists its 38 concrete ratio filters (19 ratios x `_gt`/`_lt`); `/form-13f/aggregation/by-ticker` lists its concrete `min_*`/`max_*` range params; pagination uses canonical `limit`/`offset`/`size`/`from` with the accepted alias noted in the description. Also adds a build guard in `generate-openapi.js` that FAILS OpenAPI generation if any param/property name violates the Anthropic rule, so this class can never ship again. No backend change — docs/OpenAPI/MCP-schema accuracy only.
- 2026-06-16 (v3.60.0): **`GET /api/v1/sec/filings`: cold-start EDGAR backfill is now concurrency-bounded (#459 P0-9).** The endpoint still self-heals a cold ticker by backfilling its full EDGAR history on first touch, but only ONE backfill per CIK now runs at a time, capped globally (default 3 concurrent, `SEC_BACKFILL_MAX_CONCURRENT`). Concurrent duplicate requests for the same ticker — or requests beyond the global cap — no longer each launch a multi-second DB-write + EDGAR crawl (which could hammer the database and risk an EDGAR rate-limit); instead they return the current (possibly partial/RSS-only) results immediately with a new `meta.backfill_pending: true` flag — re-query shortly for the complete history. The first/winning request is unchanged (synchronous backfill, returns full results). No request-contract change; `meta.backfilled_from_edgar` is unchanged.
- 2026-06-16 (v3.59.0): **`GET /api/v1/sec/filings/{accession_number}/html`: optional size-bound paging (`offset`, `length`/`max_bytes`).** A raw 10-K can be tens of MB; pulling one whole into an LLM context window blows the token budget (and streams MBs back per call). You can now bound the response in UTF-8 bytes — `?max_bytes=200000` returns the first 200 KB, `?offset=200000&length=200000` the next 200 KB — and read the truncation state from response HEADERS (`X-Content-Total-Bytes`, `X-Content-Offset`, `X-Content-Returned-Bytes`, `X-Content-Truncated`). Fully backward-compatible: with no params the full document is returned exactly as before (the dashboard iframe is unaffected). Part of the MCP commercial-readiness security pass (#459). **Same pass — MCP surface hardening (no REST contract change):** the account/auth/payment/OAuth-lifecycle MUTATION tools (login/register/forgetpassword, payments, billing-portal, billing/quota, PUT /user, oauth/* + well-known) are removed from the agent-callable MCP tool surface (135→119 tools); `/oauth/revoke` now enforces RFC 7009 client-ownership; a per-credential request-rate + concurrency cap is enforced on the MCP proxy; and every MCP tool now carries read-only/open-world annotations plus its per-call token cost.
- 2026-06-16 (v3.58.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): two more megabank bleed fixes.** (1) 10-Q filers that print the "Financial Review" (Items 2/3/4) BEFORE the "Financial Statements" (Item 1) block — non-standard physical order — no longer run a narrative item through the entire statements block to Part II: the section is now bounded at the financial-statement cluster that physically follows it (e.g. Wells Fargo Item 4 Controls ~221,000→~2,400 characters; Bank of America Item 4 →~1,100; BNY Mellon combined Items 2 & 3 ~293,000→~54,000; Charles Schwab Item 3 ~119,000→a short cross-reference stub). (2) A 10-K Item 8 (Financial Statements) that is INCORPORATED BY REFERENCE — a brief note immediately followed by the Part IV "Financial Statement Schedules" list (e.g. Wells Fargo, JPMorgan) — now returns just that reference note instead of running through the exhibit list and signatures (~22,000→~280 characters). Verified with no change to filings that already worked (real financial statements, standard-order 10-Q, and 8-K extraction are unchanged). No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-16 (v3.57.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): megabank 10-K sections that over-extended past their true end are now bounded.** A complement to the descriptive-heading recovery in 3.55.0: where a bank renders sections under full canonical titles with no "Item N" prefix — sometimes in non-standard physical order (e.g. Citigroup prints Business → MD&A → Risk Factors) — a located section could run to end-of-document or into later sections because the next boundary carried no "Item N" label to stop at. The section end is now tightened to the next physical descriptive section heading, so these no longer bleed: e.g. Citigroup 10-K Item 1A (Risk Factors) dropped from ~1,000,000 characters (it had run through the financial statements to the glossary) to ~353,000, Item 1 (Business) from ~146,000 to ~15,000 (it had swallowed the MD&A), and Morgan Stanley Item 1A from ~669,000 to ~73,000. Monotonic and scoped: it only ever shortens an over-extended section — normal "Item N"-prefixed filers are byte-for-byte unchanged, and 10-Q / 8-K extraction is unaffected. No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-15 (v3.56.0): Insider API documentation reconciled with the backend across the insider endpoints (apiDocs↔handler drift audit). Fixes the broken `holdings_snapshot` MCP tool (documented `/holdings/snapshot` with phantom `ticker`/`as_of` params → corrected to the real `/holdings/snapshot/{snapshot_date}` route with required `snapshot_date`). Removed phantom query params (`start_date`/`end_date` on by-ticker/by-insider, `ticker`/`start_date`/`end_date` on /screen), corrected response wrapper keys (top/search `data[]`, screen `results[]`, query `transactions[]`, clusters bare array, recommendations `buy[]`+`sell[]`), removed the non-existent `standard_type` response field from search/top/screen, corrected fabricated response shapes (screen per-company aggregate, clusters `cluster_type`/`first_date`/`last_date`, query item shape, recommendations buy/sell, summary `today_date` removed), and fixed documented default values (`limit` 50 not 100; `size` 50). No backend change — docs/OpenAPI/MCP-schema accuracy only.
- 2026-06-15 (v3.55.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): recovers the megabank "descriptive heading" section class.** Citigroup, Morgan Stanley, Wells Fargo and similar filers render each 10-K / 10-Q section under its full canonical SEC title with **no "Item N" prefix** (e.g. `MANAGEMENT'S DISCUSSION AND ANALYSIS OF FINANCIAL CONDITION AND RESULTS OF OPERATIONS`, `CONSOLIDATED FINANCIAL STATEMENTS`), sometimes in non-standard physical order — so the extractor previously returned **empty** for those items. These are now matched by full title and bounded at the next physical section heading, recovering the MD&A, market-risk (Item 7A / 10-Q Item 3), financial-statements (Item 8 / 10-Q Item 1), controls, and exhibits sections that were missing — e.g. Morgan Stanley 10-K Item 7 (MD&A) and Item 8 (financial statements), previously empty, now extract in full. Verified across the affected banks with **no change to filings that already worked** (10-K / 10-Q / 8-K extraction is otherwise byte-for-byte unchanged). No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-15 (v3.54.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): three out-of-sample extraction fixes.** (1) 10-K body headings written with a hyphen separator — `Item 7 - Management's Discussion` (e.g. Lowe's) — are now matched (the separator class previously accepted only period / colon / en-dash / em-dash). (2) The **last** 10-Q item — Part II, Item 6 (Exhibits) — is now bounded at the trailing **SIGNATURES** block instead of running to end-of-document, so it no longer swallows the signature block (e.g. Bank of America's Item 6 dropped from ~389,000 characters to the correct exhibit index). (3) `Other Items` is accepted as a synonym for the Part II, Item 5 (Other Information) heading (e.g. AbbVie). No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-15 (v3.53.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): 10-Q MD&A (Part I, Item 2) that returned empty for a class of filings now extracts.** Filings that print page furniture — bare page numbers and per-page "Table of Contents" back-anchors — between the MD&A heading and its first paragraph (e.g. Boeing) previously exhausted the body-detection window before reaching the prose, so the section came back empty; that chrome is now skipped so the body is found (Boeing 10-Q MD&A: empty → ~48,000 characters). The same fix also recovered some Part II, Item 6 exhibit indexes with the same layout. Scoped to the 10-Q path — 10-K and 8-K extraction is unchanged. No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-15 (v3.52.0): `GET /api/insiders/transactions/search` documentation now matches the actual endpoint — fixing the `search_insider_transactions` MCP tool, which returned HTTP 422 on every call. The docs had declared four non-existent params (`ticker`, `insider_name`, `start_date`, `end_date`) and OMITTED the REQUIRED free-text `query` param (min 2 chars; matched case-insensitively against ticker / company name / insider name in a single field). Corrected to the real parameter set (`query`, `filed_at_days`, `transaction_days`, `transaction_code`, `standard_type`, `min_value`/`max_value`, `is_officer`/`is_director`/`is_ten_percent_owner`/`is_c_suite`, `exclude_10b5_1`/`exclude_cashless`/`exclude_sell_to_cover`, `sector`, `industry`, `dedup_owners`) and fixed the documented default `limit` (50, not 100). Docs / OpenAPI / MCP-schema accuracy fix — no backend change.
- 2026-06-15 (v3.51.0): The `standard_type` filter on the insider transaction endpoints — `GET /api/insiders/transactions/latest`, `/transactions/by-ticker/{ticker}`, and `/transactions/search` — is now actually applied. It was previously advertised in the docs / OpenAPI / MCP tool schema but silently ignored by the backend, so `standard_type=purchase` returned a mix of sales, grants and exercises instead of only open-market purchases. It now maps FinRadar's 6 normalized buckets to the raw SEC Form 4 transaction codes — `purchase`→P, `sale`→S, `grant`→A, `exercise`→M/X/C/O, `gift`→G, `other`→every remaining code (F tax-withholding, D, J, K, …) — verified end-to-end as a complete 6-bucket partition of all rows. The parameter is now a validated enum: an unrecognized value returns HTTP 422 instead of silently returning unfiltered results. Response shape is unchanged; the raw `transaction_code` / `acquired_disposed_code` filters are unaffected.
- 2026-06-15 (v3.50.0): **`GET /insider-module/api/insiders/transactions/latest` and `/transactions/top` gain an `include_total` query parameter (default `true`).** Set `include_total=false` to skip the exact `COUNT(*)` over the full matched set on these market-wide list endpoints: `meta.pagination.total` is then returned as `null` while `meta.pagination.has_more` stays exact (computed from a limit+1 fetch). On wide windows — e.g. `filed_at_days=3650` across all issuers or a whole sector/industry — the exact count is a multi-million-row scan that dominated response time; opting out returns the page in a fraction of the time. Backward-compatible and additive: the default is unchanged, so every existing caller still receives the exact `total`; only callers that pass `include_total=false` opt into the faster, count-free response (the response shape is identical apart from `total` being `null`). Entity-scoped endpoints (by-ticker / by-insider) are already selective and are intentionally not affected.
- 2026-06-15 (v3.49.0): **Section Extractor (`GET /api/v1/scrapping/extractor`): broader coverage of the 10-Q "Financial Statements" section.** A class of 10-Q filings whose Part I, Item 1 (Financial Statements) previously returned empty now extracts correctly — including compact two-column income statements, statements introduced by a caption row (e.g. a "Condensed Consolidated Statements of Income" title before the figures), body headings written as "Item 1. Condensed Consolidated Financial Statements", and headings that use a hyphen separator ("Item 1. - Financial Statements"). Verified across the affected issuers (e.g. Microsoft, NIKE, McKesson, Verizon) with no change to filings that already worked, and 10-K / 8-K extraction is unchanged. No request-contract change: identical parameters and identical `text` / `html` response shapes.
- 2026-06-14 (v3.48.0): **MCP Connect (OAuth 2.1) is live.** MCP clients (Cursor, Claude Desktop) can now connect to FinRadar's hosted MCP server with a one-click browser login instead of pasting an X-API-Key: the client runs the OAuth 2.1 authorization-code + PKCE flow against FinRadar's own login (with Dynamic Client Registration, RFC 7591), gets a short-lived RS256 access token, and calls tools on behalf of the signed-in user — tools debit that user's token balance exactly as API-key calls do. New users can create a free account during Connect (verify-first). Existing X-API-Key MCP clients are unaffected (dual auth). Discovery follows RFC 9728 (protected-resource) + RFC 8414 (authorization-server); the resource is `/api/mcp/`.
- 2026-06-14 (v3.47.0): **Section Extractor (`GET /api/v1/scrapping/extractor`) now returns the COMPLETE item section.** The previous 6,000-character output cap (a leftover from an internal card-rendering engine) has been removed, so 10-K / 10-Q / 8-K extractions return the full section instead of a truncated excerpt — e.g. a large 10-K Item 1A (Risk Factors) now returns its full ~70,000 characters rather than the first 6,000. End-of-section boundary detection was hardened across all three form types so multi-section filings cut at the correct next-item heading (no over- or under-extraction), and a worst-case performance issue on minified single-line megabank filings (e.g. a 9 MB bank 10-Q) was fixed. No request-contract change: identical parameters and identical `text` / `html` response shapes — responses are simply longer and more accurate.
- 2026-06-09 (v3.46.0): Hosted **MCP server** (Model Context Protocol) at `/api/mcp/` over streamable HTTP — exposes the public data REST operations as MCP tools for Claude and other MCP-compatible agents, generated at startup from `/openapi.json` so the tool surface tracks the API automatically. The surface is curated: operational/admin endpoints (admin, sql-proxy, sniper, bulk dumps) are excluded and the marquee data tools carry friendly names (e.g. `search_sec_filings`, `get_fund_13f_portfolio`, `latest_insider_transactions`). The MCP client passes its FinRadar API key as an `X-API-Key` header on the MCP transport; the server forwards it to the backend where the usual per-endpoint token cost, auth, and balance checks apply unchanged (the MCP server stores no key and adds no billing of its own). Routing mirrors the production split (insider vs main API) and calls the backends directly on the internal network. Stateless proxy — no new data and no contract change to any existing endpoint.
- 2026-06-09 (v3.45.0): Machine-readable integration surfaces for AI agents and codegen — both generated from `apiDocs.js` (the same single source of truth as `/llms.txt`), so they track every endpoint change automatically. **(1) OpenAPI 3.1 spec at `/openapi.json`** covering the full public REST surface (150 operations across 145 paths): per-operation `operationId`, parameters (path / query / header), request bodies, security schemes (`X-API-Key` header, `apiKey` query, Bearer JWT), a per-endpoint `x-token-cost`, and a response example per operation. WebSocket streams are documented under an `x-websockets` extension (they are Socket.IO, not HTTP, so they are not REST paths). Lints clean under the repo Spectral ruleset (0 errors). **(2) Agent Skill** — `SKILL.md` + bundled per-section reference + a zero-dependency Python helper, published under `/skill/finradar-api/` for Claude and other agent runtimes that support the Skill convention. No endpoint or response contract changed — these are additive discovery + integration artifacts.
- 2026-06-08 (v3.44.0): PR #426 — `GET /api/v1/scrapping/extractor` is now a dedicated sec-api.io Extractor replica scoped to **10-K / 10-Q / 8-K**, served by an isolated engine (`commercial_extractor.py`, zero shared code with the internal /business-description extractor). One in-house detection locates the section and renders it two ways: `type=text` (tags stripped, HTML entities kept literal, tables wrapped `##TABLE_START`/`##TABLE_END`) and `type=html` (style-PRESERVING — keeps inline font-weight/size/underline, drops color/background/positioning and all XSS via the nh3 allowlist). BREAKING contract changes vs the prior endpoint: (1) **20-F / 40-F are no longer supported** and return a refunded 400 (foreign annual reports are served by the OOM-safe /business-description card instead); (2) **10-Q items must be PART-PREFIXED** (`part1item2`, `part2item1a`) — a bare `item=1` is rejected so the Part I / Part II Item-number collision can never resolve to the wrong section; (3) **8-K items use dotted event codes** (`2.02`, `9.01`, …; hyphen `2-2` also accepted) and require `form_type=8-K`; (4) an **invalid item-for-form now returns a refunded 400** instead of a silent wrong-200. A valid-but-absent item still returns a refunded 404. The public URL is unchanged.
- 2026-06-08 (v3.43.0): PR #422 — the fund-level `activity` block's `turnover_pct` (from `GET /api/v1/form-13f/fund/{cik}?include_activity=true`) now divides by the 'total # of holdings for the quarter' = current holdings PLUS the names fully sold out this quarter, matching WhaleWisdom note 1: `turnover_pct = (new_count + sold_out_count) / (holdings_count + sold_out_count) × 100`. Previously it divided by `holdings_count` alone, dropping the sold-out names and over-reporting turnover — e.g. Berkshire Hathaway 2026-03-31 read 65.52% (19/29) instead of WhaleWisdom's published 42.22% (19/45), confirmed live end-to-end. `turnover_alt_pct` and `net_flow_pct` already used the correct flow and are unchanged. Computed live per request — no stored column, no backfill. Display-only metric on the filer-page 13F Activity card; the response shape is byte-identical (same field, corrected value).
- 2026-06-07 (v3.42.0): PR #418 — `GET /api/v1/form-13f/fund/{cik}/cusip/{cusip}/history` now SPLIT-ADJUSTS `history[].shares` (forward-adjusted to the latest split basis via the Sharadar split feed, ticker-keyed) so a stock split is no longer mislabelled as a phantom buy/sell. Previously `shares` was as-filed: AAPL's 2020 4:1 split made Berkshire's count jump 245.2M → 944.3M, rendering as a fake +699M 'buy' that dwarfed real trades on the filer-page transaction-timeline chart. That quarter now correctly shows the real -36.3M trim (verified against Dataroma: 2019-12-31 = 980,622,264). NEW additive response fields: `shares_raw` (literal as-filed count, per row), `split_adjusted` (bool), and `splits` ([{date, ratio}] applied). `value` is unchanged (already split-invariant). SELECT-only; degrades to raw shares if the ticker is unresolved or the split-feed read fails. No frontend change required — same field names, corrected values, plus additive fields callers can ignore.
- 2026-06-04 (v3.41.0): `GET /api/v1/scrapping/extractor` `type=html` now returns STRUCTURED HTML (`<h>`/`<p>`/`<strong>`/`<em>`/`<table>` markup, server-side allowlist-sanitized with nh3) instead of the legacy `<pre>`-in-`<div class='extracted-section'>` wrapper. It is powered by a new IN-HOUSE BeautifulSoup extractor (no edgartools on the hot path) that places ~99% of 10-K and 20-F item sections directly (88/89 on the regression benchmark, all foreign 20-F strategic reports recovered); on the rare filing it cannot locate (e.g. a back-of-filing cross-reference index with no item heading), it transparently falls back to the edgartools cascade, then to the legacy `<pre>` shape — so a miss never regresses below the prior behaviour. Read the `X-Extractor-Mode` response header (`structured` | `legacy_fallback` | `legacy_html` | `pending` | `notfound` | `text`) to know which path produced the body. The in-house path is also markedly faster (no edgartools accession round-trip or green-thread deadline machinery) — warm requests stay sub-second. `type=html_structured` (opt-in, edgartools-first) and `type=text` are unchanged. Cost unchanged (25 tokens).
- 2026-06-03 (v3.40.2): PR #388 — `type=html_structured` no longer returns a gateway 504 on the FIRST (cold-cache) request for a large foreign 20-F. The structured fetch+parse now runs under a wall-clock deadline in an eventlet thread-pool worker so the deadline reliably fires; on a cold cache the server returns HTTP 503 with `X-Extractor-Mode: pending` + a `Retry-After` header (NOT billed) while it prepares the section in a background thread that warms the cache, so a retry a few seconds later returns the finished `structured` body. The slow legacy fallback fetch is bounded the same way (no more unbounded cold fetch). Env knobs: `EXTRACTOR_USE_TPOOL` (default on), `EXTRACTOR_LEGACY_DEADLINE_SEC` (default 15s). No change to warm requests or to the `text`/`html` legacy shapes.
- 2026-06-03 (v3.40.1): PR #386 (+ review hardening) — the `type=html_structured` extractor cascade gains an 8th and final layer (L8) that recovers `Item 4` ('Information on the Company') for UK/AUS LSE 20-F filers — Barclays (BCS), HSBC, Unilever (UL), Rio Tinto (RIO) and peers — whose UK FCA strategic-report headings arrive through edgartools as plain prose with no `#`/`**bold**` markers, defeating the structural probes in layers 1-7. L8 substring-matches the FCA strategic-report taxonomy (generic across LSE filers, no per-ticker logic) and returns a body slice for these filers where the endpoint previously fell back to the legacy `<pre>` shape (`X-Extractor-Mode` flips from `legacy_fallback` to `structured` for this filer class). L8 fires ONLY for 20-F Item 4/4A after layers 1-7 all return nothing, so no existing 10-K/40-F or already-handled 20-F output changes. Review hardening on top of the original PR: each returned slice is bounded by a hard upper cap (no run-away whole-document capture), the anchor lists are de-duplicated, the cross-reference-TOC filter now also rejects em-dash (U+2014) separators, and the layer ships with offline unit tests. Cost unchanged (25 tokens).
- 2026-06-03 (v3.40.0): PR #383 (+ review hardening) — `GET /api/v1/scrapping/extractor` gains an OPT-IN structured-HTML mode `type=html_structured`, backed by a 7-layer edgartools-v5 cascade (clean `<h>`/`<p>`/`<strong>`/`<em>`/`<table>` markup, server-side allowlist-sanitized with nh3 so it is safe to render in a browser). The legacy `type=html` (extracted text wrapped in `<pre>` inside `<div class='extracted-section'>`) and `type=text` shapes are UNCHANGED — existing consumers see no difference, and the structured shape ships ONLY when explicitly requested (zero-disconnect; a future release may flip the default after consumer migration). Covers 10-K and 20-F (foreign private issuers); 40-F (Canadian filers) is best-effort. Additional hardening: the endpoint now returns a stable `X-Extractor-Mode` response header (`text` | `legacy_html` | `structured` | `legacy_fallback` | `notfound`); a not-found item returns HTTP 404 (and is NOT billed) instead of a 200; the `url` is validated to be on `sec.gov` for every path; and the response body is the raw extracted string (NOT a JSON envelope — the prior `responseSchema` JSON fields never matched the actual response and have been corrected). On any structured-cascade failure (e.g. transient SEC access) the response transparently falls back to the legacy `html` shape, signalled via `X-Extractor-Mode: legacy_fallback`. Cost unchanged (25 tokens).
- 2026-05-31 (v3.39.0): PR #366 — new opt-in `?include_activity=true` query param on `GET /api/v1/form-13f/fund/{cik}` adds a fund-level `activity` object with WhaleWisdom-parity quarter-over-quarter portfolio metrics: prior-quarter market value + `market_value_change_pct`, `inflow_value`/`outflow_value` (USD of newly-opened / fully-exited positions), `net_flow_pct` = (inflow−outflow)/market_value, `turnover_pct` = (new+sold_out)/holdings_count, `turnover_alt_pct` = min(inflow,outflow)/market_value, the new/sold_out/increased/decreased/unchanged counts, and `time_held_top10_qtrs`/`top20`/`all` (average holding period in quarters over the top-10/top-20/all positions by value). Computed REQUEST-TIME from the current + prior-quarter holdings the report already loads — no extra quarter fan-out — plus at most one indexed lookup into the `sec_13f_holdings_analytics` warm cache for the time-held averages. Powers the `13F Activity` card on the `/filer/<slug>-<cik>/` page in a single call. Fund-wide regardless of `?status=` (snapshotted before the status filter). Prior-dependent metrics are `null` on a fund's first filing; the three `time_held_*` fields are best-effort and `null` until the Phase 79 cost-basis analytics cache is warm for that `(cik, period)` (the other scalars always populate). Applies to `detail=full` only. Default `false` keeps the byte-identical pre-PR response shape (no `activity` key); cache key partitions on the new `:activity` dimension so pre-flag entries stay valid. Same opt-in flag pattern as `include_options` / `include_analytics` / `?status=`.
- 2026-05-31 (v3.38.0): New real-time WebSocket stream — `/13dg` (13D/G Live Stream). Schedule 13D/13G beneficial-ownership filings are now pushed live (Socket.IO namespace `/13dg`, HTTP path `/socket.io`) the moment they are parsed and committed. A single `13dg_filing` event per filing carries the COMPLETE detail object — byte-identical to `GET /api/v1/ownership/beneficial-ownership/filings/{accession}` (all filers, positions with sole/shared voting & dispositive power, classified purpose + intent flags, exhibits, structured items, and for amendments the prior/current % + threshold-crossing delta block) — plus an `event` tag and `is_catchup` flag. Server-side `subscribe` filters: issuer (CIK + ticker), filer (CIK + name substring), form type (SC_13D / SC_13G / +amendments), min ownership %, isAmendment, isConversion, purpose category, and threshold crossings (5/10/15/20%); all optional, ANDed, empty = match-all. Catch-up replays recent matching filings on connect; subscriptions persist 7 days across reconnects; `13dg_heartbeat` every 30s. Auth + tiering + billing mirror the `/13f` stream (api_key via Socket.IO auth payload / X-API-Key / Authorization / ?api_key=; Free=1 / Paid=5 concurrent per namespace; flat 100-token/UTC-day connection fee, charged separately per namespace; billing currently OFF). Runs on a dedicated `sec_13dg` Celery queue + worker so 13F deadline-day storms cannot delay the live 13D/G feed. No REST contract change.
- 2026-05-20 (v3.37.1): PR #295 — `GET /api/v1/sec/filings/{accession_number}/html` now returns the INFORMATION TABLE (positions) for `13F-HR` / `13F-HR/A` filings, not the cover page. Previously the endpoint returned the rendered cover page (`primary_doc.xml`, Form 13F front matter) for every 13F-HR filing because the stored `primary_html_url` pointed there — the actual positions live in a separate XML file in the same accession folder (`xslForm13F_X02/<infotable>.xml`) and were unreachable from the consumer iframe. The handler now skips the cached `primary_html_url` for 13F-HR and parses the index page's Document Format Files table, picking the row whose `doc_type` is `INFORMATION TABLE` (preferring the XSL-rendered URL so SEC's server-side XSLT returns styled HTML with COLUMN 1-8 position headers). Existing cached cover-page content is detected on read (title contains `FORM 13F COVER PAGE` and not `FORM 13F INFORMATION TABLE`) and re-fetched automatically — no backfill or migration required, no client action needed. Affects 13F-HR + 13F-HR/A. Unchanged for 10-K, 10-Q, 8-K, Form 4, 13D/G — those forms' `primary_html_url` already points to a `.htm` file. User-visible: `finradar.ai/sec/<13f-accession>/` now renders the holdings list instead of just the cover sheet.
- 2026-05-19 (v3.37.0): PR #285 — new `?status=` query param on `GET /api/v1/form-13f/fund/{cik}` for server-side filtering of the holdings list to a single position-classification bucket. Valid values: `all` (default — no filter, byte-for-byte pre-PR behavior), `new`, `increased`, `decreased`, `unchanged`, `closed`. Powers the New / Increased / Decreased / Unchanged / Closed status pills on the `/filer/<slug>-<cik>/` page where client-side filtering breaks down for BlackRock-class filers (5K+ holdings, only a partial buffer in memory at any time). `closed` is special-cased — closed positions are absent from the current `holdings` list (in prior quarter, not current), so the handler synthesizes standard-shape rows from the `closed_list` analysis bucket with `shares=0`, `value=0`, `change_percent=-100`, `status='Closed'`, and the prior values preserved as `shares_sold` / `value_sold`. `meta.pagination.total` reflects the FILTERED count so pagination stays correct across pill switches; `analysis.*.total` continues to reflect the UNFILTERED per-category totals so the pill counts themselves stay accurate. Cache key partitions on the new dimension; default `all` omits the suffix so pre-PR cache entries remain byte-for-byte valid. Mirrors the precedent on `GET /api/v1/tickers/{ticker}/holders?status=`. Unknown values silently fall through unchanged (same convention as `sort_by`/`sort_order`).
- 2026-05-19 (v3.36.1): Frontend now ships real pages for the forgot/reset password flow (no API contract change). Previously the backend's `POST /api/v1/auth/forgetpassword` + `PUT /api/v1/auth/newpassword` were live but the matching `/forgot-password` and `/reset-password` SPA routes did not exist, so the 'Forgot password?' link on the login screen and the 302 redirect from `GET /api/v1/auth/verifyPasswordLink` both hit the catch-all and bounced users to `/`. This release adds those two pages: `/forgot-password` posts to `/auth/forgetpassword` and shows the anti-enumeration generic toast; `/reset-password` reads the `?token=` (or `?error=invalid_or_expired`) emitted by `verifyPasswordLink` and PUTs `{token, newpassword}` to `/auth/newpassword`. On success the user is redirected to `/login?reset=success`, which the Login page now renders as a green success banner (matches the existing `?verify_email=success` pattern). Two small backend changes ride along: (1) `users.password_changed_at TIMESTAMP NULL` column added, written by `/auth/newpassword` on a successful reset (and backfilled to `COALESCE(updated_at, created_at)` for existing rows) — surfaces a 'Last changed' line on the future `/account/security` page and stamps the new notification email; (2) on a successful password reset the user now receives a 'Your FinRadar password was changed' email with a self-rescue 'Reset password' button — closes the security-audit P0 'no notification of security-relevant events to user email' gap. No API contract change for any caller — bodies, status codes, headers, and the `verifyPasswordLink` 302 target are byte-identical to v3.36.0.
- 2026-05-18 (v3.36.0): News section removed from public documentation pending commercial release. The 4 endpoints (`GET /api/v1/news/feed`, `GET /api/v1/news/ticker/{ticker}`, `GET /api/v1/news/sources`, `GET /api/v1/news/stats`) are sourced from a separate aggregated-news pipeline that is not part of the launch offering and will not be billable. The section is no longer reachable from the sidebar, the `/docs` router, the `/docs/llms-txt` viewer, the `/llms.txt` LLM-fetch surface, the Cmd+K search palette, or the public sitemap. Backend routes are unchanged for the moment; the section will be re-surfaced in apiDocs when the underlying pipeline is ready to commercialize. No client-facing breaking change — these endpoints were never advertised as a billed product.
- 2026-05-18 (v3.35.0): Pre-launch close-out batch (issues #260 / #261 / #276). **(1) `GET /api/v1/account/transactions` rows now carry `response_status` (#260).** Each debit row in the response now includes the HTTP status code the handler returned for that request (200 / 400 / 401 / 403 / 404 / 500 / etc.). Refund rows stay `null` (they're bookkeeping follow-ups, not responses). Pre-migration rows also stay `null` (the column was just added). New nullable `SMALLINT` column on `token_transactions`; populated by the token meter via an UPDATE after the handler returns. Useful for ops + users to audit error-billed vs success-billed history (combined with the auto-refund from #254, the typical error row appears as a `debit` with status=4xx/5xx paired with an immediate `refund` row — net-zero on the ledger, but now visibly correlated). **(2) `GET /api/v1/tickers/{ticker}/overview` negative-cache TTL reduced from 1 hour to 60 seconds (#261).** Previously a single transient Yahoo Finance throttle / hiccup locked the ticker out of the endpoint for an hour because the 404 response was cached for 3600s. Most 404s here aren't 'ticker doesn't exist' — they're 'yahooquery's upstream momentarily refused us' — so an hour-long lockout was wildly disproportionate. The successful-response cache stays at 24h (unchanged). Also added an `INFO` log on the 404 path with the inferred yahooquery shape so ops can correlate spikes with Yahoo's throttling. **(3) Local-dev: insider_api on `localhost:5002` (#276) is unreachable via host port-forward on Windows Docker Desktop (TCP connects but server closes without responding). Internal Docker network access (`http://insider_api:8000/health` from another container) works fine, and production routes via nginx — so the issue is local-dev only and not user-visible. Documented for future devs; no code change needed.** No API contract changes other than the additive `response_status` field on `/account/transactions` rows.
- 2026-05-18 (v3.34.0): Auth UX polish bundle (issues #257 / #258 / #262 / #263). **(1) `GET /api/v1/auth/verifyEmail` no longer renders a JS `alert()` + `window.close()` (#257).** Modern browsers refuse to close tabs the user opened from an email link, so the legacy behaviour left a blank page after dismissing the alert — terrible first impression. The handler now 302-redirects to the FinRadar frontend at `/login?verify_email=success` on success and `/login?verify_email=invalid` on any failure (anti-enumeration: same `invalid` code for token-decode-fail, wrong purpose, unknown user, and already-consumed row). The Login page reads the query param and renders an emerald banner ("Email verified. Please sign in.") or a red one. **(2) Welcome email no longer carries the raw API key in the body (#258).** Mailbox compromise alone used to be enough to take over the account's API access (key sat in inbox forever, archive-readable). The email now shows a 'Get your API key →' CTA linking to `/account/credentials` on the frontend; user must log in with their password to view + copy + rotate. The first-call curl example uses a `YOUR_API_KEY_HERE` placeholder. Signature change: `send_welcome_email(email, credentials_url, docs_url=..., feedback_email=...)` — `api_key` arg removed. The register handler now passes `_frontend_base_url() + '/account/credentials'`. **(3) Register form client-side validates password length (#262).** The form already checked password ≠ confirmPassword; it now also checks `password.length >= 6` (the same threshold the server-side validator enforces) so a too-short attempt doesn't round-trip to the server. Pure UX, server is still the security boundary. **(4) Register form no longer sends hardcoded `first_name: 'User'` / `last_name: 'Name'` (#263).** The backend `register()` handler doesn't read those fields and the `users` table has no such columns; the hardcoded sentinels were misleading dead code. Dropped from the POST body. All four are UX hardening — no public-contract changes, no migration.
- 2026-05-18 (v3.33.0): Rate-limit infrastructure hardening (issues #255 / #256). **(1) Flask-Limiter switched to Redis backend (#256).** Previously the limiter used per-worker in-memory storage, which meant the documented `60 per minute per IP` global cap became `60 × N workers per IP` in practice (the limiter's startup warning had been firing on every container boot). Storage is now `redis://redis:6379/2` (dedicated DB number to avoid collision with Celery on db 0 and Socket.IO session data on db 1). Override via `RATELIMIT_STORAGE_URI` env var. Single shared counter across every worker; container restarts no longer reset the rolling window. **(2) Rate-limit headers now emitted on every response (#255).** Every limited endpoint now carries four headers that clients (incl. our own Try-It panel) can use for proper backoff: `X-RateLimit-Limit` (the cap, e.g. 60), `X-RateLimit-Remaining` (requests left in the current window), `X-RateLimit-Reset` (Unix epoch when the window resets), and `Retry-After` (seconds until you can retry — particularly useful on the 429). All four are added to `Access-Control-Expose-Headers` so browsers don't strip them on cross-origin reads. **Behavioural note**: the headers ride along on 200 OKs as well, so frontend code can render a `requests remaining` indicator pre-emptively rather than waiting for the first 429. Backwards compatible — no public-contract changes, no migration needed; clients that don't read the new headers see no difference.
- 2026-05-18 (v3.32.0): Pre-launch security hardening pass #3 (issues #269 / #274). **(1) `X-Request-ID` idempotency on every metered endpoint (#274).** When a client sends an `X-Request-ID` request header, the token meter dedup-checks against prior debits — if a non-refunded debit row already exists for `(user_id, X-Request-ID)`, the request short-circuits the bill (returns `X-Tokens-Charged: 0`) but still hits the handler so the client receives a fresh response. This lets retry loops (axios-retry, urllib3, server-to-server clients re-driving after a transient network failure) safely replay without double-billing the user. Refunded prior debits do NOT count for dedup: a 5xx that was auto-refunded (per #254) followed by a successful retry with the same X-Request-ID bills the retry fresh — the user paid for nothing the first time. New nullable column `token_transactions.idempotency_key` + partial unique index `uq_token_transactions_user_idem_debit ON (user_id, idempotency_key) WHERE idempotency_key IS NOT NULL AND reason = 'debit'`. Backwards compatible: callers that don't supply `X-Request-ID` keep the prior per-request billing semantics. **(2) `email_verify` table now carries a `purpose` discriminator (#269).** Previously the `email_verify` table was shared by the email-verification AND password-reset flows without a discriminator, which allowed a row issued for one flow to be silently consumed by the other flow's handler (e.g. a mistakenly-clicked password-reset link verified the user's email; a mail-preview prefetch on an email-verification link burned the user's reset token). The table now has `purpose VARCHAR(32) NOT NULL DEFAULT 'email_verification'` with composite uniques `(uuid, purpose)` and `(email, purpose)` (the legacy single-column uniques on uuid + email were dropped). JWTs issued by `/auth/register`, `/auth/resend-verification`, `/auth/forgetpassword` now carry a `purpose` claim in the payload (`email_verification` | `password_reset`), and the verifying handlers (`/auth/verifyEmail`, `/auth/verifyPasswordLink`, `/auth/newpassword`) reject tokens whose `purpose` doesn't match. Invite-redemption tokens are tagged `purpose=invite` for defense-in-depth (no cross-consumption was ever possible anyway since invite tokens don't touch the email_verify table). **Backwards compatibility:** the JWT payload's `purpose` claim defaults to `email_verification` when absent (so legacy verify-email tokens still work); password-reset rows in flight at the time of the migration are silently re-classified to email_verification and become unusable for password-reset — the affected user just requests a fresh `/forgetpassword` (no manual intervention required). The composite uniques replace the per-user single-row constraint, so a single user can now hold one email_verification row AND one password_reset row simultaneously.
- 2026-05-18 (v3.31.0): Pre-launch security hardening pass #2 (issues #259 / #272 / #273 / #275). **(1) `POST /api/v1/auth/login` brute-force lockout (#272).** Per-account consecutive-failure counter: 5 fails → 60s lockout, 10 → 5min, 20 → 1hr. During lockout the endpoint returns HTTP 429 with a `Retry-After` header in seconds — even if the supplied password is correct (intentional: an attacker must not be able to fish for whether they've guessed right inside the lockout window). A successful login resets the counters to zero. New columns on `users`: `failed_login_count INT NOT NULL DEFAULT 0`, `lockout_until TIMESTAMP NULL`. **(2) `POST /api/v1/sql-proxy` error sanitization (#273).** DB-runtime errors (division by zero, type mismatch, etc.) no longer echo the raw psycopg2/SQLAlchemy trace + offending SQL back to the caller — those revealed the backend stack and helped blind-SQLi recon. Response body is now a generic `{success: false, error: 'Query execution failed.'}` with HTTP 500 (was HTTP 400 + full trace). Full detail logged server-side with the request_id for ops forensics. 500 also lets the token meter's auto-refund branch credit back the 25-token charge (the user didn't make a bad request; the DB couldn't satisfy a syntactically-valid one). Policy-rejection errors (forbidden keyword, disallowed table) still emit their short non-revealing messages at 4xx — those are also AUTO-REFUNDED per the 2026-05-18 batch-1 #254 change. **(3) HTTP 402 payload enriched (#259).** `current_balance < cost` responses now also include `plan_display_name` and `monthly_quota` so SDK consumers can render 'X / Y free tokens used' without a round-trip to `/account/balance`. The pre-existing `current_balance`, `required_cost`, `next_refill_at`, `plan`, `upgrade_url` keys are unchanged. **(4) Wrong HTTP method now returns 405 (#275).** A global `werkzeug.exceptions.HTTPException` errorhandler was added + an explicit 405 handler with `code: METHOD_NOT_ALLOWED`. Previously any non-handled HTTPException (405 / 406 / 413 / 415 / 422 / 423 / 501 / 502 / 503 / etc.) fell through to the `Exception` catchall and emerged as 500 — that hid real server bugs in 5xx telemetry and triggered the token meter's 5xx refund branch unnecessarily. The explicit per-status handlers (400, 401, 403, 404, 429, 500) are unchanged. **Backwards compatibility:** the lockout response is a NEW 429 status on `/login` (callers that already handled 429 elsewhere — e.g. global rate-limit — see no shape change); the sql-proxy status flip 400 → 500 changes which branch retry libraries take, but the success / 401 / 403 paths are unchanged; the 402 body adds two fields (existing parsers ignore unknown fields); 405 callers that were getting 500 should switch to checking 405. No client-config changes required for FinRadar's own frontend.
- 2026-05-18 (v3.30.0): Pre-launch security hardening pass (issues #254 / #264 / #265 / #266 / #267 / #268 / #270 / #271). **Auth + billing changes that touch the public contract:** (1) `POST /api/v1/auth/forgetpassword` — `weblink` body field is REMOVED; the reset link in the email now always points at the FinRadar frontend's `/reset-password?token=...` page (server-controlled). The endpoint now always returns 200 with the generic message `If that email is registered, a password-reset link has been sent.` regardless of whether the email is registered (anti-enumeration). (2) `PUT /api/v1/auth/newpassword` — **BREAKING:** `userId` body field is REMOVED; the endpoint now REQUIRES `token` (the reset JWT from the email link). Previously the endpoint accepted only `{userId, newpassword}` with no auth — a full account-takeover vector for anyone who knew a target's UUID. The token is validated against the live `email_verify` row and consumed atomically with the password update; all active sessions are invalidated on success (OWASP). (3) `GET /api/v1/auth/verifyPasswordLink` — the `link` query param is now IGNORED. The handler always 302-redirects to the FinRadar frontend's `/reset-password?token=...` page. The previous open-redirect (`?link=https://evil.example.com`) is closed; the user's UUID no longer appears anywhere in the redirect URL. (4) `POST /api/v1/auth/login` — error messages for 'unknown email' and 'wrong password' are now identical (`Invalid email or password`) at status 401 (was 400). Closes the email-enumeration channel. (5) `POST /api/v1/auth/resend-verification` — already-verified accounts now receive the same generic 200 message as unknown emails, instead of a distinguishable 400. **Auth + billing changes that are invisible to well-behaved callers:** (6) The `Origin: https://finradar.ai` (and 5 other finradar.* origins) auth + billing bypass on metered endpoints is REMOVED. CLI/non-browser callers spoofing that Origin no longer get free unauthenticated data. (7) The token meter now REFUNDS 4xx responses (previously only 5xx). 401 / 403 / 400 / 404 calls show `X-Tokens-Charged: 0` and produce a paired `debit` + `4xx_refund` row in `/account/transactions`; net-zero on the ledger. Closes the `/sql-proxy` abuse vector where a malicious caller could drain a victim's bucket via `DROP TABLE` 403s. (8) JWT `session_id` invalidation now applies to every JWT-accepting decorator (`api_auth_required`, `account_auth_required`, `jwt_required_custom`). A JWT whose session has been kicked (device-limit eviction or password reset) now 401s across the full metered surface, not just the account-billing endpoints.
- 2026-05-17 (v3.29.0): New endpoint (PR #248) — `GET /api/v1/form-13f/aggregation/by-industry` — industry-first mirror of `/aggregation/by-sector`. Returns a flat industries array with sector context nested per industry, instead of grouping industries under their parent sector. Answers cross-sector questions like 'which industries had the biggest fund inflows this quarter regardless of sector?' in a single round-trip, no client-side flatten+re-rank required. Same `sec_13f_sector_summary` data source, same 2-level top-movers resolution (`cusip_mappings.sector` → `cusip_mappings.ticker → all_stocks_list`), same `coverage_pct` math, and same `quarter_metadata` block as the sector endpoint. Params: `quarter` (defaults to latest), `compare=prev` (adds per-industry QoQ deltas: `flow_change`, `prev_momentum_label`, `momentum_shift`, `fund_count_change`, `value_change_pct`), `limit` (default 50, max 200, or `all` — when no `sector` filter set, returns top-N inflows + top-N outflows; when `sector` filter set, returns top-N by `abs(metric)`), `sort_by` (`fund_flow` or `significance`; legacy `sort` alias accepted), `sector` (optional single-sector drill-down — skips the inflow/outflow split). Free — `cost: 0` token charge. No backend schema changes; no impact on `/by-sector` or any other route.
- 2026-05-16 (v3.28.1): Sniper accession-base prediction now queries the filer's actual latest accession from the local DB index (indexed by LEFT(accession_no,10) prefix + 2-digit year) rather than using a stale in-memory snapshot. Both self-filing and historical third-party filer prefixes are probed in parallel, ranked by filing recency. Year boundaries reset automatically (December near-exhaustion + calendar-year rollover). A background rebase loop (SNIPER_REBASE_ENABLED flag) periodically refreshes candidate_urls during the active sniper window via a SQL-guarded UPDATE that no-ops on completed targets. New sniper_targets columns: baseline_source (db_primary / legacy) and last_baselined_at. Internal improvement — no API surface change.
- 2026-05-15 (v3.28.0): Sniper hits now trigger full 13F parse + holdings-aware notification (stages: filing_acquired, enriched, no_holdings, failed_fallback). New response fields on /api/v1/sniper/targets (both GET and POST): filing_uuid (FK to filings.uuid once parsed), processing_state (one of detected/parsing/parsed/enriched/no_holdings/parse_failed — orthogonal to status), holdings_count (number of form_13f_holdings rows when parsed or later), parsed_at (ISO 8601 UTC timestamp when parse completed), enriched_at (ISO 8601 UTC timestamp when OpenFIGI enrichment completed), candidate_urls (range-scan window of predicted [{accession, url}] objects assembled at target creation). WebSocket payload (event=snipe_success) gains: stage, holdings_count, tickers_resolved, tickers_pending, period_of_report, view_url.
- 2026-05-14 (v3.27.0): Phase 72-02 — on-the-fly fund analytics pipeline + deadline snapshot backfill. (1) **5-15 min latency for multi-period returns.** `process_filing` now enqueues into a new `pending_fund_analytics` queue table at the end of every successful 13F parse (gated on `ENABLE_FUND_ANALYTICS_HOOK=true` env var; reparse / data-correction paths explicitly opt out via `enqueue_analytics=False`). A new Airflow DAG `fund_analytics_drain` (every 5 min, `light-ops` pool) claims pending rows, groups by quarter, and dispatches batches of ≤50 CIKs to a new Celery task `compute_fund_perf_batch` on heavy_ops that performs: per-CIK quarter-row UPSERT (via new `FundPerformanceService.compute_for_cik_batch`) → daily-returns extension → multi-period rollup → cache invalidation. Compared to the prior 8h `market_analytics` cadence + 24h `fund_analytics_daily` cadence, this is a 100× latency improvement for new filings going forward. (2) **Pre-deadline backfill of ~7,500 non-tracked CIKs.** New one-shot Airflow DAG `fund_analytics_snapshot_backfill` (paused on creation, manual trigger) populates `return_1y/3y/5y/10y/inception`, `sp500_return_*`, `alpha_*` for every non-tracked CIK currently NULL on `sec_13f_fund_performance`, using a quarter-snapshot rollup method (`return_N = portfolio_value[q] / portfolio_value[q-N*4] - 1`) instead of the daily mark-to-market method. The 580 tracked funds keep their daily-method values untouched (decision C7 hybrid methodology). Verified `<1%` drift vs the daily method on Berkshire / BlackRock / Lone Pine reference funds via the new `scripts/ab_verify_snapshot_rollup.py` C8 gate (must PASS before unpausing the backfill DAG). Full 7,500-CIK run estimated ~12–15 min wall-clock on heavy_worker, ordered by `MAX(portfolio_value) DESC NULLS LAST` so famous funds populate first if the run is interrupted. (3) **Postgres advisory lock** on `quarter_date` (`pg_advisory_xact_lock(hashtext('fund_perf_q_' || quarter_date))`) serializes `compute_quarter`'s whole-quarter DELETE+INSERT against the new per-CIK upserts so concurrent runs can't corrupt each other's writes. (4) **30-min escape hatch** on stuck claimed rows in `pending_fund_analytics` (`failure_count < 3` AND (claimed > 30 min ago OR claimed_at IS NULL)) so worker crashes or dispatch-skip scenarios don't permanently strand pending work. **Backwards compatibility:** every existing `/api/v1/form-13f/fund-performance` caller sees byte-identical response shapes; only delta is that previously-NULL multi-period columns now carry values for all 8K+ filers. **H8 recommendation for finradar.ai:** when a response row has `return_1y=null AND portfolio_return_pct!=null`, render a 'Returns computing — refreshes shortly' placeholder in the perf card section to signal the 5–15 min backfill latency (covers the brief window between new-filing parse and drain-DAG processing).
- 2026-05-14 (v3.26.0): Phase 72/leaderboard enhancements (PR #185) — `/api/v1/form-13f/fund-performance` leaderboard mode gains four additive features for the new Fund Performance Leaderboard table on FinRadar.ai's hedge-fund-analyzer page: (1) **`?q=<text>` search** — same filer-universe match as [/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers) (`company_name` / padded CIK / unpadded CIK / `signature_name` / `filer_aliases` famous-manager lookup like `buffett` → Berkshire). Empty matches return `data.leaderboard=[]` (NOT 404) so frontends can render an empty-state UI while `quarter_metadata` + `pagination` stay valid. Logic extracted into a shared `_search_filer_ciks(q)` helper that both `/filers` (autocomplete) and `/fund-performance` (leaderboard) now call — guaranteed identical match pools. `/filers` keeps its alias-priority `ORDER BY` ranking (alias-matched filers float to top) since leaderboard sort is user-driven. (2) **`?has_returns=true` filter** — drops rows where `return_1y IS NULL` to hide the ~75% multi-period-rollup coverage gap. Default `false` keeps the full filer universe browsable; FinRadar's leaderboard UI defaults this toggle ON. (3) **Sort whitelist extended from 4 → 20 keys** — adds `return_1y/3y/5y/10y/inception`, `sp500_return_1y/3y/5y/10y`, `alpha_1y/3y/5y/10y`, `portfolio_turnover`, `buy_value`, `sell_value`, `company_name`. The Phase 62-01 and Phase 72-01 multi-period rollup columns are now finally exposed as sort keys. Pre-existing keys (`portfolio_return_pct`, `portfolio_value`, `holdings_count`, `price_coverage_pct`) unchanged. Both `sort_by` and the legacy `sort` aliases work. (4) **`data.available_quarters` on first page** — distinct list of `quarter_date` values (newest-first) present in `sec_13f_fund_performance`, returned ONLY when `offset=0`. Lets frontends populate a quarter-selector dropdown without a second round-trip. Omitted on infinite-scroll continuations to keep them lean. **Default-behavior preservation:** every existing caller (no `?q=`, no `?has_returns=`, no new `sort_by` values) hits the SAME SQL filters + SQL sort + response shape as v3.25.0; only delta is the additive `data.available_quarters` field on `offset=0` responses (existing parsers ignore unknown fields).
- 2026-05-13 (v3.25.0): New endpoint (PR #184) — `GET /api/v1/form-13f/fund/{cik}/cusip/{cusip}/history` returns the per-quarter share + value history for a single (fund, CUSIP) position. One row per 13F-HR quarter where the position appeared, carrying `quarter_date`, `shares` (as-filed, not split-adjusted), `value` (USD), `shares_delta` (QoQ), and `transaction_type` ∈ {`new`, `increased`, `decreased`, `unchanged`}. Filing selection per quarter mirrors `CostBasisService` / `/fund/{cik}` exactly — pick the filing with MOST non-option holdings (#264 amendment-handling) so a 4-holding 'correction' 13F-HR/A doesn't overwrite a 36-holding original. CUSIP-keyed (not ticker) so corporate-action chains (mergers, spinoffs, the SIRI 2024 reverse-split CUSIP flip `82968B103 → 829933100`) don't break the timeline. Best-effort ticker + `security_name` enrichment via `cusip_mappings`. CUSIP shape validation: alphanumeric only, ≤ 12 chars → 400 BAD_REQUEST. Unknown (cik, cusip) combination → 404 NOT_FOUND. Closed positions stop appearing in the response when the fund no longer holds the security — no synthetic 0-share row is emitted. Powers the chevron-expanded transaction-timeline chart on FinRadar.ai's `/filer/<slug>-<cik>/` page (replaces the placeholder 'Transaction-timeline chart coming next — needs per-ticker quarterly history endpoint'). Free — `cost: 0` token charge.
- 2026-05-13 (v3.24.0): Phase 73 — options visibility two-PR bundle: (1) `normalized_holdings_deduped` matview partition key extended (PR #181) to include `put_call_options`, recovering ~1.49M previously-collision-dropped option rows for filers holding BOTH common stock AND options on the same underlying CUSIP (legal per SEC 13F-HR spec). Pre-fix: Duquesne Family Office (CIK 0001536411) Q4 2025 showed 2 of 4 Call options on `/api/v1/form-13f/fund/{cik}?include_options=true` (SPY + IWM survived; EWZ $134M Call + AMZN $23M Call were silently dropped because Duquesne also held the underlying common). Post-fix matview rebuild (22m 45s wall-clock, atomic `--single-transaction` swap on UAT 2026-05-13): all 4 Calls now visible, total matview row count 72.70M → 74.72M. Backwards-compatible — filers holding only common OR only options on a given CUSIP see no behavioral change (the new fourth partition dimension is single-valued for them). (2) New `?options_only=true` query parameter on `/api/v1/form-13f/fund/{cik}` (PR #182). When `true`, response carries ONLY options rows (`is_option=true`) — overrides `include_options`. Lets clients fetch the Options-tab payload for `/filer/<slug>-<cik>/` without pulling the full equity book (2K-5K rows for BlackRock-class; 0 rows for Berkshire). Cache key partitions independently with `:options-only` suffix replacing `:opts` so the three shapes (default / `:opts` / `:options-only`) never collide. Default `false` keeps the byte-identical pre-3.24.0 response for every existing caller (hedge-fund-search-v2, screener, sandbox FundReport.jsx, AI Chat Tool 22). Cutover: FinRadar's filer-proxy switches from `?include_options=true` (60-5K-row) to `?options_only=true` (2-50-row) for the Options-tab fetch — one-line URL edit in `filer-proxy.php`.
- 2026-05-12 (v3.23.0): Phase 69 Plan 05 (PR #166) — opt-in per-holding cost-basis analytics on `/api/v1/form-13f/fund/{cik}` + soft-deprecation of `/holdings-analytics`. (1) New `?include_analytics=true` query param on `/fund/{cik}` (default `false`). When `false` (or omitted), response is BYTE-IDENTICAL to v3.22.0 — same SQL filter, same row count, same Redis cache key, same `holdings[]` shape. When `true`, each `holdings[]` row gains 11 cost-basis analytics fields (`avg_buy_price`, `current_price`, `cost_basis`, `market_value`, `unrealized_pnl`, `unrealized_pnl_pct`, `holding_period_days`, `holding_period_quarters`, `first_added`, `last_share_delta`, `last_transaction_quarter`; plus `sector` when /fund/{cik}'s row doesn't already carry one) — same VWAP-of-quarterly-closes methodology as the now-deprecated `/holdings-analytics` route. Cache key composes correctly: the four combinations (no flags / `:opts` / `:analytics` / `:opts:analytics`) cache independently. If `CostBasisService` raises for an exotic CIK, the analytics decoration is skipped with a warning log — the default `/fund/{cik}` response is never broken by an analytics failure. Same opt-in flag pattern as `?include_options=true` (PR #149). (2) `/api/v1/form-13f/fund/{cik}/holdings-analytics` is now SOFT-DEPRECATED — returns HTTP 302 Found with `Location: /api/v1/form-13f/fund/{cik}?include_analytics=true`. The redirect is returned BEFORE any service call so the deprecated route never triggers `CostBasisService` (no DB load on deprecated clients). HTTP clients that follow redirects (axios/fetch/curl -L/PHP/WP defaults) keep working transparently; clients that explicitly disallow redirects must update their URL. The softer 302 (vs the originally-planned 410 Gone) is the deployment-ordering escape valve — UAT auto-deploys on merge and a hard 410 would degrade the live filer-profile page in the window between this PR's UAT-deploy and the downstream WordPress-adapter cut-over. The route is expected to remain a 302 redirect for at least one release after adapter migration; full removal will get its own deprecation notice in this changelog before it ships. NO-replicated-variables policy preserved (D-04): the 11 analytics fields are owned by `/fund/{cik}?include_analytics=true` only — `/fund-performance` and `/daily-returns` (Phase 69 Plan 03, PR #165) remain free of replicated cost-basis state.
- 2026-05-12 (v3.22.0): Phase 69 Plan 03 (PR #165) — `/api/v1/form-13f/fund-performance` leaderboard rows drop seven previously-replicated fields: `new_positions`, `closed_positions`, `increased_positions`, `decreased_positions`, `unchanged_positions`, `top_sector`, `sector_concentration_hhi`. Each of these is now owned exclusively by `/api/v1/form-13f/fund/{cik}` (under `analysis.new.total` / `analysis.closed.total` / `analysis.increased.total` / `analysis.decreased.total` / `analysis.unchanged.total` for the position-change counts; `sector_allocation.top_sector` / `sector_allocation.sector_concentration_hhi` for the sector-concentration pair) per the Phase 69 D-04 'each variable owns exactly one endpoint' decision. **BREAKING** for any caller relying on these keys on `/fund-performance` — switch to `/fund/{cik}` for the same data. `top_contributors`, `top_detractors`, `portfolio_return_pct`, `portfolio_value`, `holdings_count`, `price_coverage_pct` are unchanged on `/fund-performance`. Same PR also drops the top-level `summary` block (`total_return_pct`, `sp500_return_pct`, `alpha_pct`) from `/api/v1/form-13f/fund/{cik}/daily-returns` — those scalars duplicate `/fund-performance`'s `return_*y` and `alpha_*y` for the selected period. The `data` block (chart arrays / table rows) on `/daily-returns` is preserved verbatim. Three previously-undocumented fields (`increased_positions`, `decreased_positions`, `unchanged_positions`, `sector_concentration_hhi`) were never in apiDocs.js for `/fund-performance` so their removal is doc-invisible on the leaderboard surface — but they were live in the JSON response and any LLM that introspected the response shape will need to drop them.
- 2026-05-10 (v3.21.0): Phase 68 (issue #148, PR #149) — opt-in options on `/api/v1/form-13f/fund/{cik}` + holdings-analytics enrichment. (1) New `?include_options=true` query param on `/fund/{cik}` (default `false`). When false, response is byte-identical to pre-3.21.0 — same SQL filter, same row count, same Redis cache key. When true, response includes options positions (puts/calls) alongside long-equity holdings; rows always carry the new `is_option` boolean (and existing `put_call` field) regardless of mode so clients can filter client-side. The two response shapes cache independently (`:opts` suffix on the cache key when true). All other callers (`POST /fund/bulk`, `/13f` WebSocket builders, hedge-fund-search-v2 inline report, screener, basket aggregator) pass the kwarg as default-False ⇒ zero behavior change. (2) `/api/v1/form-13f/fund/{cik}/holdings-analytics` per-row output gains three additive Phase 68 fields: `sector` (Sharadar GICS-style; resolution priority `cusip_mappings.ticker → all_stocks_list.sector` with `holding_info.sector` fallback excluding the literal 'Equity'), `last_transaction_quarter` (ISO `YYYY-MM-DD` of most-recent quarter where the split-adjusted share count moved — null for static-since-acquisition positions), and `last_share_delta` (signed split-adjusted share delta on that quarter; positive = added, negative = trimmed). Tracked AFTER split adjustment so a 4:1 stock split alone does NOT register as a transaction. Powers the 'Holdings' tab + 'Latest Trades' sort mode + Sector / Industry filter dropdown on `/filer/<slug>-<cik>/`. Endpoint also newly documented in apiDocs (was missing — pre-Phase-59 long-tail backfill gap closed). No DB migration; no removed fields; no breaking changes.
- 2026-05-06 (v3.20.2): Issue #101 — WebSocket auth: `/sec`, `/13f`, `/insider-module` now accept api_key via three methods, first match wins: (1) Socket.IO `auth` payload (`io(url, { auth: { api_key: '...' } })`) — recommended; (2) HTTP header `X-API-Key` or `Authorization: Bearer`; (3) query `?api_key=`. Pre-fix only query params worked, so customers following the docs got `One or more namespaces failed to connect`. **BREAKING:** undocumented `?token=` query param REMOVED — move to one of the three methods above. JWT browser-session auth still works via `auth.token` payload. Token billing (100/day) and concurrent-cap unchanged.
- 2026-05-06 (v3.20.1): Issue #100 — `/api/v1/account/balance`, `/api/v1/account/usage`, and `/api/v1/account/transactions` now accept `X-API-Key` (or `Authorization: Bearer <api_key>`) in addition to the existing session JWT. Closes the commercial-readiness gap where server-side automation scripts could not budget-check before bursty workloads (the docs already advised non-browser callers to use api_key, but these three endpoints were the only customer-facing exemption). Auth method does NOT change billing — the endpoints stay free (`cost: 0`, `@meters_tokens` exempt) regardless of how the caller authenticated. `POST /api/v1/account/billing-portal` remains JWT-only by design (Stripe Customer Portal is a browser-redirect flow with no automation use case). Backed by a new `account_auth_required` decorator in `app/middleware/auth.py` that omits the first-party-origin bypass present in `api_auth_required` — account routes always need a real user identity.
- 2026-05-02 (v3.20.0): Phase 59 long-tail content backfill (Wave 3, plans 59-04 through 59-09) — 91 previously-undocumented endpoints across 11 sidebar groups now ship full Polygon-grade content: populated `responseSchema[]` (with `field` / `type` / `nullable` / `description` per row), realistic `sampleResponse` data using marquee public-domain identifiers (AAPL/MSFT/NVDA/GOOGL/TSLA + Berkshire 0001067983 / BlackRock 0001364742 / Vanguard 0000884144 + Tim Cook 0001214156 / Warren Buffett 0000315090), persona-grounded `longDescription` (2-4 paragraphs with inline `/docs/...` cross-links), and 4-entry `related[]` cross-section adjacency arrays. Per-plan endpoint coverage: Plan 59-04 = 15 Insider Trading endpoints (event-sourced ledger + Section-16 P/S transaction codes + cluster-detection tier signals); Plan 59-05 = 15 Account-group endpoints (cents-vs-dollars unit emphasis + Stripe-PaymentIntent client-secret pattern + signed-delta token-ledger semantics); Plan 59-06 = 14 SEC Filings group endpoints (canonical accession-number XXXXXXXXXX-YY-NNNNNN format + form-type catalog cross-linking + non-JSON body endpoint pattern); Plan 59-07 = 13 Form 13F API endpoints (10-char zero-padded CIK convention + ISO YYYY-MM-DD calendar quarter-end + Phase 51 holdings-quality value-normalization + Phase 52 split-adjustment redirect); Plan 59-08 = 15 Company Data endpoints (XBRL units-and-concept-explicit pattern + Yahoo-vs-XBRL ±2% normalization-difference disclaimer + non-calendar fiscal-year-end aware behavior); Plan 59-09 = 19 long-tail endpoints across CUSIP API (8 — Phase 11/47 successor-chain semantics + OpenFIGI 24% null-ticker caveat + CUSIP6 NOT stable across reorgs), Ownership & Positions (5 — Phase 47 unified-holder layer + holder_uuid stable cross-source identifier + per-source-type drill-down vs merged-feed shape contracts), Sniper (3 — 3-state lifecycle CREATED/ACTIVE/STOPPED + plan-allocated sniper-slot budget + manual_stop idempotency), Webhooks (1 — DIRECTIONAL FLIP contract for events FinRadar SENDS to customer URL with HMAC-SHA256 X-FinRadar-Signature + 10s/60s/300s exponential-backoff retry policy + WS-stream alternative), Home (1 — `/api/v1/stats` poll-safe platform metrics), and Resources (1 — `/api/v1/status/history` with hourly-vs-daily resolution-clamp guard). After this release: ZERO non-deprecated, non-admin, non-WS endpoints in the documentation surface have missing `responseSchema` (Phase 59 completeness criterion fully met). Combined with Phase 58's top-50 Polygon-grade polish (Plans 58-07 + 58-11), the v5.0 API Documentation Rework milestone now ships full Polygon/sec-api.io/IEX-Cloud-grade documentation across all customer-facing endpoints. No backend behavior changes — documentation surface only. Regenerated `/llms.txt` and `/docs-search-index.json` at build time to expose all 91 newly-populated endpoints to the LLM-fetch consumer + cmdK search palette.
- 2026-05-01 (v3.19.0): Phase 58 Plan 11 polish pass — re-authored `utility`, `params[].description`, and `responseSchema[].description` text across all 50 top-50 endpoints to meet Maroun's quality bar (per-Maroun review of Plan 58-07's content output). Each utility is now 2-4 sentences explaining the persona / financial problem / decision the endpoint enables (replacing the previous one-line summaries). Each param description now explains the lever, valid range/format, default behaviour, and edge cases (replacing the previous restated-field-name shorthand). Each responseSchema description now explains semantic meaning, null cases, units, and computation notes (replacing the previous one-line types). Tone matches Polygon.io / sec-api.io / IEX Cloud documentation depth. Endpoint coverage by group: Insiders 7, SEC Filings 8, Institutional Holdings 12, Ownership & Positions 5, Company Data 5, Bulk Data 3, Account 2, Webhooks 3, Reference Data 1, Resources 1, Home 1, Market Status 1, Daily Index 1. No backend behavior changes — documentation surface only.
- 2026-05-02 (v3.18.0): Phase 58 Plan 07 — top-50 customer-facing endpoints now ship full Polygon-grade documentation: `responseSchema` (4-19 typed field rows per endpoint with nullable + description), `sampleResponse` (hand-curated representative JSON), `longDescription` (2-4 paragraph prose with EndpointRef links to related endpoints), `related[]` (3-5 cross-section adjacency links), and `since` (introduction-version chip). Selection algorithm: deterministic HYBRID (all tier-10 + tier-25 unconditionally → section-coverage floor → tier-5/1 fillers) with 6 explicit Maroun swaps applied (drop 6 cost-0 placeholder reps, add 6 customer-facing tier-10 insider-module hot paths: /transactions/search, /transactions/top, /clusters, /screen, /recommendations/daily, /query). The remaining ~106 endpoints fall through to the Plan 58-08 fallback callout. No backend behavior changes — documentation surface only.
- 2026-05-01 (v3.17.1): Phase 65 PR2 — `/aggregation/by-sector.unique_insiders` semantics fix. The field previously returned `count(distinct(ReportingOwner.name_as_filed))`, which inflated on multi-entity joint filings (e.g. LGN's 9 Blackstone LP/GP/manager entities reporting one $514M trade became `unique_insiders=9` on the Industrials row). Now returns `count(distinct(_canonical_owner_id))` — one canonical owner per economic transaction, matching `/clusters.insider_count` semantics. Field name preserved; AI-chat consumers see corrected numbers without prompt changes. Empirical impact (per Phase 65 audit, last 45d): Industrials sells +222.8%, Technology sells +166.3%, Energy sells +111.6% over-counting eliminated. Other fields on this endpoint (buy_value/sell_value/net_value/transaction_count/filing_count/unique_issuers) were already deduped — only `unique_insiders` was broken.
- 2026-05-01 (v3.17.0): Phase 65 PR1 — opt-in `dedup_owners=true` query parameter on the 5 raw insider transaction endpoints (/transactions/latest, /transactions/by-ticker/{ticker}, /transactions/by-insider/{cik}, /transactions/search, /transactions/top). When true, the API collapses joint-filer rows (PE LP+GP+manager, 13D groups, SPAC sponsors) into one canonical row per economic transaction and surfaces a `co_owners` JSON array ([{name, cik, is_officer, is_director, is_ten_percent_owner}, ...]) plus a `co_owner_count` integer. Eliminates the +112-223% aggregate-flow inflation observed across Industrials/Technology/Energy sells over the last 45 days from joint Form 4 filings (e.g. LGN $514M × 9 owners = $4.6B reported; FANG $2.15B × 2 = $4.3B; RDW $231M × 8 = $1.85B). When false (default) or omitted, the response is byte-identical to pre-3.17.0 production — no new keys appear. Dedup partition: (issuer_cik, transaction_date, transaction_code, shares, price_per_share, COALESCE(shares_owned_following, 0), ownership_nature). Deterministic winner: lowest transaction_id. WebSocket payloads are unchanged. No commercial peer (sec-api.io, FMP, Intrinio, EODHD) offers server-side joint-filer dedup — finradar is now a strict superset.
- 2026-04-26 (v3.16.0): Token-based metering (Phase 56 — #commercialization): every billed `/v1/*` and `/api/insiders/*` endpoint now carries an explicit `cost` field (1 / 5 / 10 / 25 tokens per call) so customers can see the price of every API call in the docs page AND in the `/llms.txt` LLM-fetched reference. Exempt endpoints (auth, account self-serve, billing, payments, admin, sniper, user, webhooks, health) carry `cost: 0`. WebSocket endpoints follow a flat connection-day model (`cost: 100` tokens per connection-day, reconnects on the same UTC day are free). Free tier = 2,000 tokens/month; Paid tier = 200,000 tokens/month for $29/mo. Refilled on subscription anniversary; no rollover. Insufficient balance returns 402 with `current_balance` + `required_cost` + `next_refill_at` + `upgrade_url`. New customer self-serve endpoints (also exempt): GET /api/v1/account/balance (live balance + plan + days_until_refill), GET /api/v1/account/usage (30-day daily consumption + top-10 endpoints), GET /api/v1/account/transactions (signed-delta ledger), POST /api/v1/account/billing-portal (Stripe Customer Portal redirect URL). Customer dashboard at /account/usage.
- 2026-04-19 (v3.14.2): Ticker normalization (Phase 53, #247): All 17 ticker-accepting endpoints now coerce user input to canonical hyphen form (BRK.A, BRK/A, BRKA -> BRK-A). Canonical form matches SEC EDGAR company_tickers.json and the DB-layer norm_ticker_bi trigger invariant. Applies to /tickers/{ticker}/overview, /holders, /fund-trends, /cusip/ticker/{ticker}, /filings, /backfill/ticker, /financials/metrics, /ratios, /snapshot, /changes/{ticker}, /stock-overview, /tickers/logos/domain/{symbol}, /tickers/logos/domains, /insiders/transactions/by-ticker/{ticker}, /insiders/summary/by-ticker/{ticker}, /insiders/filings/by-ticker/{ticker}, /insiders/holdings/by-ticker/{ticker}. Backed by the Phase 49 ticker_norm_aliases table (~101 rows, seeded weekly from cf_ticker_lookup by the new ticker_autocomplete_weekly Airflow DAG). No breaking changes for well-formed inputs.
- 2026-04-16 (v3.14.1): Add 4 signal tables to SQL proxy whitelist (#253): all_stocks_signals_monthly, all_etfs_signals_daily, all_etfs_signals_weekly, all_etfs_signals_monthly. Create all_etfs_signals_monthly table in Postgres (matching ETF weekly schema + indexes). Enables migration of all signal pages from DO MySQL to PostgreSQL.
- 2026-04-14 (v3.14.0): Document 15 previously undocumented endpoints across 4 sections. Insider Module: GET /recommendations/daily (cluster-based buy/sell signals), GET /stats/global (market-wide insider activity), GET /filings/by-ticker/{ticker} (company filing history), GET /filings/{accession_number} (full filing detail), GET /insider/search (name/CIK search). CUSIP: GET /cik/{cik} (reverse CIK lookup), GET /cusip6/{cusip6} (issuer prefix lookup), GET /search (full-text search), GET /stats (mapping coverage). Ticker Research: GET /autocomplete (full ticker list), GET /logos/domain/{symbol} (company logo), GET /logos/domains (batch logo lookup). Bulk Data: GET /bulk/form-{type}/index.json (monthly file index), GET /bulk/form-{type}/{year}/{filename} (JSONL.gz download). Total endpoint count: 119 → 134.
- 2026-04-13 (v3.13.0): Add POST /api/v1/sql-proxy endpoint for WordPress SCC migration (#246). Executes read-only SELECT queries against whitelisted tables (all_stocks_strategies_yf_daily, all_stocks_list, all_stocks_signals_daily, all_stocks_signals_weekly, market_calendar, ai_daily_summaries). Auth via api_key in POST body/header. 30s timeout, 30 req/min rate limit. Extend /financials/stock-overview with 7 new columns: rsi, score, volume, pct_change, pct_from_high, above_200_sma, above_50_sma (#246).
- 2026-04-13 (v3.12.0): Materialize enrichment columns (close_price, market_cap, shares_outstanding, sector, industry, is_etf, first_traded, fund_flow_mcap_pct) into sec_13f_summary during reaggregation (#245). Raises /aggregation/by-ticker limit from 500 to 10000. 8k Stocks in <2s vs ~2min before. Add CUSIP to search filter (#244). Fix volume stats to respect security_group filter (#244). Make security_group enrichment failure hard-fail (#244).
- 2026-04-12 (v3.11.0): Replace security_type + is_etf/etf filters with unified security_group param on /aggregation/by-ticker (#241). Six groups: Stocks, ETFs, Preferred, Warrants, Debt, Other. Old params still work as deprecated aliases. Coverage restored from 7,968 to ~25,000 CUSIPs by removing equity-only whitelist.
- 2026-04-12 (v3.10.0): Add Operations / Airflow admin proxy endpoints: GET /admin/airflow/dags (DAG list + stats), GET /admin/airflow/dags/{id}/runs (run history), POST /admin/airflow/dags/{id}/trigger (manual trigger), GET /admin/airflow/health (health check), PATCH /admin/airflow/dags/{id}/toggle (pause/unpause). All admin-only. Enables pipeline monitoring and control from the FinRadar dashboard.
- 2026-04-11 (v3.9.0): 13F API math + consistency hotfix batch (#239). Bug 1: fund_count_prev now uses fair comparison (only counts funds that filed in BOTH quarters) — AAPL Q4 2025 fund_change_pct is now +11% instead of -98%. Bug 2: closed position fund_flow uses cross-fund weighted avg current price instead of up-to-7.5-month-stale prev quarter price. Bug 4: holdings query filters against new cusip_equity_filter lookup table (Sharadar equity whitelist), replacing the unreliable filer-reported security_type='equity' filter — bonds, warrants, convertibles, and preferred stock no longer leak through. Row count for Q4 2025 dropped from 25,060 to 7,968 after filtering. Rename /api/v1/form-13f/market/tickers → /api/v1/form-13f/aggregation/by-ticker (old path kept as deprecated alias). Rename response field float_shares → shares_outstanding (was a misleading proxy, not true float). Remove /api/v1/form-13f/market/summary endpoint (redundant with /aggregation/by-ticker). Remove fund_flow_pct column and response field (never used, misleadingly named — fund_flow_mcap_pct is the real metric). API consistency: sort/order params renamed to sort_by/sort_order with backward-compat aliases, etf param renamed to is_etf (boolean) with backward-compat alias.
- 2026-04-09 (v3.8.0): Add GET /api/v1/financials/stock-overview endpoint (#236): market data snapshot from all_stocks_strategies_yf_daily table (beta, close, sector, industry, market cap, enterprise value, float, short data). Unblocks DCF and Financials module migration from DO MySQL. Add nginx rate limiting for /api/v1/financials/ endpoints (#237): 30 req/min per IP with burst of 10, returns 429 when exceeded.
- 2026-04-07 (v3.7.3): Add missing filters to activists and threshold-crossings endpoints (#235): Activists now supports issuerTicker, filerName, and minOwnership filters. Threshold-crossings now supports issuerTicker, threshold (5/10/15/20), direction (up/down), and dateTo filters. Also adds crossed_15_percent to default threshold detection.
- 2026-04-04 (v3.7.2): XBRL Round 4 DO parity (#228): TTM sum now uses LAG(1/2/3) with ORDER BY period_end (crosses fiscal year boundaries like DO), TTM latest uses ROW_NUMBER with period_end DESC tiebreaker, averaged ratios (ROE/ROA/turnover) use deterministic fiscal_period ordering in LAG window, standardization removes filed_date tiebreaker to match DO exactly.
- 2026-04-04 (v3.7.1): Add automatic re-aggregation of latest quarter's sec_13f_summary every 6 hours via Celery beat (#229). Keeps /market/summary and /market/tickers fresh during filing season as new 13F filings arrive, without manual CLI runs. Also re-aggregates sector data.
- 2026-04-04 (v3.7.0): Add GET /api/v1/form-13f/market/tickers endpoint for grouped hedge fund analysis (#214). Returns all tickers for a given quarter with 31 sortable columns, 11 range filters (min/max), sector/industry/ETF category filters, and text search. Enriches 13F summary data with close price, market cap (close x shares_outstanding from XBRL), float (shares_outstanding proxy), first traded date, and ETF flag from Sharadar. Includes filter_ranges for frontend slider initialization, available_quarters for dropdown, and quarter_metadata for incomplete/complete distinction. Replaces DO backend for Grouped Hedge Funds page. Also adds ?quarter= param to GET /market/summary so incomplete filing-season quarters can be requested (#229).
- 2026-04-03 (v3.6.1): XBRL Round 3 parity fixes (#228): Fix cashflow Q2/Q3 duration filter — was accepting discrete (70-200/70-290 days) instead of cumulative-only (170-200/260-290 days), causing 169+ companies to have wrong quarterly cashflow (e.g. MSFT Q2 OCF was -$11.9B, now correct +$22.3B). Ticker resolution now goes through cf_ticker_lookup so alternate tickers like GOOGL resolve correctly. Year filter matches DO behavior (relative to current year). LAG window determinism fix for averaged ratios (ROE/ROA/turnover).
- 2026-04-02 (v3.6.0): XBRL critical data fixes (#228): Fix Q3 cashflow discretization (was off by +Q1 for every company), add period duration filter (root cause of AAPL mismatch), Q4 quarter guard (prevents FY duplication), TTM minimum 2-quarter count, turnover ratio positive denominator filter. API: /ratios accepts period=TTM, /snapshot accepts period=Q for latest quarter, tiered cash_runway_status (healthy/moderate/caution/critical), oldest-first sort order. Deterministic primary ticker scoring via _score_ticker(). 7 new performance indexes. concept_used audit trail for all calculated rows.
- 2026-04-01 (v3.5.0): XBRL DO-to-PG parity fixes (#224/#228): Add frame filter to prevent cross-year fact pollution, unit filter matching DO regex patterns, remove form_type restriction (recover 127K+ rows). Fix ROE/ROA/turnover to use averaged denominators, ROIC to match DO formula (0.75 fixed tax, subtract cash), cash runway restricted to TTM. New endpoints: GET /api/v1/financials/screen (stock screener with 20+ ratio filters), GET /api/v1/financials/changes/{ticker} (per-ticker change details), GET /api/v1/financials/status (pipeline health). Add cf_ticker_lookup table for alternate ticker resolution.
- 2026-03-31 (v3.4.0): Add Company Financials (XBRL) section: GET /api/v1/financials/metrics for standardized financial data (36 metrics), GET /api/v1/financials/ratios for 29 derived financial ratios with category filtering, GET /api/v1/financials/snapshot for TTM summary, GET /api/v1/financials/tickers for search, GET /api/v1/financials/changes for delta tracking. Data sourced from SEC EDGAR companyfacts bulk download (~7,000+ companies), updated daily.
- 2026-03-28 (v3.3.3): Add offset pagination to GET /tickers/{ticker}/holders (#216). New offset query param (default 0) and total_count/offset/limit in response. Enables paging through all holders including Closed positions that were previously cut off by the 500 limit.
- 2026-03-27 (v3.3.2): Add position change deltas to GET /ownership/beneficial-ownership/filings (#213): priorPercent, priorShares, percentChange, sharesChange, sharesChangePct, daysSincePriorFiling. Auto-links amendments after parse. Backfill Pass 3 covers all unlinked filings with priors (Fintel parity).
- 2026-03-27 (v3.3.1): Add 20-F form type support to GET /scrapping/extractor (#212). New form_type query parameter (default '10-K'). 14 item patterns for 20-F foreign private issuer filings (Items 1-12, 19). Enables extraction of 'Information on the Company' (Item 4), 'Operating and Financial Review' (Item 5), etc. for tickers like BABA, TSM, NVO, BTDR.
- 2026-03-26 (v3.3.0): Rewrite /tickers/{ticker}/holders and /tickers/{ticker}/fund-trends to query ALL 9,600+ 13F filers via form_13f_holdings (previously limited to 668 tracked funds). CUSIP successor chain expansion and amendment deduplication (latest filing per CIK+period). CIK normalization handles zero-padding inconsistency. Split-adjusted share counts preserved. Response shape unchanged — fully backwards compatible.
- 2026-03-26 (v3.2.0): 13D/13G sec-api.io full parity (#210): Fix 43K filings with corrupt issuer_cik='None' string (B1-B5). Add QoQ change fields to POST /form-13f/holdings via includeChanges param — returns changeShares, changePercent, status (New/Increased/Decreased/Unchanged/Closed), closedPositions array, previousPeriod (#209). BO API model changes: cusip as array, sourceOfFunds/typeOfReportingPerson as arrays, new fields nameOfIssuer, titleOfSecurities, eventDate, secFilingUrl, entities (SGML index metadata), groupMembers, entityType (entity/individual detection), per-filer footnotes, amountOfFunds, indirectOwnershipExplanation, sharesAcquirable60Days, legalProceedingsDisclosureRequired, amountExcludesCertainShares. Parser v11 with aggregateAmountExcludesCertainSharesFlag extraction.
- 2026-03-15 (v3.1.1): Fix insider cluster insider_count inflation: clusters now count unique transactions instead of distinct owner entities, preventing fund vehicles of the same beneficial owner from being counted as separate insiders. Affects /insider-module/api/insiders/clusters and daily recommendations.
- 2026-03-15 (v3.1.0): Add unified position tracking: event-sourced ledger with assertion-based position calculation, holder-issuer position history, issuer holder list, timeline, and cross-reference endpoints. Historical 13D/13G backfill pipeline via EDGAR EFTS. Parser v3 with 96% ticker resolution, fixed CIK disambiguation, and 80%+ ownership data extraction. Schema aligned with full Ralph spec (~70 new columns).
- 2026-03-15 (v3.0.0): Major 13D/13G beneficial ownership overhaul: Normalized multi-table schema (bo_filings, bo_filers, bo_positions, bo_purpose, bo_amendments, bo_groups, bo_exhibits). New GET /api/v1/ownership/* endpoints for filings, issuer summary, filer portfolio, activist tracker with purpose classification, conversions, groups, unified holders, filing history, ownership concentration, and threshold crossings. Rule-based NLP purpose classification with 13 categories and intent flags. Unified holder identity linking across Form 4, 13F, and 13D/G via CIK and name matching. Legacy POST /api/v1/form-13d endpoint preserved for backward compatibility.
- 2026-03-14 (v2.2.0): Add Form 13D/13G API: POST /api/v1/form-13d for querying parsed Schedule 13D/13G beneficial ownership filings. Supports filtering by ticker, issuer/filer CIK, filer name, ownership percentage, form type, and date range. Includes structured ownership data (percent of class, shares owned, voting power, purpose). Auto-triggers parsing for new 13D/13G filings from RSS feed. Admin backfill endpoints at /api/v1/admin/backfill/13dg/*.
- 2026-03-14 (v2.1.0): Add public System Status page and API: GET /api/v1/status (current health of all services with uptime %), GET /api/v1/status/history (time-bucketed uptime history for charts). Watchdog now persists health checks to DB. Add public Changelog page at /dev/changelog.
- 2026-03-11 (v2.0.0): v3.0 13F Analytics documentation complete. Fixed market/summary endpoint: added ?detail=basic|full query parameter and sampleResponse (gap from Phase 32). Added sampleResponse to by-sector endpoint (was missing despite having params). Audited all v3.0 endpoint docs (fund-performance, market-rotation, cross-filing-signals, filing-progress) -- all verified complete. Version bump to 2.0.0 marks v3.0 milestone completion.
- 2026-03-11 (v1.9.0): Added /filing-progress endpoint for quarter completeness tracking with recurring-filer baseline, deadline countdown, and AUM. Added quarter_metadata to market/summary, by-sector, fund-performance, market-rotation, and cross-filing-signals responses indicating whether the quarter's data is complete or still accumulating.
- 2026-03-11 (v1.8.0): Add market rotation signals (GET /api/v1/form-13f/market-rotation) for value/growth and cyclical/defensive sector rotation detection with QoQ comparison. Add cross-filing convergence signals (GET /api/v1/form-13f/cross-filing-signals) for smart money convergence detection where both insiders and institutions are buying, with investment attractiveness scoring.
- 2026-03-11 (v1.7.0): Add GET /api/v1/form-13f/fund-performance endpoint for VWAP-based quarterly fund performance ranking with leaderboard mode, single-fund detail mode, position-level return attribution, eligibility filtering, and sector concentration metrics.
- 2026-03-11 (v1.6.0): Add GET /api/v1/form-13f/aggregation/by-sector endpoint for sector/industry-level institutional fund flow analytics with momentum labels, flow significance metrics, top movers drill-down, and QoQ comparison support.
- 2026-03-08 (v1.5.0): v2.3 Sector & Industry Enrichment: Add sector and industry response fields to all insider transaction, holdings, cluster, and filing endpoints (Sharadar classification). Add sector and industry query parameters to 6 endpoints (transactions/latest, transactions/search, transactions/top, screen, clusters, filings/latest). New GET /aggregation/by-sector endpoint for sector/industry-level insider activity metrics with full filter support.
- 2026-03-05 (v1.4.0): Add total_beneficial_ownership field across all insider transaction, holdings, and profile endpoints. Aggregates shares_owned_following across all ownership vehicles (direct + indirect trusts/entities) per insider per company. Add 8 new insider endpoint docs: by-ticker, by-insider, search, query POST, insider detail, holdings by-ticker/by-insider/snapshot. Insider-centric endpoints (by-insider, insider detail) include ownership_summary with per-company vehicle breakdown. Fix holdings GROUP BY bug that silently dropped indirect holdings.
- 2026-02-23 (v1.3.3): Add Ticker Research section: GET /api/v1/tickers/{ticker}/overview (company financials), /holders (institutional holders with QoQ change), /fund-trends (historical quarterly fund ownership).
- 2026-02-23 (v1.3.2): Fix GET /api/v1/sec/filings sort order: default is now filed_date:desc (newest first). Add sort parameter supporting filed_date and updated_at fields with asc/desc direction. limit=1 now correctly returns the most recent filing.
- 2026-02-23 (v1.3.1): Add description field to GET /api/v1/sec/forms endpoint. Covers all 352 root SEC form types with human-readable descriptions. Amendment variants (/A) auto-append '(Amendment)'. Also documents q and limit query params.
- 2026-02-21 (v1.3.0): Add Market Status section: GET /api/market/status for real-time NYSE session state with countdown, holiday awareness, and next-event info. Public endpoint (no auth required).
- 2026-02-21 (v1.2.1): Add GET /billing/history and GET /billing/invoices endpoints for wallet transaction history and Stripe invoice retrieval.
- 2026-02-21 (v1.2.0): Add Billing & Subscription section: GET /billing/subscription, GET /plans/, POST /billing/quota, POST /payment/create-checkout-session. Stripe subscription webhooks for plan lifecycle management.
- 2026-02-18 (v1.1.0): Add 13F calendar timeline fields to /filing-stats: previousDeadline, lastCompleteQuarterEnd, beforeLastCompleteQuarterEnd, nextReportingPeriodStart, nextDeadline, daysUntilNextDeadline. Default period now shows last completed quarter when between filing seasons.
- 2026-02-18 (v1.0.1): Fix duplicate User Data section
- 2026-02-18 (v1.0.0): Initial LLM docs release with all endpoints

## 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.

---

## Token Pricing

Every billed endpoint costs 1, 5, 10, or 25 tokens per call. Free tier ships with 2,000 tokens/month. Paid tier ships with 200,000 tokens/month for $29/mo USD. Tokens refill on your subscription anniversary; balances do NOT roll over. Insufficient balance returns HTTP 402 with `current_balance`, `required_cost`, `next_refill_at`, `plan`, and `upgrade_url` so your client can prompt the user before the next call. Check your live balance at GET /api/v1/account/balance and manage your subscription via POST /api/v1/account/billing-portal (returns a Stripe Customer Portal redirect URL). WebSocket connections follow a flat connection-day model (100 tokens per UTC day connected, regardless of message volume). Exempt endpoints (auth, account self-serve, billing, payments, admin, sniper, user, webhooks, health) carry `cost: 0` and never debit the ledger.

### GET /api/v1/account/balance

Live token balance, plan, and days until next refill. EXEMPT — does not consume tokens. Accepts session JWT (browser dashboard) OR `X-API-Key` (server-side automation pre-flighting bursty workloads).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `current_balance` (integer): Tokens left in the current billing cycle. Always non-negative — when a billed call would push this below zero, the call returns 402 instead of debiting and the balance stays at the pre-call value. Refilled to `monthly_quota` on `billing_cycle_end`; balances do NOT roll over.
- `plan` (string): Plan tier — `free` (2,000 tokens/month, no credit card required) or `paid` ($29/mo, 200,000 tokens/month). Use to gate feature visibility client-side (e.g. show 'Upgrade for full Try-It' button on free plans only).
- `plan_display_name` (string): Human-readable plan name for UI display (e.g. `Free`, `Paid`). Casing follows brand guidelines — use this verbatim in dashboards rather than capitalizing the `plan` field client-side.
- `monthly_quota` (integer): Total tokens granted on each billing-cycle refill. `2000` for free; `200000` for paid. Display alongside `current_balance` for the customer-facing 'X / Y tokens used' progress bar.
- `billing_cycle_end` (string): ISO-8601 UTC timestamp of the next refill (subscription anniversary). At this exact moment the account's `current_balance` is reset to `monthly_quota` regardless of prior balance — there is NO rollover of unused tokens. For paid customers, also coincides with Stripe billing event.
- `days_until_refill` (integer): Whole days remaining until `billing_cycle_end` (rounded down). Useful for dashboard countdown chips ('29 days until refill'). When 0, the refill is happening within the next 24 hours.
- `suspended` (boolean): True when `current_balance == 0` AND the account has consumed all monthly tokens — subsequent billed calls return HTTP 402 with `current_balance`, `required_cost`, `next_refill_at`, `plan`, and `upgrade_url`. False otherwise (still has balance OR has been topped up via admin grant). Use to render 'Account suspended — upgrade now' banners.
- `as_of` (string): ISO-8601 UTC timestamp the balance snapshot was generated server-side. NOT cached — always reflects the live balance at request time, since stale balance display in the dashboard would be confusing during active token consumption.

**Since:** v3.16.0

**Utility:** Live customer-facing balance probe — the canonical 'how many tokens do I have left?' call. EXEMPT (`cost: 0`) so balance polling never debits the ledger; safe to call as aggressively as 1 Hz. Returns the current balance, plan tier (free / paid), monthly quota, days until next refill, and a `suspended` boolean that flips to `true` when balance hits zero (subsequent billed calls then return HTTP 402). Customer dashboards typically poll every 30 seconds for near-real-time display; server-side automation scripts should poll before bursty workloads to pre-flight the budget and avoid mid-batch 402s. For per-endpoint spend breakdowns use `/api/v1/account/usage`; for the full debit/credit ledger use `/api/v1/account/transactions`.

**Use case:** Customer dashboard polls this every 30 seconds for near-real-time balance display. Server-side scripts can also poll before bursty workloads to avoid 402s.

**Sample response:**
```json
{
  "current_balance": 198432,
  "plan": "paid",
  "plan_display_name": "Paid",
  "monthly_quota": 200000,
  "billing_cycle_end": "2026-05-26T08:39:00.000Z",
  "days_until_refill": 29,
  "suspended": false,
  "as_of": "2026-04-26T10:14:45.000Z"
}
```

### GET /api/v1/account/usage

Last-N-days daily token consumption + top-10 endpoints by spend. EXEMPT. Same auth model as `/balance` — accepts session JWT or `X-API-Key`.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `window_days` (integer): Echo of the requested `days` query parameter, AFTER clamping to [1, 90]. Use to confirm the server applied the expected window (e.g. caller passed `days=180` but server clamped to 90 — `window_days=90` confirms the truncation).
- `daily` (array): Per-day spend buckets, sorted by `day DESC` (most recent day first). Empty array on accounts with zero token activity in the window (free-tier accounts that signed up but never called a billed endpoint). Days with zero activity are ABSENT from the array — densify client-side if rendering a continuous bar chart.
- `daily[].day` (string): ISO-8601 date (YYYY-MM-DD) at UTC day boundary. Bucketing uses `date_trunc('day', created_at)` — a debit at 23:59:00 UTC and a debit at 00:01:00 UTC the next morning land in DIFFERENT buckets. Display in user's local timezone if the dashboard expects local-day semantics.
- `daily[].tokens_consumed` (integer): Total tokens debited on this day (positive integer; the underlying signed delta is negative on debits, but this field flips the sign for human-readable display). Always non-negative — refunds and grants do NOT subtract from this counter (they show up in `/api/v1/account/transactions` instead). For the live signed-delta ledger use `/api/v1/account/transactions`.
- `daily[].calls` (integer): Number of debit transactions (= billable API calls) recorded on this day. Use to compute average cost-per-call (`tokens_consumed / calls`) for a 'most expensive day' diagnostic. Calls with `cost: 0` (auth, account, billing, etc.) are EXEMPT and never appear here.
- `top_endpoints` (array): Top-10 endpoints by token spend over the window, sorted by `tokens DESC`. Empty array on accounts with zero billed activity. The leaderboard is computed live (no cache) so newly added endpoints surface within seconds of their first paid call.
- `top_endpoints[].endpoint` (string): Endpoint identifier in `METHOD /path` format (e.g. `GET /api/v1/sec/filings`, `POST /api/v1/form-13f/holdings`). Path-parameter values are normalized to placeholders so all calls to `/transactions/by-ticker/AAPL` and `/transactions/by-ticker/NVDA` aggregate into a single `/transactions/by-ticker/{ticker}` row.
- `top_endpoints[].tokens` (integer): Total tokens spent on this endpoint over the window (sign-flipped from the underlying signed delta — always non-negative). Use to drive the 'where did my tokens go?' donut chart on the dashboard.
- `top_endpoints[].calls` (integer): Number of times this endpoint was called over the window. Combined with `tokens` reveals the cost tier (`tokens / calls` ∈ {1, 5, 10, 25} for the four canonical tiers; WS connection-day rows show `tokens / calls = 100`).
- `as_of` (string): ISO-8601 UTC timestamp the usage snapshot was generated server-side. NOT cached — always reflects the live `token_transactions` state at request time.

**Since:** v3.16.0

**Utility:** Per-day usage histogram + top-10 endpoints by spend — drives the customer dashboard usage chart and 'where my tokens went' breakdown. EXEMPT (`cost: 0`) so dashboards can poll without quota concerns. Direct query against `token_transactions` (no rollup table in v1) — ~50ms p99 at 10K txns/day per the locked-in CONTEXT.md performance budget. The `daily[]` array is sorted by `day DESC` (most recent day first) and back-fills with `tokens_consumed: 0` only for days that had at least one transaction; gap-days are absent from the array (frontend should densify if a continuous bar chart is desired). The `top_endpoints[]` array is sorted by `tokens DESC` (highest spender first) and is capped at 10 entries server-side.

**Use case:** Customer dashboard renders a 30-day bar chart of daily spend + a top-10 leaderboard of which endpoints consumed the most tokens. Use to drive the 'usage trend' chip ('You burned 45,800 tokens this week, +12% vs last week').

**Parameters:**
- `days` (query, optional, default: 30): Window size in days (1-90; clamped at the bounds; non-numeric falls back to 30). 30 is the canonical dashboard default; 7 for compact widgets; 90 for quarterly review.

**Sample response:**
```json
{
  "window_days": 30,
  "daily": [
    {
      "day": "2026-05-02",
      "tokens_consumed": 1250,
      "calls": 248
    },
    {
      "day": "2026-05-01",
      "tokens_consumed": 980,
      "calls": 196
    },
    {
      "day": "2026-04-30",
      "tokens_consumed": 1420,
      "calls": 284
    }
  ],
  "top_endpoints": [
    {
      "endpoint": "GET /api/v1/sec/filings",
      "tokens": 8400,
      "calls": 1680
    },
    {
      "endpoint": "GET /api/insiders/transactions/latest",
      "tokens": 6200,
      "calls": 1240
    },
    {
      "endpoint": "POST /api/v1/form-13f/holdings",
      "tokens": 4500,
      "calls": 450
    }
  ],
  "as_of": "2026-05-02T15:51:00.000Z"
}
```

### GET /api/v1/account/transactions

Signed-delta ledger of recent token transactions (debits, refunds, refills, grants, manual adjustments). EXEMPT. Same auth model as `/balance` — accepts session JWT or `X-API-Key`. `delta < 0` is a debit, `delta > 0` is a credit. NOT to be confused with `/api/v1/billing/history` (Stripe charges + admin grants — different table, different sign convention).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `transactions` (array): Array of signed-delta transaction rows, sorted by `created_at DESC` (most recent first). Empty array on freshly-registered accounts that have neither been granted free-tier tokens (race window before `ensure_ledger_row` fires) nor called any billed endpoint. Cap of 200 rows enforced server-side.
- `transactions[].created_at` (string): ISO-8601 UTC timestamp the transaction was recorded. For debits this is the API call's request-completion time (within milliseconds of the response being sent); for `subscription_refill` events this is the Stripe webhook arrival time.
- `transactions[].delta` (integer): Signed token movement — NEGATIVE for debits (e.g. `-5` for a 5-token API call), POSITIVE for credits (`+200000` for a paid-plan refill, `+2000` for a free-tier signup grant, `+10` for an admin manual adjustment). Zero for status-only events (e.g. `subscription_cancelled`, `payment_failed`) where token balance does not move but the event must be recorded for audit. Sum across all rows in the current cycle = `current_balance - monthly_quota`.
- `transactions[].reason` (string): Transaction kind — one of `debit` (billed API call), `refund` (per-call refund, e.g. handler error), `subscription_refill` (monthly Stripe charge → token grant), `signup_grant` (free-tier 2,000-token initial grant), `manual_adjustment` (admin-applied credit/debit), `subscription_cancelled` / `payment_failed` (status-only, `delta=0`). Use to dispatch UI badges and audit-trail filters.
- `transactions[].endpoint` (string (nullable)): Endpoint identifier in `METHOD /path` format for `debit` and `refund` rows (e.g. `GET /api/v1/sec/filings`). Null for non-call events (`subscription_refill`, `signup_grant`, `manual_adjustment`, status-only events) — these are account-level movements unattached to a specific endpoint.
- `transactions[].metadata` (object (nullable)): JSONB blob with event-specific context. For `debit`/`refund`: `{request_id, cost_tier}` (correlate with server logs via `request_id`). For `subscription_refill`: `{stripe_invoice_id, plan}`. For `manual_adjustment`: `{admin_user_id, reason}`. For status-only events: `{stripe_event_id, error_code}`. Null when the row was inserted by an early-Phase-56 path that did not yet write metadata.
- `transactions[].response_status` (integer (nullable)): HTTP status code the handler returned for this request. Populated for `debit` rows from 2026-05-18 onward (issue #260). Null on `refund` / `subscription_refill` / `signup_grant` / `manual_adjustment` rows — those are bookkeeping movements, not responses to a specific API call. Null on `debit` rows that pre-date the migration (the column was just added; back-population was not attempted). After the 2026-05-18 batch-1 #254 change, any `debit` row with `response_status >= 400` is always paired with an immediate `refund` row (net-zero on the ledger), so this field is mainly an audit trail rather than a billing-correctness signal.
- `count` (integer): Number of transaction rows in the response (matches `transactions.length`). Bounded by the `limit` query parameter; smaller when the account has fewer transactions than requested.
- `as_of` (string): ISO-8601 UTC timestamp the snapshot was generated server-side. NOT cached — always reflects live state.

**Since:** v3.16.0

**Utility:** Per-call signed-delta audit trail — every token movement on the account, ordered by `created_at DESC` (most recent first). EXEMPT (`cost: 0`) so support workflows can fetch full history without debiting. The canonical answer to 'where did my tokens go?' — each row carries the endpoint that consumed (or refunded) the tokens plus a JSONB `metadata` blob with `request_id` for cross-correlation against server logs. Different from `/api/v1/billing/history` in two ways: this endpoint is a per-call ledger (every API call shows up), the other is a per-billing-event ledger (only Stripe charges + admin grants); this endpoint uses signed deltas (negative for debits), the other uses unsigned amounts in cents with a separate `transaction_type` enum.

**Use case:** Customer dashboard 'Recent transactions' card; support troubleshooting ('where did my tokens go on April 26?'); automated reconciliation scripts that need to verify a specific request_id was billed correctly.

**Parameters:**
- `limit` (query, optional, default: 50): Number of recent transactions to return (1-200; clamped at the bounds; non-numeric falls back to 50). 50 is the canonical dashboard default; 200 for export workflows; 20 for compact widgets.

**Sample response:**
```json
{
  "transactions": [
    {
      "created_at": "2026-05-02T15:50:12.000Z",
      "delta": -5,
      "reason": "debit",
      "endpoint": "GET /api/v1/sec/filings",
      "metadata": {
        "request_id": "req_3OqK2jK9L8pQ4xZ1",
        "cost_tier": 5
      },
      "response_status": 200
    },
    {
      "created_at": "2026-05-02T15:48:01.000Z",
      "delta": -1,
      "reason": "debit",
      "endpoint": "GET /api/v1/stats",
      "metadata": {
        "request_id": "req_3OqK2jK9L8pQ4xZ0",
        "cost_tier": 1
      },
      "response_status": 200
    },
    {
      "created_at": "2026-04-26T08:39:00.000Z",
      "delta": 200000,
      "reason": "subscription_refill",
      "endpoint": null,
      "metadata": {
        "stripe_invoice_id": "in_1Pz...",
        "plan": "paid"
      },
      "response_status": null
    }
  ],
  "count": 3,
  "as_of": "2026-05-02T15:51:00.000Z"
}
```

### POST /api/v1/account/billing-portal

Returns a Stripe Customer Portal session URL. The frontend MUST redirect the user to this URL via `window.location.href = response.url` (Stripe disallows iframe embedding via X-Frame-Options: DENY). Free users without a Stripe customer get a 400 with `error: no_stripe_customer`.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `url` (string): Stripe Customer Portal session URL. Short-lived (~1 hour TTL). REDIRECT the browser to this URL via `window.location.href = response.url` — DO NOT iframe-embed (Stripe sets `X-Frame-Options: DENY` on the portal response). After the user finishes (or closes the portal), Stripe redirects back to `${FRONTEND_URL}/account` per the server-configured `return_url`.

**Since:** v3.16.0

**Utility:** Single endpoint for self-serve subscription management — update card, view invoices, cancel subscription, change billing email. EXEMPT (`cost: 0`). Returns a short-lived Stripe-hosted Customer Portal session URL. The frontend MUST redirect (NOT iframe-embed) — Stripe disallows embedding via `X-Frame-Options: DENY` on the portal HTML response. Sessions expire ~1 hour after creation; if the user idle-bounces back, generate a new one. Customers without a Stripe customer record (free-tier users who never upgraded) get a 400 with `error: no_stripe_customer` — gate the 'Manage Billing' button by `plan === 'paid'` to avoid the dead-click.

**Use case:** Customer clicks 'Manage Billing' on the dashboard → frontend POSTs here → redirects to Stripe-hosted portal → returns to the app on close (Stripe's `return_url` brings them back to `/account`).

**Sample response:**
```json
{
  "url": "https://billing.stripe.com/p/session/test_YWNjdF8xUXBlV0VLRzQzS3JCbnJ1eA0HDJI"
}
```

---

## Authentication

Manage user sessions and credentials.

### POST /api/v1/auth/register

Register a new user account. EXEMPT (`cost: 0`). INVITE-ONLY during the soft-trial — body must include a valid `invite_token` from POST /api/v1/auth/redeem-invite.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `message` (string): Top-level result message. `Register user successful` on success (200). On error: `Email already exists` (400), `Invalid or expired invite token` (400), `Invite code is used and cannot be used` (410), or the underlying exception message (400). UI should toast on success and gate-form on error.
- `linkMsg` (string): Email-flow status message. Always `Please verify the email, I have send verification link.` on a clean 200. If verification email send failed (SMTP error), the endpoint returns 500 instead with a different message and the user is created but cannot log in until they trigger /auth/resend-verification.

**Since:** v1.0.0

**Utility:** Create a new user account during the invite-only soft-trial. EXEMPT (`cost: 0`) — auth endpoints never debit tokens. Phase 64 enforces invite-token gating: the body MUST include a short-lived `invite_token` JWT issued by `/api/v1/auth/redeem-invite`; the server re-validates the token against the `invite_codes` table on every register call (never trusts the JWT alone). On success the user is created with the FREE tier (2,000 tokens/month), an API key is generated, a verification email is sent, AND a welcome email with the API key + `curl` example is sent (separate try/except so SMTP failure does NOT 500 the response). The user CANNOT log in until they click the verification link in the email — `/auth/login` returns 400 if `verify_email=false`.

**Use case:** Frontend signup form: user enters email + password + redeemed invite code → POST here → backend creates the account, sends verification email, returns success message. User clicks verification link → email is verified → user can log in. Server-side onboarding scripts can also call this with a programmatically-redeemed invite token (see /auth/redeem-invite).

**Parameters:**
- `email` (body, required): User email address. Lowercased server-side. Must be unique across the `users` table — re-registration with an existing email returns 400 with `Email already exists`. Used as the canonical login identifier and the destination for the verification email.
- `password` (body, required): User password — minimum 8 characters (validated by `@validate_register`). Hashed via bcrypt server-side; never stored in plaintext, never returned in any response. Use a strong password manager-generated value in production; the example shown above is a redaction placeholder.
- `invite_token` (body, required): Short-lived JWT from POST /api/v1/auth/redeem-invite. Encodes the underlying `invite_codes.code` value; the server re-validates against the `invite_codes` table to confirm the code is still REDEEMABLE (not used, not expired, not revoked) before creating the account. Required during the Phase 64 invite-only soft-trial.

**Sample response:**
```json
{
  "message": "Register user successful",
  "linkMsg": "Please verify the email, I have send verification link."
}
```

### POST /api/v1/auth/login

Authenticate with email + password and receive a JWT access token. EXEMPT (`cost: 0`). Bad credentials return 401 with a single generic message (anti-enumeration). Per-account brute-force lockout: 5 / 10 / 20 consecutive failures trigger a 1-min / 5-min / 1-hour lockout respectively (HTTP 429 with `Retry-After` header).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `message` (string): Top-level result. `User login successfully.` on 200. On error: `Invalid email or password` (401, identical for unknown email AND wrong password — anti-enumeration); `Please verify the email, I have send verification link.` (400, when email is unverified — server side-effect: re-issues a verification email if the previous link expired); `Too many failed login attempts. Try again later.` (429, after 5/10/20 consecutive wrong-password attempts — response also carries a `Retry-After` header in seconds).
- `user` (object): Full user profile (same shape as GET /api/v1/user/ returns). Includes the user's `api_key` — surface in the dashboard 'API Keys' page so they can copy it for server-to-server calls. Includes embedded `Userplan` (subscription state) and `credit_balance` (Stripe-paid top-up balance, in USD).
- `user.uuid` (string): Stable user identifier (UUIDv4 string). Used as the JWT `sub` claim and as the foreign-key target in every per-user table (`user_token_ledger.user_id`, `token_transactions.user_id`, etc.). Treat as the canonical user PK for client-side state.
- `user.api_key` (string): API key for server-to-server calls (32-char concatenation of two UUIDs with hyphens removed). Pass as `X-API-Key: <api_key>` to billed endpoints. Distinct from the JWT `token` field — the API key has NO expiry and NO device limit, but DOES debit tokens; the JWT expires (default 1h), is bound to a session_id, but does NOT debit tokens (session cookies are exempt).
- `user.verify_email` (boolean): True if the user has clicked the verification email link. Always true in a successful login response (login is gated by this flag — unverified users get a 400 instead of a 200). Use to dispatch onboarding-state UI client-side.
- `user.credit_balance` (number): Stripe-paid top-up balance in USD (NOT in cents — server returns `float(credit_balance)`). Used by [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota) for buying additional API quota at 100 requests / $1. Distinct from `current_balance` in [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) — that's the token ledger; this is the dollars wallet.
- `user.Userplan` (object (nullable)): Embedded subscription state (relationship-included via `to_dict(include_relations=True)`). Null for accounts where the relationship row is missing (legacy edge case). Contains `total_limit_api`, `reach_limit_api`, `plan` (`free`/`weekly`/`monthly`/`pro`/`yearly`), `status`, `current_period_end`.
- `token` (string): JWT access token issued by `flask_jwt_extended.create_access_token`. Pass as `Authorization: Bearer <token>` on protected endpoints. Embeds the user's `uuid` as `sub` and a `session_id` claim used for device-limit eviction. Default expiry is the Flask app's `JWT_ACCESS_TOKEN_EXPIRES` (typically 1 hour). Re-issue by re-calling /auth/login (no separate refresh-token endpoint in v1).

**Since:** v1.0.0

**Utility:** Exchange email + password for a JWT access token (`flask_jwt_extended`-issued). EXEMPT (`cost: 0`). The returned token is a Bearer JWT — pass as `Authorization: Bearer <token>` to protected dashboard endpoints (NOT to API-key endpoints; those use the `X-API-Key` header from the user's `api_key` field). Each successful login appends a session_id to the user's `user_login_device` array and is bounded by `device_limit` (default 2 — third login evicts the oldest session). Email must be verified (`verify_email=true`) before login succeeds; otherwise 400 with a re-send-verification message. The user object returned in the body includes the API key — surface this in the dashboard 'API Keys' page so the user can copy it for server-to-server calls. **Lockout (issue #272):** five consecutive wrong-password attempts triggers a 60s lockout; tenth a 5-min lockout; twentieth a 1-hour lockout. During lockout every login returns HTTP 429 with a `Retry-After` header — even calls supplying the correct password (intentional, so an attacker can't fish for whether they've guessed right). A successful login resets the counters.

**Use case:** Frontend login form posts here → receives JWT + user object → stores JWT in cookie or localStorage → uses Bearer auth on protected endpoints (`/api/v1/account/*`, `/api/v1/user/*`, `/api/v1/billing/*`). Server-side automation should NOT call this; use the user's `api_key` directly instead (no expiry, no device limit, no brute-force lockout). On 429 the SPA should honour `Retry-After` and surface a 'Too many attempts, retry in N seconds' toast; do NOT auto-retry inside the lockout window.

**Parameters:**
- `email` (body, required): Registered email address. Lowercased server-side before lookup. Returns 401 `Invalid email or password` whether the email is unregistered or the password is wrong (anti-enumeration since the 2026-05-18 hardening pass).
- `password` (body, required): User password (6+ chars). Compared against the bcrypt hash stored in `users.password`. Returns 401 `Invalid email or password` on mismatch (same generic message as unknown-email so an attacker cannot distinguish the two). Never logged, never echoed in responses.

**Sample response:**
```json
{
  "message": "User login successfully.",
  "user": {
    "id": 42,
    "uuid": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
    "email": "user@example.com",
    "usertype": "user",
    "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "verify_email": true,
    "is_online": true,
    "has_uat_access": false,
    "billing_admin": false,
    "credit_balance": 0,
    "notify_email": true,
    "notify_browser": true,
    "webhook_url": null,
    "created_at": "2026-04-15T10:00:00.000Z",
    "updated_at": "2026-05-02T15:51:00.000Z",
    "Userplan": {
      "id": 42,
      "userId": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
      "total_limit_api": 100,
      "reach_limit_api": 12,
      "plan": "free",
      "status": "active",
      "current_period_end": null,
      "created_at": "2026-04-15T10:00:00.000Z",
      "updated_at": "2026-05-02T15:51:00.000Z"
    }
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZjE0..."
}
```

### POST /api/v1/auth/forgetpassword

Initiate the password-reset flow. Sends a one-time reset link to the registered email. EXEMPT (`cost: 0`). Token expires after 24 hours. Always returns 200 with a generic message regardless of whether the email is registered (anti-enumeration).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `message` (string): Generic status message. Always identical across the registered / unregistered / already-sent / SMTP-failed cases to prevent enumeration. UI should show a 'check your email' toast on every 200.

**Since:** v1.0.0

**Utility:** Send a password-reset email containing a one-time JWT token. EXEMPT (`cost: 0`). Tokens expire after 24 hours; if a previous unexpired token already exists for the user, the existing token is re-used (no duplicate email). The link in the email points at GET /api/v1/auth/verifyPasswordLink which 302-redirects to the FinRadar frontend's `/reset-password?token=…` page; the frontend then PUTs `{token, newpassword}` to /api/v1/auth/newpassword to finalize. The redirect target is server-controlled — there is no caller-supplied redirect-URL parameter (the previous `weblink` field was removed in the 2026-05-18 security hardening because it enabled an open-redirect that could exfiltrate the user UUID).

**Use case:** Frontend 'Forgot password?' form: user enters email → POST here → generic 'check your email' toast (always 200, never 400) → user checks email → clicks link → 302 to frontend `/reset-password?token=…` page → user enters new password → frontend PUTs to /api/v1/auth/newpassword to finalize.

**Parameters:**
- `email` (body, required): Email address. Lowercased server-side. The endpoint ALWAYS returns 200 with a generic message regardless of whether the email is registered — this is intentional and prevents account enumeration. Only a registered user actually receives an email.

**Sample response:**
```json
{
  "message": "If that email is registered, a password-reset link has been sent."
}
```

---

## User Data

Manage user profile and settings.

### GET /api/v1/user/

Get the authenticated user's profile, API key, and embedded subscription state. EXEMPT (`cost: 0`). JWT auth required.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `user` (object): Authenticated user profile (matches the `user` field in the /auth/login response). Built by `User.to_dict(include_relations=True)` — includes the three relationship rows (`Userplan`, `UserDocumentLimit`, `UserDeviceLimit`) inline.
- `user.uuid` (string): Stable user identifier (UUIDv4 string). Foreign-key target in every per-user table; treat as the canonical user PK.
- `user.email` (string): Lowercased registration email. Unique across `users`. Used as the login identifier.
- `user.usertype` (string): Role enum value — `user` (default) or `admin`. Use to gate admin-only UI surfaces. Distinct from `billing_admin` (a finer-grained flag for billing-operator dashboard access).
- `user.api_key` (string): API key for server-to-server billed calls (32-char concatenation of two UUIDs with hyphens removed). Pass as `X-API-Key: <api_key>` header on `/api/v1/sec/*`, `/api/insiders/*`, etc. Distinct from the JWT `token` (issued by /auth/login) — JWT is for browsing the dashboard, API key is for server-to-server calls.
- `user.verify_email` (boolean): True if the user has clicked the verification email link. Always true here — login is gated by this flag, so the JWT bearer must already be verified.
- `user.has_uat_access` (boolean): True if the user is allowed onto the UAT environment (separate cohort gate from the production access flag). Use to render UAT-environment banners or to gate UAT-only feature flags.
- `user.billing_admin` (boolean): Phase 56-02 RBAC flag — true if the user can access the billing-operator dashboard (`/admin/billing/*` routes). Distinct from `usertype === 'admin'` (which grants full admin access).
- `user.credit_balance` (number): Stripe-paid top-up balance in USD (not in cents). Used by [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota) for buying additional API quota at 100 requests / $1. NOT the same as the token balance (see [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) for that).
- `user.webhook_url` (string (nullable)): User-configured HTTPS URL for sniper-hit webhook callbacks. Null when the user has not configured one (most users). PUT /api/v1/user/ with `webhook_url` to update.
- `user.notify_email` (boolean): True if email notifications are enabled. Default true. Toggle via PUT /api/v1/user/.
- `user.notify_browser` (boolean): True if in-browser push notifications are enabled. Default true. Toggle via PUT /api/v1/user/.
- `user.created_at` (string): ISO-8601 UTC timestamp the user account was created (set by /auth/register).
- `user.updated_at` (string): ISO-8601 UTC timestamp the user row was last modified (`onupdate=datetime.utcnow`). Bumped on profile edits, login (last-seen), and admin role changes.
- `user.Userplan` (object (nullable)): Embedded subscription state — `total_limit_api` (monthly request quota), `reach_limit_api` (consumed this cycle), `plan` (`free`/`weekly`/`monthly`/`pro`/`yearly`), `status` (`active`/`canceled`/`past_due`), `current_period_end`. Null in legacy edge cases where the relationship row was never seeded; /auth/register seeds this for new users.
- `user.UserDocumentLimit` (object (nullable)): Embedded document-quota state for the (legacy) RAG document-upload feature — `total_limit_GB` and `reach_limit_GB`. Most users do not consume document quota.
- `user.UserDeviceLimit` (object (nullable)): Embedded device-limit state — `device_limit` (max concurrent JWT sessions, default 2) and `user_login_device` (JSON-serialized array of active session_ids). When a third login lands the oldest session_id is evicted from the array.

**Since:** v1.0.0

**Utility:** Authenticated 'who am I?' probe — returns full user profile plus embedded subscription (`Userplan`), document-quota (`UserDocumentLimit`), and device-limit (`UserDeviceLimit`) relationship rows. EXEMPT (`cost: 0`). Identical shape to the `user` field in the /auth/login response (both invoke `User.to_dict(include_relations=True)`). Use to bootstrap dashboard state on app load — the JWT cookie is presumed valid; if it expired the endpoint returns 401 and the SPA should redirect to /auth/login. Includes `api_key` (32-char) for the dashboard's 'API Keys' page; the user's `credit_balance` (USD top-up wallet, NOT tokens); subscription `plan` (`free` / `weekly` / `monthly` / `pro` / `yearly`); and notification preferences (`webhook_url`, `notify_email`, `notify_browser`).

**Use case:** Dashboard SPA bootstraps on load by calling this endpoint to populate user state. Server-side automation should never call this — use the user's `api_key` directly for billed endpoints, no profile fetch needed.

**Sample response:**
```json
{
  "user": {
    "id": 42,
    "uuid": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
    "email": "user@example.com",
    "usertype": "user",
    "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "verify_email": true,
    "is_online": true,
    "has_uat_access": false,
    "billing_admin": false,
    "credit_balance": 12.5,
    "notify_email": true,
    "notify_browser": true,
    "webhook_url": "https://your-app.example.com/webhooks/finradar",
    "created_at": "2026-04-15T10:00:00.000Z",
    "updated_at": "2026-05-02T15:51:00.000Z",
    "Userplan": {
      "id": 42,
      "userId": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
      "total_limit_api": 100,
      "reach_limit_api": 12,
      "plan": "free",
      "status": "active",
      "current_period_end": null,
      "created_at": "2026-04-15T10:00:00.000Z",
      "updated_at": "2026-05-02T15:51:00.000Z"
    },
    "UserDocumentLimit": {
      "id": 42,
      "userId": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
      "total_limit_GB": 5,
      "reach_limit_GB": "0.42",
      "created_at": "2026-04-15T10:00:00.000Z",
      "updated_at": "2026-05-02T15:51:00.000Z"
    },
    "UserDeviceLimit": {
      "id": 42,
      "userId": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
      "device_limit": 2,
      "user_login_device": "[\"sess-abc-123\",\"sess-def-456\"]",
      "created_at": "2026-04-15T10:00:00.000Z",
      "updated_at": "2026-05-02T15:51:00.000Z"
    }
  }
}
```

### PUT /api/v1/user/

Update the authenticated user's notification preferences (`webhook_url`, `notify_email`, `notify_browser`). EXEMPT (`cost: 0`). Other profile fields are immutable via this endpoint.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `message` (string): Top-level result. `Profile updated successfully` on 200. On error (400): the underlying exception message. On 404: `User not found` (defensive — JWT was valid but user was deleted between auth and now).
- `user` (object): Full updated user profile (same shape as GET /api/v1/user/'s `user` field). Reflects the post-update state of the three mutable fields plus the bumped `updated_at`. Use to patch SPA state without re-fetching.
- `user.webhook_url` (string (nullable)): Updated webhook URL. Null if the request body cleared it (passed empty string) or if the user had never set one and this PUT did not include `webhook_url`.
- `user.notify_email` (boolean): Updated email-notification preference. Reflects the body's `notify_email` if present; otherwise unchanged from the prior value.
- `user.notify_browser` (boolean): Updated in-browser push-notification preference. Same merge semantics as `notify_email`.
- `user.updated_at` (string): Bumped to the current UTC timestamp on every successful PUT (`onupdate=datetime.utcnow` on the User model).

**Since:** v1.0.0

**Utility:** Update the authenticated user's notification preferences. EXEMPT (`cost: 0`). Only three fields are mutable here: `webhook_url`, `notify_email`, `notify_browser` — all other user fields (email, password, api_key, role, plan) are immutable via this endpoint by design (the handler hard-codes the allowlist). To change email/password use the dedicated /auth/* flows; to change subscription tier use [POST /api/v1/payment/create-checkout-session](/docs/account/billing-and-subscription/post-payment-create-checkout-session). The endpoint returns the full updated user object (same shape as GET /api/v1/user/) so dashboards can patch local state from the response without re-fetching.

**Use case:** Dashboard 'Settings → Notifications' page submit handler: user toggles email/browser notifications + pastes their webhook URL → PUT here → backend persists + returns updated profile → SPA patches React state from the response.

**Parameters:**
- `webhook_url` (body, optional): HTTPS URL for POST callbacks when sniper targets fire. Pass an empty string to clear. Validated client-side as `^https://`; server stores as-is up to 512 chars. Webhook payload shape is documented at the Webhooks section.
- `notify_email` (body, optional): Boolean — true to enable email notifications, false to disable. Default true on signup. Affects sniper-hit emails, billing-event emails, and product-update emails.
- `notify_browser` (body, optional): Boolean — true to enable in-browser push notifications via the Web Push API, false to disable. Default true on signup. Browser must have granted notification permission separately for this to take effect.

**Sample response:**
```json
{
  "message": "Profile updated successfully",
  "user": {
    "id": 42,
    "uuid": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
    "email": "user@example.com",
    "usertype": "user",
    "api_key": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "verify_email": true,
    "is_online": true,
    "has_uat_access": false,
    "billing_admin": false,
    "credit_balance": 12.5,
    "notify_email": false,
    "notify_browser": true,
    "webhook_url": "https://your-app.example.com/webhooks/finradar",
    "created_at": "2026-04-15T10:00:00.000Z",
    "updated_at": "2026-05-02T15:51:00.000Z"
  }
}
```

---

## Webhooks

Automated server-to-server notifications.

### POST {your_webhook_url}

Payload sent when a Sniper Target is hit.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `event_type` (string): Discriminator field. For sniper webhooks: typically `sniper.filing_hit`. Receivers should switch on this field to route to the appropriate handler.
- `occurred_at` (string): ISO 8601 UTC timestamp of the underlying SEC event.
- `delivery_id` (string): Unique webhook-delivery identifier — use for idempotency-key on the receiver (in-flight retries reuse the same delivery_id).
- `target_id` (string (nullable)): Sniper target identifier (when event_type=sniper.*).
- `payload` (object): Event-specific payload. The fields below describe the `sniper.filing_hit` shape.
- `payload.ticker` (string): Canonical hyphen-form ticker the sniper was registered for.
- `payload.issuer_cik` (string): 10-character zero-padded SEC CIK of the filing issuer.
- `payload.accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Use to pull the full filing detail via [GET /api/v1/sec/filings/{accession_number}](/docs/sec-filings/main-api/get-sec-filings-accession-number).
- `payload.form_type` (string): SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `SC 13D`). Will match one of the `form_types` filter values from the original sniper-target creation.
- `payload.filed_at` (string): ISO 8601 UTC SEC filing-acceptance timestamp (the moment EDGAR accepted the filing).
- `payload.filing_url` (string): Direct URL to the filing on EDGAR — `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=...&filenum=...&accession_number=...`. Useful for opening the filing in a browser tab from a notification system.

**Since:** v1.0.0

**Utility:** DIRECTIONAL FLIP: this is NOT an endpoint FinRadar serves — it is a CONTRACT for events FinRadar will SEND to the customer's URL when a configured sniper target hits a matching SEC filing. The customer registers their receiving URL via [POST /api/v1/sniper/targets](/docs/sniper/sniper-module/post-sniper-targets) (`webhook_url` field) or as the account-level default via `/account/settings/webhooks`. FinRadar then makes an HTTP POST to that URL with the event payload documented below. The receiver MUST respond 200 within 10 seconds — non-200 / timeout / connection-error responses trigger up to 3 exponential-backoff retries (10s, 60s, 300s) before the event is dropped (with logged failure, surfaced in [GET /api/v1/account/usage](/docs/account/main-api/get-account-usage)). For high-availability event delivery, prefer the WS streaming endpoints ([/ws/main-api](/docs/main-api/main-api-stream/ws-main-api), [/ws/insider-api](/docs/insiders/insider-api-stream/ws-insider-api), [/ws/13f-live](/docs/13f/13f-live-stream/ws-13f-live)) — push delivery without the customer needing to operate a public-internet webhook receiver.

**Use case:** Automated trading bot execution: customer's sniper target on TSLA fires when a 10-Q lands at SEC EDGAR -> FinRadar POSTs the event payload to the customer's `https://customer.example.com/sniper-callback` -> customer's webhook-handler parses the payload, runs the trading-rule logic (e.g. 'if revenue beats consensus by >5%, place market buy'), and submits the order via their broker API. Also useful for ops dashboards / Slack alerts / CRM events / any 'when X happens, do Y server-side' workflow that needs SEC-filing event triggers.

**Parameters:**
- `event_type` (body, required): Event type discriminator — one of `sniper.filing_hit` (sniper target matched a filing), `sniper.window_expired` (sniper window ended without a hit; only sent when configured), `insider.transaction.created` (Form 4 push, requires WS subscription topic mapping), `13f.holdings.updated` (13F-HR processed; requires WS topic mapping). The bulk of webhook deliveries are `sniper.filing_hit`.
- `occurred_at` (body, required): ISO 8601 UTC timestamp of the underlying SEC event (filing acceptance for `sniper.filing_hit`, NOT the moment FinRadar dispatched the webhook). Use for chronological ordering on the receiver side.
- `delivery_id` (body, required): Unique webhook-delivery identifier — distinct from event_id. Used by FinRadar to track retries; receiver should idempotency-key on this value to dedupe retries (in-flight retries land with the same delivery_id but new HTTP POST).
- `target_id` (body, optional): Sniper target identifier when `event_type=sniper.*`. Echoed from the original [POST /api/v1/sniper/targets](/docs/sniper/sniper-module/post-sniper-targets) creation. Null on non-sniper event types.
- `payload` (body, required): Event-specific payload object. For `sniper.filing_hit`: `{ ticker, issuer_cik, accession_number, form_type, filed_at, filing_url }`. For other event types, see the per-type payload contract below.

**Sample response:**
```json
{
  "event_type": "sniper.filing_hit",
  "occurred_at": "2026-05-02T20:14:32Z",
  "delivery_id": "wd_3K8mPq2nQ4xZ1Y9b",
  "target_id": "tgt_abc123def456",
  "payload": {
    "ticker": "TSLA",
    "issuer_cik": "0001318605",
    "accession_number": "0001318605-26-000038",
    "form_type": "10-Q",
    "filed_at": "2026-05-02T20:14:32Z",
    "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0001318605&accession_number=0001318605-26-000038"
  }
}
```

---

## Main API

General platform statistics and reference data.

### GET /api/v1/stats

Get database and ingestion statistics.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `total_filings` (integer): Cumulative count of SEC filings successfully accepted and persisted to the `filings` table. Covers Forms 3/4/5, 13F-HR/NT, 13D/G, 8-K, 10-K/Q, S-1, 20-F, and ~340 other root form types. Increments roughly +5K/day off-season and +50K/day during 13F deadline windows.
- `total_insiders` (integer): Distinct count of Section 16 insider entities (officers, directors, 10%+ owners) in the `insiders` table. Typically ~85K-100K active insiders.
- `total_holdings_13f` (integer): Total row count in the `form_13f_holdings` table — every (filer, issuer, period) row across all 13F filings. Typical magnitude: ~300M-400M rows across the full historical window.
- `total_tickers` (integer): Distinct ticker count in the canonical catalog. Typical: ~26K post v3.11.0 catalog expansion (was ~7,968 prior).
- `total_endpoints_documented` (integer): Count of distinct endpoints documented in apiDocs.js — the value surfaced on the docs page as 'X endpoints documented'. v5.0 milestone target: 156+ endpoints.
- `last_filing_at` (string): ISO 8601 UTC timestamp of the most-recent successfully-ingested filing. Lag should be < 60s during ET market hours; values older than ~10 minutes outside the SEC's overnight quiet-window (10pm-6am ET) indicate an ingestion-pipeline alert.
- `last_13f_quarter` (string): Most-recent calendar quarter-end (`YYYY-MM-DD`) for which 13F-HR filings have been processed. Updated within ~1h of the SEC's 45-day-after-quarter-end filing deadline. Use to surface 'as of Q1 2026' on holdings drill-downs.
- `request_id` (string): Server-generated request identifier for distributed-tracing / support-ticket attribution.
- `timestamp` (string): ISO 8601 UTC timestamp of the response generation.

**Since:** v1.0.0

**Utility:** Lightweight platform-level metrics endpoint — total filings tracked, total endpoints documented, total tickers in the catalog, last-ingestion timestamp. EXEMPT (`cost: 0`). The cheapest 'is FinRadar alive AND has fresh data?' probe — pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for service-level health rollups and [GET /api/v1/facts](/docs/home/main-api/get-facts) for the per-form-type 90-day breakdown. Designed to be safe to poll at 60-second cadence from dashboard widgets without affecting plan budget.

**Use case:** Dashboard widget showing total platform metrics (X filings tracked across Y companies, last ingested Z minutes ago). Also useful as a marketing-page counter ('FinRadar tracks 2.4M+ SEC filings across 26K+ securities') and for client-side staleness detection ('last ingestion was 47 minutes ago — show a warning').

**Sample response:**
```json
{
  "total_filings": 2420187,
  "total_insiders": 92418,
  "total_holdings_13f": 348290612,
  "total_tickers": 26080,
  "total_endpoints_documented": 156,
  "last_filing_at": "2026-05-02T20:14:32Z",
  "last_13f_quarter": "2025-12-31",
  "request_id": "req_5pQ9LmN8K2vXwY3z",
  "timestamp": "2026-05-02T20:15:00Z"
}
```

### GET /api/v1/facts

Get system-wide facts.

**Token cost:** 10 tokens per call

**Response fields:**
- `total_filings` (integer): Cumulative count of SEC filings successfully accepted and persisted to the `filings` table since 2000 — covers Forms 3/4/5, 13F-HR/NT, 13D/G, 8-K, 10-K/Q, S-1, 20-F, and ~340 other root form types. Increments roughly +5K/day off-season and +50K/day during 13F deadline windows.
- `last_filing_at` (string): ISO-8601 UTC timestamp of the most recent successful filing acceptance (the moment the filing landed in our DB, NOT the filed_at on EDGAR which is timezone-loose). Lag should be < 60s during ET market hours; values older than ~10 minutes outside the SEC's overnight quiet-window (10pm-6am ET) are an ingestion-pipeline alert.
- `queue_depth` (integer): Live count of accepted-but-not-yet-parsed filings in the Celery `sec_13f` + `sec_filings` queues. Steady-state < 50; values 100-500 indicate filing-season pressure (normal at 10-Q peak); values > 1,000 indicate worker backlog and merit a sec_watchdog inspection.
- `by_form_type` (object): Map of form_type → count for the last 90 days (e.g. `{"4": 28432, "13F-HR": 9617}`). Only forms with non-zero activity in the window appear. Use this to confirm expected magnitudes per form type before kicking off heavy historical queries; sudden zeros on a form type usually indicate a parser regression rather than an SEC issuance pause.
- `as_of` (string): ISO-8601 UTC timestamp the snapshot was generated server-side (cached up to 60 seconds). Treat any consumer-side `now() - as_of > 90s` as stale-cache contention rather than a stale source — re-poll once before alerting.

**Since:** v1.0.0

**Utility:** A lightweight platform health probe that returns the cumulative SEC filing count, the most-recent acceptance timestamp, the live parsing-queue depth, and a per-form-type breakdown of the last 90 days. Operations teams and external status-board integrations use this as a 60-second-cached canonical reference for 'is FinRadar ingesting?' — pair it with `GET /api/v1/status` to also cover service-level health. The 90-day form-type histogram is the cheapest way to confirm Form 4 / 13F-HR / 8-K / 10-K throughput is at expected magnitudes before kicking off heavier per-filing queries.

**Use case:** Dashboard widgets showing total filings processed.

**Sample response:**
```json
{
  "total_filings": 2845129,
  "last_filing_at": "2026-05-01T20:54:12.000Z",
  "queue_depth": 14,
  "by_form_type": {
    "4": 28432,
    "13F-HR": 9617,
    "8-K": 16244,
    "10-K": 4112,
    "10-Q": 12055,
    "13D": 412,
    "13G": 1208
  },
  "as_of": "2026-05-01T20:55:00.000Z"
}
```

---

## SEC Filings API

Core access to 25+ years of SEC filings.

### GET /api/v1/sec/filings

List filings with pagination and filtering. When querying by ticker, if no local filings exist yet, the API automatically backfills the complete filing history from SEC EDGAR (first call may take a few seconds).

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — present on every endpoint that wraps via `ApiResponse.paginated()`. Use to assert the call succeeded before reading `data`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs to trace the exact request lifecycle (gateway routing, auth resolution, token debit, response).
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`). Use as the freshness marker — auto-backfill calls that take a few seconds will surface here as a measurable lag from your client-side `Date.now()`.
- `data` (array): Array of filing rows matching the query, sorted by `filed_date DESC` by default (newest first; configurable via `sort` param). Empty array when no rows match — never null. One element per filing — see `data[].*` for shape.
- `data[].id` (integer): Internal `sec_filing_entries.id` row ID (auto-increment primary key). Stable across calls but not portable across environments — always join via `accession_number` for cross-environment work.
- `data[].accession_number` (string): SEC accession number in the canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`). Globally unique across EDGAR; the natural primary key for any filing. Pass this to `GET /api/v1/sec/filings/{accession_number}` to retrieve metadata and document URLs.
- `data[].ticker` (string (nullable)): Resolved ticker from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals filing Form 4, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class (e.g. BRK-A for Berkshire Hathaway).
- `data[].form_type` (string): Canonical SEC form type as filed (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13F-NT`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Amendment variants append `/A` (e.g. `13D/A`, `10-K/A`). NT-prefixed and -NT-suffixed forms (`NT 10-K`, `13F-NT`) appear verbatim — these have no information table to drill into. Reference [SEC EDGAR form types](https://www.sec.gov/forms) for the full catalog.
- `data[].cik` (string (nullable)): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Note: SEC EDGAR's submissions API returns the unpadded form; FinRadar normalizes to 10-char padded form everywhere. Stable across decades — same CIK refers to the same legal entity.
- `data[].entity_name` (string (nullable)): Filer's legal entity name as registered with SEC (e.g. `Apple Inc.`, `BERKSHIRE HATHAWAY INC`). Casing is whatever EDGAR provides — typically uppercase for institutional filers, mixed-case for issuers. For display, prefer the `company_name` alias which is the same value.
- `data[].company_name` (string (nullable)): Frontend-friendly alias of `entity_name`. Same value, kept for backwards compatibility with older client code that queried `company_name`.
- `data[].role` (string (nullable)): Role of the filer in this filing — relevant for insider filings (Form 4) and institutional filings (13F). Null for issuer filings (10-K/10-Q/8-K). Common values: `Reporting Owner`, `Issuer`, `Filer`.
- `data[].title` (string): Free-text title from the EDGAR submissions feed (e.g. `8-K - APPLE INC (0000320193) (Filer)`). Useful for full-text search; for structured fields prefer `form_type` + `entity_name`.
- `data[].summary_html` (string (nullable)): Optional HTML summary block from EDGAR (typically empty on Form 4 and 8-K; populated on 13F-HR with structured holdings summary). Treat as untrusted HTML — sanitize before rendering in a browser.
- `data[].filing_size` (string (nullable)): Filing size as a human-readable string (e.g. `"245 KB"`, `"2.1 MB"`). NOT a numeric byte count — for byte-level work parse the string client-side or fetch the document directly.
- `data[].filed_date` (string (nullable)): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET (NOT UTC; matches the date EDGAR's index pages show). For intra-day ordering use `updated_at` which carries a full timestamp.
- `data[].filed_at` (string (nullable)): Frontend-friendly alias of `filed_date`. Same value, kept for backwards compatibility.
- `data[].updated_at` (string): ISO-8601 UTC timestamp of the last server-side update to this row (e.g. on a backfill refresh). Use as the cursor for incremental sync — sort `updated_at:desc` and persist the max value as your watermark.
- `data[].primary_link` (string (nullable)): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use this as the human-readable link in dashboards.
- `data[].primary_html_url` (string (nullable)): Direct URL of the filing's primary HTML document (the actual 10-K/8-K/13F body, not the index page). For programmatic access use this with `GET /api/v1/sec/document?url=...` or with `GET /api/v1/sec/filings/{accession_number}/html`.
- `data[].document_files` (array (nullable)): JSON array of structured document descriptors `[{type, document, description, size}, ...]` extracted from the filing's index page. Useful for filtering specific exhibits (e.g. EX-99.1, EX-10.1) before fetching.
- `data[].data_files` (array (nullable)): JSON array of XBRL/data file descriptors `[{type, document, description, size}, ...]`. Populated on 10-K/10-Q/8-K filings with embedded XBRL; null on filings without XBRL (e.g. older Form 4s).
- `data[].items` (array (nullable)): Array of 8-K item codes disclosed in this filing (e.g. `["2.02", "9.01"]` for an earnings-release 8-K). Null on non-8-K forms. Use for material-event surveillance — filter on specific item codes (1.01 = Material Definitive Agreement, 2.02 = Earnings, 5.02 = Officer Change, 8.01 = Other).
- `data[].period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end date for 10-K/10-Q, the trade date for Form 4, the report date for 13F-HR). Null for filings without a meaningful period (e.g. some 8-Ks). Differs from `filed_date` — `period_of_report` is the as-of date, `filed_date` is the disclosure date.
- `data[].sic` (string (nullable)): Standard Industrial Classification code (4-digit string, e.g. `3674` = Semiconductors). Null when not assigned. For richer industry categorization, join against the Sharadar SF1 industry table via the resolved ticker.
- `data[].all_links` (array (nullable)): Array of every document URL listed on the filing's index page — exhibits, XBRL data, images, the primary document. Pass any element to `GET /api/v1/sec/document?url=...` to fetch its content.
- `data[].first_seen_at` (string): ISO-8601 UTC timestamp when FinRadar first ingested this filing (typically within seconds of SEC acceptance for filings caught by the RSS poller; longer for backfilled rows). Use for ingest-latency analytics.
- `data[].last_seen_at` (string): ISO-8601 UTC timestamp of the last time the RSS poller observed this filing on EDGAR. Updated on every poll cycle for filings still in the active feed; frozen for older filings.
- `meta.pagination` (object): Offset-based pagination metadata: `{total, limit, offset, has_more}`. Use `has_more` as the canonical end-of-iteration signal rather than comparing `data.length` to `limit`.
- `meta.pagination.total` (integer): Exact total count of filings matching the query (full-table count, not just the current page). Computed via a parallel `COUNT(*)` query — reliable for UI pagers but adds ~50-200ms latency on broad queries.
- `meta.pagination.has_more` (boolean): `true` when more pages exist beyond this one (`total > offset + data.length`). Canonical end-of-iteration signal — when `false`, stop paginating.
- `meta.backfilled_from_edgar` (boolean (nullable)): Present and `true` ONLY when this call triggered an auto-backfill from SEC EDGAR (i.e. the ticker had no local data or only recent RSS-captured data). Absent on the typical hot-path call. Use to surface a UX hint ("first call took a moment to fetch full history").
- `meta.requested_ticker` (string (nullable)): Echo of the resolved ticker after Phase-53 normalization (e.g. `BRK.A` becomes `BRK-A`). Present only when the request included a `ticker` param.
- `meta.primary_ticker` (string (nullable)): Canonical primary share class for the filer (e.g. for Berkshire Hathaway, returns `BRK-A` even if the user queried `BRK.B`). Use to pivot to the multi-class top-of-book.
- `meta.cik` (string (nullable)): 10-char zero-padded CIK of the resolved ticker. Use as the join key against XBRL, 13F, or insider-filing tables.
- `meta.company` (string (nullable)): Resolved entity name for the ticker (e.g. `Apple Inc.`). Useful as a display label when the user queried by ticker rather than entity_name.

**Since:** v1.0.0

**Utility:** Canonical SEC filings list endpoint — paginated, ticker/CIK/form-type/date-range filterable, and self-healing (auto-backfills from SEC EDGAR's submissions API on first ticker query so you never see an empty result for a real issuer). Returns one row per filing with the SEC accession number, filer CIK + entity name + ticker, the form type (canonical strings: `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`, etc. — see [SEC EDGAR's form-type catalog](https://www.sec.gov/forms) for the full list), filing dates, and the document URL set (`primary_link`, `primary_html_url`, full `all_links` array). Pair this with `GET /api/v1/sec/filings/{accession_number}` to drill into a specific filing's documents, with `POST /api/v1/scrapping/search/` for full-text content search across filing bodies, or with `GET /api/v1/sec/filings/stats` for aggregate counts.

**Use case:** Building a timeline of filings for a specific company or monitoring all new 8-K filings. Example: GET /api/v1/sec/filings?ticker=XAIR&limit=500 returns all XAIR filings, auto-fetching from EDGAR if needed.

**Parameters:**
- `ticker` (query, optional): Company Ticker (e.g. AAPL). Triggers auto-backfill from SEC EDGAR if no local data exists.
- `form_type` (query, optional): Filter by Form Type (10-K, 4, 8-K)
- `from_date` (query, optional): Start Date (YYYY-MM-DD)
- `to_date` (query, optional): End Date (YYYY-MM-DD)
- `sort` (query, optional, default: filed_date:desc): Sort order. Format: field:direction. Fields: filed_date, updated_at. Directions: asc, desc. Shorthand 'asc'/'desc' also accepted (defaults to filed_date). Examples: sort=desc, sort=filed_date:asc
- `limit` (query, optional, default: 50): Max 500 records
- `offset` (query, optional, default: 0): Pagination offset

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": [
    {
      "id": 18234567,
      "accession_number": "0000320193-25-000123",
      "ticker": "AAPL",
      "form_type": "10-K",
      "cik": "0000320193",
      "entity_name": "Apple Inc.",
      "company_name": "Apple Inc.",
      "role": null,
      "title": "10-K - APPLE INC (0000320193) (Filer)",
      "summary_html": null,
      "filing_size": "12.4 MB",
      "filed_date": "2025-11-01",
      "filed_at": "2025-11-01",
      "updated_at": "2025-11-01T20:14:32.000Z",
      "primary_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K&dateb=&owner=include&count=40",
      "primary_html_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "document_files": [
        {
          "type": "10-K",
          "document": "aapl-20250928.htm",
          "description": "10-K",
          "size": "12943821"
        }
      ],
      "data_files": [
        {
          "type": "EX-101.INS",
          "document": "aapl-20250928.xml",
          "description": "XBRL Instance Document",
          "size": "412390"
        }
      ],
      "items": null,
      "period_of_report": "2025-09-28",
      "sic": "3571",
      "all_links": [
        "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
        "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml"
      ],
      "first_seen_at": "2025-11-01T20:14:35.000Z",
      "last_seen_at": "2025-11-02T03:00:01.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2148,
      "limit": 50,
      "offset": 0,
      "has_more": true
    },
    "requested_ticker": "AAPL",
    "primary_ticker": "AAPL",
    "cik": "0000320193",
    "company": "Apple Inc."
  }
}
```

### POST /api/v1/sec/filings/backfill

Explicitly backfill ALL historical filings for a ticker from SEC EDGAR. Fetches the complete filing history from data.sec.gov/submissions/ and stores it locally. Subsequent GET queries will return the full history instantly.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`).
- `data` (object): Backfill result envelope — see `data.*` for fields. Wall-clock duration scales with how many filings the issuer has — typically 2-15s for an issuer with 500-3000 historical filings; longer for very-tenured issuers (e.g. GE, IBM) which can have 10K+ filings.
- `data.ticker` (string): Echoed input ticker after Phase-53 normalization (e.g. `BRK.A` → `BRK-A`). Useful for confirming the resolution before relying on it downstream.
- `data.cik` (string): 10-char zero-padded CIK resolved from the input ticker. Use this as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.
- `data.company` (string): Resolved entity name (e.g. `Apple Inc.`). Useful as a display label for the backfilled batch.
- `data.inserted` (integer): Count of NEW filings inserted into the local index by this call (rows that didn't exist before). 0 on a no-op repeat call. Compare against `total_from_edgar` to gauge completeness.
- `data.already_existed` (integer): Count of EDGAR filings that were already in the local index (skipped via the `(accession_number, cik)` UNIQUE constraint). On a fresh-ticker backfill: 0. On a repeat call: equals `total_from_edgar`.
- `data.total_from_edgar` (integer): Total count of filings returned by SEC EDGAR's submissions API for this CIK. Equals `inserted + already_existed + errors`.
- `data.errors` (integer): Count of EDGAR rows that failed to ingest (parse errors, transient DB issues). Should typically be 0 — non-zero values indicate a parse-edge-case worth filing a support ticket for. Errors are logged server-side with the accession number.

**Since:** v1.0.0

**Utility:** Explicit, free (cost: 0) trigger to pre-load the FULL submissions history for a ticker from SEC EDGAR's `data.sec.gov/submissions/CIK{cik}.json` endpoint into FinRadar's local index. Use this to warm the cache before running an analysis batch — once a ticker has been backfilled, every subsequent call to `GET /api/v1/sec/filings?ticker=X` hits the local DB instantly (no SEC round-trip). Cost is zero because the work is one-shot per-ticker — repeated backfills detect the existing rows via the `(accession_number, cik)` UNIQUE constraint and only insert deltas. Idempotent: safe to call multiple times — `inserted` will be 0 on no-op repeat calls.

**Use case:** Call POST /filings/backfill?ticker=AAPL to load all ~2000 Apple filings in one shot, then query them instantly with GET /filings?ticker=AAPL.

**Parameters:**
- `ticker` (query, required): Stock ticker to backfill (e.g. XAIR, AAPL, TSLA)

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "ticker": "AAPL",
    "cik": "0000320193",
    "company": "Apple Inc.",
    "inserted": 1843,
    "already_existed": 0,
    "total_from_edgar": 1843,
    "errors": 0
  }
}
```

### GET /api/v1/sec/filings/{accession_number}

Get filing metadata by accession number — returns filing details, document URLs (all_links), and structured data. Does NOT return the document content itself.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side (suffix `Z`).
- `data` (object): Full filing metadata record. Same shape as a single element of `GET /api/v1/sec/filings`'s `data[]` array, PLUS the `raw_entry_xml` field (which is excluded from list responses for payload-size reasons). See `data.*` for fields.
- `data.id` (integer): Internal `sec_filing_entries.id` row ID (auto-increment primary key).
- `data.accession_number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. Echoes the input.
- `data.ticker` (string (nullable)): Resolved ticker from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker.
- `data.form_type` (string): Canonical SEC form type as filed (e.g. `10-K`, `13F-HR`, `8-K`, `4`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Amendment variants append `/A`. NT-prefixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim. Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `data.cik` (string (nullable)): Filer CIK as a zero-padded 10-character string (e.g. `0000320193`).
- `data.entity_name` (string (nullable)): Filer's legal entity name as registered with SEC.
- `data.company_name` (string (nullable)): Frontend-friendly alias of `entity_name`.
- `data.role` (string (nullable)): Role of the filer in this filing (`Reporting Owner`, `Issuer`, `Filer`). Null for issuer filings.
- `data.title` (string): Free-text title from the EDGAR submissions feed.
- `data.summary_html` (string (nullable)): Optional HTML summary block from EDGAR. Sanitize before rendering.
- `data.filing_size` (string (nullable)): Filing size as a human-readable string (e.g. `"245 KB"`, `"2.1 MB"`). NOT a numeric byte count.
- `data.filed_date` (string (nullable)): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET.
- `data.filed_at` (string (nullable)): Frontend-friendly alias of `filed_date`.
- `data.updated_at` (string): ISO-8601 UTC timestamp of the last server-side update to this row.
- `data.primary_link` (string (nullable)): Canonical SEC EDGAR URL for the filing's index page.
- `data.primary_html_url` (string (nullable)): Direct URL of the filing's primary HTML document (the actual 10-K/8-K/13F body). For the parsed body content use the `/html` companion endpoint.
- `data.document_files` (array (nullable)): JSON array of structured document descriptors `[{type, document, description, size}, ...]`.
- `data.data_files` (array (nullable)): JSON array of XBRL/data file descriptors `[{type, document, description, size}, ...]`. Populated on filings with embedded XBRL.
- `data.items` (array (nullable)): Array of 8-K item codes disclosed in this filing (e.g. `["2.02", "9.01"]`). Null on non-8-K forms.
- `data.period_of_report` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (fiscal-period-end for 10-K/10-Q, trade date for Form 4, report date for 13F-HR).
- `data.sic` (string (nullable)): Standard Industrial Classification code (4-digit string).
- `data.all_links` (array (nullable)): Array of every document URL listed on the filing's index page — exhibits, XBRL data, images, the primary document. Pass any element to `GET /api/v1/sec/document?url=...` to fetch its content.
- `data.raw_entry_xml` (string (nullable)): Raw XML entry from SEC EDGAR's RSS feed at the time of ingestion. Useful for forensic / audit-trail work — preserved verbatim from EDGAR for filings ingested via the RSS poller. Null for filings ingested via the submissions-API backfill path (which doesn't expose entry XML). NOT returned by the list endpoint — only the detail endpoint includes this field.
- `data.first_seen_at` (string): ISO-8601 UTC timestamp when FinRadar first ingested this filing.
- `data.last_seen_at` (string): ISO-8601 UTC timestamp of the last time the RSS poller observed this filing on EDGAR.

**Since:** v1.0.0

**Utility:** Canonical filing-detail lookup by SEC accession number — returns the full metadata record (form type, filer CIK + entity name, filed date, period of report, SIC, summary HTML, the complete `all_links` array of every document URL in the filing package, and the `raw_entry_xml` from EDGAR's RSS feed for archival/audit). The natural "step 1" of any filing workflow: find the filing by some other route (search, RSS, ticker timeline), then call this to get the document URLs, then drill into a specific document via `/{accession_number}/html` (primary doc shortcut) or `/api/v1/sec/document?url=...` (any document by URL). Accession numbers are 18-char dashed `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`); the path-parameter accepts either the dashed or the un-dashed form.

**Use case:** You have an accession number (e.g. from a search) and need the filing date, form type, filer info, and links to all documents in the filing package.

**Parameters:**
- `accession_number` (path, required): SEC accession number in 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`). Also accepts the un-dashed 18-char form (`000032019325000123`). Returns 404 when the accession is not in the local index — call `POST /api/v1/sec/filings/backfill?ticker=...` first if you suspect the ticker hasn't been backfilled yet.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "id": 18234567,
    "accession_number": "0000320193-25-000123",
    "ticker": "AAPL",
    "form_type": "10-K",
    "cik": "0000320193",
    "entity_name": "Apple Inc.",
    "company_name": "Apple Inc.",
    "role": null,
    "title": "10-K - APPLE INC (0000320193) (Filer)",
    "summary_html": null,
    "filing_size": "12.4 MB",
    "filed_date": "2025-11-01",
    "filed_at": "2025-11-01",
    "updated_at": "2025-11-01T20:14:32.000Z",
    "primary_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K",
    "primary_html_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
    "document_files": [
      {
        "type": "10-K",
        "document": "aapl-20250928.htm",
        "description": "10-K",
        "size": "12943821"
      }
    ],
    "data_files": [
      {
        "type": "EX-101.INS",
        "document": "aapl-20250928.xml",
        "description": "XBRL Instance Document",
        "size": "412390"
      }
    ],
    "items": null,
    "period_of_report": "2025-09-28",
    "sic": "3571",
    "all_links": [
      "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml"
    ],
    "raw_entry_xml": "<entry>\n  <title>10-K - APPLE INC...</title>\n  <link href=\"https://www.sec.gov/...\" />\n  ...\n</entry>",
    "first_seen_at": "2025-11-01T20:14:35.000Z",
    "last_seen_at": "2025-11-02T03:00:01.000Z"
  }
}
```

### GET /api/v1/sec/filings/{accession_number}/html

Get the primary document's HTML content by accession number. Returns the full raw HTML of the main filing document (e.g. the 10-K, 8-K body, or — for `13F-HR` / `13F-HR/A` — the INFORMATION TABLE with positions, not the cover page). For XBRL filings, automatically resolves through the SEC viewer to the actual inline XBRL document.

**Token cost:** 5 tokens per call

**Response fields:**
- `(body)` (string): Raw filing HTML — UTF-8 encoded `text/html` body. NOT a JSON envelope (this endpoint returns the document body directly). Server-side post-processing strips `<noscript>` blocks (the SEC "Javascript required" warning) and rewrites relative `href`/`src` URLs to absolute `https://www.sec.gov/...` — so the HTML can be rendered in a browser outside sec.gov without broken assets. Length ranges from 50 KB (Form 4) to 2 MB+ (large 10-K filings).
- `(headers).Content-Type` (string): Always `text/html`. Distinguishes this endpoint from JSON-returning siblings — your client must accept HTML responses, not assume JSON.

**Since:** v1.0.0

**Utility:** One-call shortcut to the filing's PRIMARY document body — the actual 10-K / 10-Q / 8-K / 13F-HR HTML, not the index page. Auto-resolves through SEC's `/ix?doc=` inline-XBRL viewer wrapper to the underlying tagged HTML so customers don't have to handle the redirect themselves. Critical for: feeding a 10-K straight into an LLM context window without scraping EDGAR yourself, rendering filings in an embedded iframe in your dashboard, building diff tools that compare 10-K filings year-over-year. Returns `Content-Type: text/html` — NOT a JSON response (one of the few non-JSON endpoints in the surface). Pair with [`GET /api/v1/sec/document?url=...`](/docs/sec-filings/sec-filings-api/get-sec-document) when you need a specific exhibit or data file rather than the primary doc.

**Use case:** Feed a 10-K annual report or 8-K directly into an LLM context window for summarization, without needing to scrape SEC EDGAR yourself.

**Parameters:**
- `accession_number` (path, required): SEC accession number in 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. Returns 404 with a JSON error body when the accession is not in the local index (or has no extractable HTML — e.g. some pre-2001 filings are TXT-only).
- `offset` (query, optional, default: 0): Byte offset (UTF-8) at which to start the returned slice. Combine with `length`/`max_bytes` to page through a large document instead of pulling it whole. Omit (with no `length`/`max_bytes`) to get the full document — the default, unchanged behaviour.
- `length` (query, optional): Max number of UTF-8 bytes to return starting at `offset`. Alias of `max_bytes` (if both are given the smaller wins). A raw 10-K can be tens of MB; agents should bound the response (e.g. 200000) and page via `offset` to avoid context/token blow-up. When the response is sliced, truncation is reported in the response HEADERS (`X-Content-Total-Bytes`, `X-Content-Offset`, `X-Content-Returned-Bytes`, `X-Content-Truncated`) — the body stays valid HTML.
- `max_bytes` (query, optional): Alias of `length` — max UTF-8 bytes to return from `offset`. Provided for clients that think in terms of a hard response-size cap.

**Sample response:**
```json
"<html>\n<head>\n  <title>Apple Inc. 10-K (Fiscal 2025)</title>\n</head>\n<body>\n  <h1>UNITED STATES SECURITIES AND EXCHANGE COMMISSION</h1>\n  <h2>FORM 10-K</h2>\n  <p>Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934</p>\n  <p>For the fiscal year ended September 28, 2025</p>\n  ...\n  <h2>PART I — Item 1. Business</h2>\n  <p>The Company designs, manufactures and markets smartphones, personal computers, tablets...</p>\n  ...\n</body>\n</html>"
```

### GET /api/v1/sec/document?url={sec_url}

Fetch any SEC EDGAR document by its full URL. Works with any file type — HTML exhibits, XML, XBRL, images, PDFs, etc. Use this when you need a specific document (not the primary one) from a filing's document list.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx in JSON-wrapped mode. ApiResponse envelope marker. NOT present when `raw=true` (raw mode returns the document body directly, no JSON envelope).
- `request_id` (string (nullable)): Per-request UUID generated server-side. JSON-wrapped mode only.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated. JSON-wrapped mode only.
- `data` (object): Document content envelope (JSON-wrapped mode only — see `data.*`). Absent in raw mode (`?raw=true`).
- `data.url` (string): Echoed (and `/ix?doc=`-stripped) URL of the document fetched. May differ from the input URL when SEC's viewer wrapper was present.
- `data.original_url` (string (nullable)): Original URL as passed by the caller, ONLY present when the server stripped a `/ix?doc=` wrapper. Null when no rewrite occurred.
- `data.content_type` (string): Detected MIME type based on URL extension: `text/html` (.htm, .html), `application/xml` (.xml, .xsd), `application/json` (.json), `text/plain` (.txt), `image/jpeg` / `image/png` / `image/gif` / `application/pdf` (binary types), `application/octet-stream` (unknown extensions). Use to dispatch the correct decoder client-side.
- `data.size` (integer): Decoded content size in bytes. For text content this is the UTF-8 byte length; for binary content this is the post-base64-decode byte length (the actual file size, not the inflated base64-string length).
- `data.encoding` (string): `utf-8` for text content (`text/*`, `application/xml`, `application/json`) — `data.content` is decoded text. `base64` for binary content (PDFs, images) — `data.content` is base64-encoded; decode client-side before consuming.
- `data.content` (string): Document content. UTF-8 plain text for text content types; base64-encoded string for binary types (decode via `Buffer.from(content, 'base64')` in Node, `atob(content)` in browsers, or `base64.b64decode(content)` in Python). HTML content is post-processed: `<noscript>` blocks stripped, relative `href`/`src` URLs rewritten to absolute `https://www.sec.gov/...` so embedded rendering works outside sec.gov.
- `(raw mode body)` (string): When `?raw=true`: the document body is returned directly with the original `Content-Type` header (no JSON envelope). For binary types (PDFs, images), the body is the raw bytes. For HTML, the body is the post-processed UTF-8 HTML. Use raw mode for `<iframe src=...>` or `<img src=...>` embedding patterns.

**Since:** v1.0.0

**Utility:** Universal SEC EDGAR document fetcher — pass any document URL from a filing's `all_links` array (HTML exhibits, XML data files, raw XBRL instances, images, PDFs, plain-text filings) and receive the content back in either a JSON envelope (default — base64 for binary, UTF-8 for text) or a raw passthrough (`?raw=true`, sets the original `Content-Type` for iframe/img embedding). The server-side guard rejects any URL whose hostname is not in `{www.sec.gov, sec.gov, efts.sec.gov, edgar.sec.gov}` — pass-through is gated to SEC domains only. Auto-strips SEC's `/ix?doc=` inline-XBRL viewer wrapper, so passing a URL copied directly from a browser's address bar (which often has `/ix?doc=` prepended) works without manual cleanup. HTML responses get the same `_fix_sec_html` post-processing as `/{accession_number}/html` (noscript stripped, relative URLs absolutized).

**Use case:** Chain: GET /filings/{accession} → pick a URL from all_links → GET /document?url={url}. Example: fetch an exhibit agreement or an XBRL data file from a 10-K filing package.

**Parameters:**
- `url` (query, required): Full SEC EDGAR document URL — must be on `sec.gov`, `www.sec.gov`, `efts.sec.gov`, or `edgar.sec.gov`. Returns 400 BAD_REQUEST when the hostname is anything else. Get these URLs from the `all_links` array in `GET /api/v1/sec/filings/{accession_number}`'s response. The `/ix?doc=` inline-XBRL viewer wrapper is auto-stripped — pass either form.
- `raw` (query, optional, default: false): If `true`, returns raw content with the original `Content-Type` header (for iframe rendering or direct binary download). If `false` or omitted, returns a JSON envelope with content in `data.content` (UTF-8 for text, base64 for binary). For LLM ingestion of HTML/XML use the default JSON mode; for `<iframe>` or `<img>` embedding use `raw=true`.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
    "original_url": null,
    "content_type": "text/html",
    "size": 12943821,
    "encoding": "utf-8",
    "content": "<html>\n<head><title>Apple Inc. Form 10-K</title></head>\n<body>\n<h1>UNITED STATES SECURITIES AND EXCHANGE COMMISSION</h1>\n<h2>FORM 10-K</h2>\n<p>Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934. For the fiscal year ended September 28, 2025.</p>\n<h2>PART I — Item 1. Business</h2>\n<p>The Company designs, manufactures and markets smartphones, personal computers, tablets, wearables and accessories...</p>\n..."
  }
}
```

### GET /api/v1/sec/forms

List all supported form types with descriptions. Each entry includes form_type, root_form_type, a human-readable description (covers all 352 root types), filing_count, first_filed, and last_filed. Amendment variants (/A) auto-append '(Amendment)' to the root type's description.

**Token cost:** 1 token per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (array): Array of form-type entries sorted by `filing_count DESC` (most-common forms first). Up to `limit` entries (default 500). One entry per distinct `form_type` — see `data[].*` for shape.
- `data[].form_type` (string): Canonical SEC form type as it appears in filings (e.g. `4`, `13F-HR`, `8-K`, `10-K`, `10-Q`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`, `13F-HR/A`). Amendment variants append `/A`. NT-prefixed forms (`NT 10-K`, `13F-NT`) appear verbatim.
- `data[].root_form_type` (string): Form type with the `/A` amendment suffix stripped (e.g. `13D/A` → `13D`, `10-K/A` → `10-K`). Useful for grouping amendments alongside their original-filing siblings (`SELECT * FROM forms WHERE root_form_type = '13D'`). For non-amendment forms, this equals `form_type`.
- `data[].description` (string): Human-readable description of the form's purpose (e.g. for `4` = "Statement of Changes in Beneficial Ownership", for `13F-HR` = "Information Required of Institutional Investment Managers Form 13F", for `S-1` = "Registration Statement under the Securities Act of 1933"). Covers all 352 SEC root form types. For amendments, the suffix " (Amendment)" is auto-appended.
- `data[].filing_count` (integer): Count of filings of this exact `form_type` in the local index. Reflects ingest coverage, not SEC's universe — recently-onboarded form types may show low counts here even though they're widely filed.
- `data[].first_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the EARLIEST filing of this type in the local index. Null when no filings have a `filed_date` (rare). Useful for spotting newly-introduced form types (e.g. `2026-` indicates a form added recently).
- `data[].last_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the MOST RECENT filing of this type in the local index. Null when no filings have a `filed_date`. Forms that haven't been filed in years (e.g. `last_filed: '2018-...'`) suggest deprecated form types — useful for hiding legacy types from active dropdowns.

**Since:** v1.0.0

**Utility:** Cheap (1 token) form-type catalog endpoint — returns every distinct form type observed in the local filings index alongside human-readable descriptions, filing counts, and the first/last dates each form type appears in the index. The single source of truth for: form-type dropdown menus in search UIs, tooltips that explain `13F-NT` vs `13F-HR`, autocomplete chips showing "how many of these have we seen" counts. Descriptions cover all 352 SEC root form types ([catalog](https://www.sec.gov/forms)) — amendment variants (`/A` suffix) auto-append "(Amendment)" to the description (e.g. `13D/A` description = "Statement of Beneficial Ownership (Amendment)"). Sorted by `filing_count DESC` so the most common forms (4, 13F-HR, 8-K, 10-K, 10-Q, S-1) surface first.

**Use case:** Populating a dropdown menu or table for 'Form Type' selection in a search UI, with descriptions so users understand each form type without looking it up.

**Parameters:**
- `q` (query, optional): Search form types by name — case-insensitive substring match against `form_type`. E.g. `q=13F` returns `13F-HR`, `13F-NT`, `13F-HR/A`. Use to narrow large lists; omit for full catalog.
- `limit` (query, optional, default: 500): Max results — clamped server-side to range `[1, 1000]`. Use 500 (default) for full catalog dropdowns; lower (10-20) for autocomplete-style hints.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": [
    {
      "form_type": "4",
      "root_form_type": "4",
      "description": "Statement of Changes in Beneficial Ownership",
      "filing_count": 8240194,
      "first_filed": "2002-08-29",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "13F-HR",
      "root_form_type": "13F-HR",
      "description": "Information Required of Institutional Investment Managers Form 13F",
      "filing_count": 384529,
      "first_filed": "2003-02-14",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "8-K",
      "root_form_type": "8-K",
      "description": "Current report",
      "filing_count": 1294831,
      "first_filed": "1996-03-15",
      "last_filed": "2026-05-02"
    },
    {
      "form_type": "10-K",
      "root_form_type": "10-K",
      "description": "Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934",
      "filing_count": 248194,
      "first_filed": "1993-08-30",
      "last_filed": "2026-05-01"
    }
  ]
}
```

### GET /api/v1/sec/entities

Return unique entity names, optionally filtered by filing form type. Results are alphabetically sorted and cached for 5 minutes.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. Note: this endpoint uses a custom `jsonify` envelope rather than `ApiResponse.success()` to control the `Cache-Control` header — so `request_id` and `timestamp` are NOT present (unlike sibling endpoints in this section).
- `data` (array): Array of distinct entity records, sorted alphabetically by `entity_name` (case-sensitive — uppercase names sort before lowercase per default Postgres collation). One entry per unique `(entity_name, cik)` pair. Empty array when no filings match the filter — never null.
- `data[].entity_name` (string): Filer's legal entity name as registered with SEC. Casing reflects EDGAR's stored form — typically uppercase for institutional filers (e.g. `BERKSHIRE HATHAWAY INC`, `BLACKROCK INC`), mixed-case for issuers (e.g. `Apple Inc.`, `Microsoft Corporation`). The same legal entity can appear with multiple cosmetic variants if EDGAR registrants update their formal name — dedupe client-side via `cik` if needed.
- `data[].cik` (string): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Stable across decades — same CIK refers to the same legal entity even if `entity_name` cosmetic variations exist. Use as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.

**Since:** v1.0.0

**Utility:** Distinct-entity catalog endpoint — returns every unique `(entity_name, cik)` pair observed in the local filings index, alphabetically sorted, optionally filtered by form type. The right surface for: form-type-aware autocomplete ("only show entities that have actually filed a 10-K"), notification-rule builders (user picks form type → entity search shows only relevant filers), entity-pivot navigation in the SEC workstation. Server-side `Cache-Control: public, max-age=300` (5 min cache) — entity list mutates slowly so caching is safe; expect a 5-minute lag for newly-onboarded filers. Returns a non-standard envelope (`{status, data}` only — NO `request_id` or `timestamp`) because the handler builds its own `jsonify` for cache-header control rather than going through `ApiResponse.success()`.

**Use case:** In notification settings, user selects a form type (e.g. 10-K), then a search bar appears where they can search for specific entities to watch. The autocomplete only shows entities that actually have filings of the selected form type. Also used in the SEC workstation for general entity search by company name.

**Parameters:**
- `form_type` (query, optional): Filter to entities with filings of this type (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). If omitted, returns all entities across all form types. Case-sensitive — pass exactly as it appears in `data[].form_type` from `GET /api/v1/sec/forms`.

**Sample response:**
```json
{
  "status": "success",
  "data": [
    {
      "entity_name": "ABBVIE INC.",
      "cik": "0001551152"
    },
    {
      "entity_name": "Apple Inc.",
      "cik": "0000320193"
    },
    {
      "entity_name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983"
    },
    {
      "entity_name": "BlackRock, Inc.",
      "cik": "0001364742"
    },
    {
      "entity_name": "Microsoft Corporation",
      "cik": "0000789019"
    }
  ]
}
```

### GET /api/v1/filings

Generic filings list — alias of /api/v1/sec/filings without the /sec prefix. Same query semantics; returns the same filings array.

**Token cost:** 10 tokens per call

**Response fields:**
- `filings` (array): Array of filing rows matching the query, sorted by `filed_date DESC` by default (newest first). Empty array when no rows match — never null. Pagination is cursor-based; consult `pagination.next_cursor` rather than `filings.length` to detect the last page.
- `filings[].accession_number` (string): SEC accession number in the canonical `XXXXXXXXXX-YY-NNNNNN` format (e.g. `0001127602-26-001234`). Globally unique across EDGAR; the natural primary key for any filing. Pass this to `GET /api/v1/sec/filings/{accession_number}` to retrieve metadata and document URLs.
- `filings[].cik` (string): Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Note: SEC EDGAR's submissions API returns the unpadded form; FinRadar normalizes to 10-char padded form everywhere except the URL path parameters that explicitly accept either.
- `filings[].ticker` (string (nullable)): Ticker symbol resolved from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs, dissolved entities). Primary-share-class is preferred when a filer has multiple tickers (e.g. BRK-A is returned for Berkshire Hathaway).
- `filings[].form_type` (string): Canonical SEC form type as filed (e.g. `4`, `13F-HR`, `8-K`, `10-K`, `10-Q`, `S-1`, `20-F`). Amendment variants append `/A` (e.g. `13D/A`). NT-prefixed and -NT-suffixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim — these have no information table to drill into.
- `filings[].filed_date` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET (NOT UTC; matches the date EDGAR's index pages show). For intra-day ordering use the parent filing's full timestamp via `GET /api/v1/sec/filings/{accession_number}`.
- `filings[].filing_url` (string): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use this as the human-readable link in dashboards; for programmatic document access use the `/html` or `/document` companion endpoints which return parsed content.
- `pagination` (object): Cursor-based pagination metadata. Cursor pagination (vs offset) is stable under concurrent inserts — no risk of skipping or double-counting filings as new ones land mid-iteration.
- `pagination.next_cursor` (string (nullable)): Opaque base64-encoded cursor for the next page. Pass this verbatim as the `cursor` query parameter on the next call. Null when there are no further pages — that is the canonical end-of-iteration signal.
- `pagination.total` (integer): Exact total count of filings matching the query (full-table count, not just the current page). Computed via a parallel `COUNT(*)` query — reliable for UI pagers but adds ~50-200ms latency on broad queries; pass `count=false` (when supported) to skip it for cursor-only iteration.

**Since:** v1.0.0

**Utility:** List EDGAR filings across all 350+ form types with pagination, ticker/CIK filtering, date ranges, and form-type filters — the canonical entry point for any analyst, screening pipeline, or dashboard that needs a chronological view of SEC filings. Identical query shape and cost to `/api/v1/sec/filings`; this path exists so legacy tooling that omits the `/sec/` namespace continues to work. Pair this with `GET /api/v1/sec/filings/{accession_number}` to drill into a specific filing's documents, or with `POST /api/v1/scrapping/search/` for full-text content search across filing bodies.

**Sample response:**
```json
{
  "filings": [
    {
      "accession_number": "0001127602-26-001234",
      "cik": "0000320193",
      "ticker": "AAPL",
      "form_type": "4",
      "filed_date": "2026-04-15",
      "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6...",
    "total": 12480
  }
}
```

### GET /api/v1/sec/filings/stats

Aggregate counts of filings by form type, filer, or date range. Returns counts only — does not return individual filings.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (object): Stats envelope — see `data.*` for fields. All counts reflect the local index, not SEC's universe (recently-onboarded form types may show low counts here even though they're widely filed).
- `data.total_entries` (integer): Total count of filings in the local `sec_filing_entries` index (all form types, all filers, all dates). Computed via `COUNT(*)` — typically 30M+ rows in the production index.
- `data.top_form_types` (array): Top 10 form types by `filing_count`, sorted descending. Always 10 elements (or fewer if the index has fewer distinct form types — extremely unlikely in production). Mirrors the top of `GET /api/v1/sec/forms`'s response.
- `data.top_form_types[].form_type` (string): Canonical SEC form type (e.g. `4`, `13F-HR`, `8-K`).
- `data.top_form_types[].count` (integer): Filing count for this form type. Typically dominated by Form 4 (insider transactions, ~8M+) and 13F-HR (institutional holdings, ~400K).
- `data.latest_filing_date` (string (nullable)): ISO date `YYYY-MM-DD` of the most recent filing in the local index (`MAX(filed_date)`). Use as the freshness canary — should never be more than 1-2 days behind today during active business hours; gaps suggest the RSS poller is stalled. Null only when the index is empty (initial setup).
- `data.timestamp` (string): ISO-8601 UTC timestamp the stats query ran server-side. Inside `data` rather than the envelope's `timestamp` — useful for stats-snapshot caching.

**Since:** v1.0.0

**Utility:** Aggregate-counts endpoint over the local filings index — total filing count, top-10 form types by count, latest filing date observed. The right surface for: dashboard headline stats ("X filings indexed; latest 2026-05-02"), monitoring panels checking ingest freshness (`latest_filing_date` should never be more than 1-2 days behind today during active hours), the "Did our RSS poller break?" canary. Returns aggregates only — no per-filing rows. For filtered counts (e.g. "how many 8-Ks did Apple file in 2025?") combine `GET /api/v1/sec/filings?ticker=...&form_type=...&from_date=...` with a `count`-only query against the `meta.pagination.total` field.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "total_entries": 32184529,
    "top_form_types": [
      {
        "form_type": "4",
        "count": 8240194
      },
      {
        "form_type": "13F-HR",
        "count": 384529
      },
      {
        "form_type": "8-K",
        "count": 1294831
      },
      {
        "form_type": "10-Q",
        "count": 412938
      },
      {
        "form_type": "10-K",
        "count": 248194
      },
      {
        "form_type": "S-1",
        "count": 184201
      },
      {
        "form_type": "DEF 14A",
        "count": 132481
      },
      {
        "form_type": "13D",
        "count": 98412
      },
      {
        "form_type": "13G",
        "count": 84592
      },
      {
        "form_type": "144",
        "count": 78201
      }
    ],
    "latest_filing_date": "2026-05-02",
    "timestamp": "2026-05-02T16:30:14.122000"
  }
}
```

### GET /api/v1/sec/forms/{form_type}

Get details for a specific SEC form type. Returns the form's metadata (description, filing count, first/last filed dates) — same shape as one element of GET /api/v1/sec/forms.

**Token cost:** 5 tokens per call

**Response fields:**
- `status` (string): Always `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
- `request_id` (string (nullable)): Per-request UUID generated server-side.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated server-side.
- `data` (object): Form-type detail record. Same shape as one element of `GET /api/v1/sec/forms`'s `data[]` array.
- `data.form_type` (string): Canonical form type as resolved (case-corrected from input — e.g. requesting `13f-hr` returns `13F-HR`). Echoes the canonical-cased form.
- `data.root_form_type` (string): Form type with `/A` amendment suffix stripped. For non-amendments, equals `form_type`.
- `data.description` (string): Human-readable description of the form's purpose (e.g. for `13F-HR` = "Information Required of Institutional Investment Managers Form 13F", for `10-K` = "Annual report pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934"). Covers all 352 SEC root form types. For amendments, suffixed with " (Amendment)". Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `data.filing_count` (integer): Count of filings of this exact `form_type` in the local index. Reflects ingest coverage, not SEC's universe.
- `data.first_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the EARLIEST filing of this type in the local index. Null only when no filings have a `filed_date` (rare).
- `data.last_filed` (string (nullable)): ISO date `YYYY-MM-DD` of the MOST RECENT filing of this type in the local index. Useful for deprecation detection — `last_filed` more than a year ago suggests the form may be retired.

**Since:** v1.0.0

**Utility:** Single-form-type detail lookup — pass a form type via the path (e.g. `/api/v1/sec/forms/13F-HR`) and receive its metadata: human-readable description, total filing count in the local index, first/last dates seen. Path-parameter variant of asking the catalog endpoint for a specific row. The right call for: form-type-specific landing pages ("All you need to know about Form 13F-HR"), tooltip enrichment when you have a form type but no description, deprecation detection (compare `last_filed` against current date — gaps > 1 year suggest the form has been retired). Two-stage CIK-insensitive lookup: tries exact-match `form_type` first, falls back to case-insensitive `ILIKE` if no rows match.

**Use case:** User clicks a form-type chip in the docs UI → land on a form-type page → pull description + filing count + date range to populate the page header.

**Parameters:**
- `form_type` (path, required): Canonical SEC form type (e.g. `10-K`, `13F-HR`, `8-K`, `4`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Case-insensitive — server tries exact match first, falls back to `ILIKE`. Amendment variants (`10-K/A`, `13D/A`) work — pass them verbatim. Returns 404 NOT_FOUND when no filings of this type exist in the local index.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
  "timestamp": "2026-05-02T16:30:14.122Z",
  "data": {
    "form_type": "13F-HR",
    "root_form_type": "13F-HR",
    "description": "Information Required of Institutional Investment Managers Form 13F",
    "filing_count": 384529,
    "first_filed": "2003-02-14",
    "last_filed": "2026-05-02"
  }
}
```

---

## 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
}
```

---

## CUSIP API

Resolve CUSIPs to Tickers and vice-versa.

### GET /api/v1/cusip/lookup/{cusip}

Resolve CUSIP to Ticker.

**Token cost:** 1 token per call

**Response fields:**
- `cusip` (string): Echoed 9-character CUSIP (post-normalization — leading whitespace stripped, padded to 9 chars if input was 8). Use for index-matching against the request input.
- `ticker` (string (nullable)): Resolved canonical ticker (hyphen form — `BRK-A` not `BRK.A`). Null when (a) the CUSIP exists in the catalog but has no associated ticker (debt securities, private placements, delisted issuers), or (b) the OpenFIGI enrichment fallback failed without a key (~24% of legacy CUSIPs without `OPENFIGI_API_KEY` set; with the key set this drops to <2%).
- `issuer_name` (string (nullable)): Issuer name from the canonical catalog (typically all-caps EDGAR convention for SEC-registered issuers — `APPLE INC` not `Apple Inc.`; varies for international issuers). Null when the CUSIP is unmapped.
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the issuer (e.g. `0000320193` for Apple). Null when the issuer has no SEC registration (rare; foreign-private issuers without ADR programs). Pair with `/api/v1/sec/filings?cik=...` for filing history.
- `cusip6` (string): First 6 characters of the CUSIP — the ISSUER PREFIX. A single legal issuer can have multiple 9-char CUSIPs across share classes / debt issues, all sharing the same `cusip6`. Useful for grouping multi-class issuers (e.g. BRK-A `084670108` and BRK-B `084670702` both share `cusip6=084670`).
- `security_group` (string (nullable)): Security classification — one of `Stocks` (common equity), `ETFs`, `Preferred`, `Warrants`, `Debt` (bonds, notes), `Other` (REITs, partnership units). Null when the catalog entry exists but security_group is not yet enriched.

**Since:** v1.0.0

**Utility:** Convert 9-digit CUSIPs (the universal SEC-filing security identifier) to canonical hyphen-form tickers — the single-row variant of the batch endpoint, optimised for the 'I have one CUSIP, what ticker is this?' workflow common in single-filing parsing pipelines. Backed by FinRadar's `cusip_security_catalog` (~26K rows post v3.11.0). When a CUSIP has been replaced by a corporate-action successor (SPAC merger, reorg, redomicile) this endpoint returns the CURRENT ticker — for the full historical chain use [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain).

**Use case:** Mapping 13F holdings data to actionable ticker symbols when you only have the CUSIP from a parsed filing row — e.g. SEC 13F-HR information table rows arrive with CUSIPs, but downstream alpha models speak ticker. Also useful in 'reverse-lookup' workflows: a customer asks 'what stock is CUSIP 037833100?' and you need the ticker + issuer name in one call.

**Parameters:**
- `cusip` (path, required): 9-character CUSIP. Whitespace and case are normalized server-side; 8-character CUSIPs (missing the trailing check digit) are zero-padded to 9. Returns 404 when the CUSIP is not in `cusip_security_catalog` — for stale or successor-replaced CUSIPs try `/cusip/chain/{cusip}` to chase corporate-action history. Real public-domain examples: `037833100` (Apple), `594918104` (Microsoft), `02079K305` (Alphabet Class A), `02079K107` (Alphabet Class C), `084670702` (Berkshire Class B).

**Sample response:**
```json
{
  "cusip": "037833100",
  "ticker": "AAPL",
  "issuer_name": "APPLE INC",
  "cik": "0000320193",
  "cusip6": "037833",
  "security_group": "Stocks"
}
```

### GET /api/v1/cusip/ticker/{ticker}

Resolve Ticker to CUSIP.

**Token cost:** 1 token per call

**Response fields:**
- `ticker` (string): Echoed canonical ticker (post-normalization to hyphen form). Use for index-matching against the request input.
- `cusip` (string): 9-character CUSIP for the CURRENT primary security mapped to this ticker. For a ticker like `RKLB` that has been through a SPAC merger, this is the CURRENT CUSIP only — append `?chain=true` to receive the full historical chain instead. For multi-class issuers, this is the most-liquid class only (BRK-A returns the A-class CUSIP, BRK-B returns the B-class CUSIP).
- `issuer_name` (string): Issuer name from the canonical catalog (all-caps EDGAR convention for SEC-registered issuers — `APPLE INC`).
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the issuer (e.g. `0000320193`). Null when the issuer has no SEC registration.
- `cusip6` (string): 6-character CUSIP issuer prefix. Multi-class issuers share a CUSIP6 (BRK-A `084670108` and BRK-B `084670702` both share `084670`). Use to group across share classes.

**Since:** v1.0.0

**Utility:** Reverse direction of [GET /api/v1/cusip/lookup/{cusip}](/docs/reference-data/cusip-api/get-cusip-lookup) — given a ticker, return the CUSIP. Useful when you need to bridge ticker-shaped customer input into CUSIP-shaped 13F query parameters (e.g. `POST /form-13f/holdings` accepts CUSIPs but a UI may want to expose ticker search). Backed by `cusip_security_catalog`. Returns the CURRENT active CUSIP only — to retrieve historical CUSIPs across corporate actions append `?chain=true` (see [/cusip/ticker/{ticker}?chain=true](/docs/reference-data/cusip-api/get-cusip-ticker-chain)).

**Use case:** Preparing data for institutional reporting or regulatory filings — converting customer-facing tickers (e.g. `AAPL`) into the CUSIP form (e.g. `037833100`) required by 13F holdings queries, regulatory submissions, and CUSIP6-grouped multi-class drill-downs. Also useful in 'enrich a watchlist of tickers with CUSIPs for batch 13F lookup' flows.

**Parameters:**
- `ticker` (path, required): Canonical hyphen-form ticker (`BRK-A` not `BRK.A`). Server-side normalization applies the v3.14.2 ticker-coercion shim — `BRK.A`, `BRK/A`, `BRKA` all coerce to `BRK-A`. Returns 404 when no active CUSIP mapping exists (delisted issuers, foreign tickers without OpenFIGI coverage).

**Sample response:**
```json
{
  "ticker": "AAPL",
  "cusip": "037833100",
  "issuer_name": "APPLE INC",
  "cik": "0000320193",
  "cusip6": "037833"
}
```

### POST /api/v1/cusip/batch

Batch CUSIP resolution.

**Token cost:** 5 tokens per call

**Response fields:**
- `results` (array): One row per requested CUSIP, in INPUT ORDER (not sorted) — so client code can safely zip the response array back against the request array. Unmapped CUSIPs still produce a row (with null `ticker` / `issuer_name` / `security_group`) so output length always matches input length.
- `results[].cusip` (string): Echoed 9-character CUSIP (post-normalization — leading whitespace stripped, padded to 9 chars if input was 8). Use for index-matching against the input array when needed.
- `results[].ticker` (string (nullable)): Resolved canonical ticker (hyphen form). Null when (a) the CUSIP is not in our `cusip_security_catalog` (~3% of legacy 13F filings), (b) the security has no ticker (debt, private placements), or (c) the issuer was delisted before our enrichment ran. For chain-aware multi-CUSIP-per-ticker tracking use `/cusip/chain/{cusip}`.
- `results[].issuer_name` (string (nullable)): Issuer name from the canonical catalog (typically all-caps EDGAR convention for SEC-registered issuers; varies for international issuers). Null when the CUSIP is unmapped. Use for human-readable rendering rather than the raw `cusip` itself.
- `results[].security_group` (string (nullable)): Security classification — one of `Stocks` (common equity), `ETFs` (exchange-traded funds), `Preferred` (preferred stock), `Warrants`, `Debt` (bonds, notes), `Other` (REITs, partnership units, etc.). Null when the catalog entry exists but security_group is not yet enriched. Filter 13F holdings to `Stocks` only for clean common-equity flow analysis.
- `results[].cusip6` (string): First 6 characters of the CUSIP — the ISSUER PREFIX (a single legal issuer can have multiple 9-char CUSIPs across share classes / debt issues, all sharing the same `cusip6`). Useful for grouping multi-class issuers. Always present even when the full 9-char CUSIP is unmapped.
- `meta` (object): Resolution-rate metadata: `{ requested: integer, resolved: integer, unmapped: integer }`. `resolved + unmapped == requested`. A high `unmapped` count (>10%) suggests the input batch contains stale/legacy CUSIPs — try with chain-expansion via `/cusip/chain/{cusip}` per-row to chase corporate-action successors.

**Since:** v1.0.0

**Utility:** Bulk CUSIP→ticker resolution — pass up to 1,000 CUSIPs in one request and receive ticker, issuer name, security group classification, and CUSIP6 (issuer prefix) for each. The hot-path enrichment endpoint for 13F holdings normalization workflows: 13F filings deliver positions as 9-character CUSIPs, but downstream analytics need tickers. Backed by FinRadar's `cusip_security_catalog` (~26K rows post-v3.11.0 expansion). Returns 6 security-group buckets: Stocks, ETFs, Preferred, Warrants, Debt, Other — useful for filtering 13F books to common-stock-only views without per-row decisions. Single-CUSIP variants (`/cusip/lookup/{cusip}`) exist but cost more per row at scale; this batch endpoint is the right choice for any multi-CUSIP workflow.

**Use case:** Resolving all holdings in a large portfolio in a single request.

**Parameters:**
- `cusips` (body, required): Array of 9-character CUSIP strings (max 1,000 per request — server returns 400 above the cap; for larger universes split into multiple batches client-side). 8-char CUSIPs (missing check digit) are zero-padded server-side. Whitespace and case are normalized. Order is preserved in the response so client code can zip results back to inputs.

**Sample response:**
```json
{
  "results": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "issuer_name": "APPLE INC",
      "security_group": "Stocks",
      "cusip6": "037833"
    },
    {
      "cusip": "02079K305",
      "ticker": "GOOGL",
      "issuer_name": "ALPHABET INC",
      "security_group": "Stocks",
      "cusip6": "02079K"
    }
  ],
  "meta": {
    "requested": 2,
    "resolved": 2,
    "unmapped": 0
  }
}
```

### GET /api/v1/cusip/chain/{cusip}

Get full CUSIP successor chain for a security (corporate actions tracking).

**Token cost:** 5 tokens per call

**Response fields:**
- `cusip` (string): Echoed input CUSIP — the seed for the chain walk.
- `chain` (array): Array of chain entries in CHRONOLOGICAL order (oldest CUSIP first, current CUSIP last). The last entry's `cusip` is the CURRENT active CUSIP for the security.
- `chain[].cusip` (string): 9-character CUSIP at this point in the chain.
- `chain[].issuer_name` (string): Issuer name AT THE TIME this CUSIP was active — preserves the historical-issuer-identity view (e.g. `VECTOR ACQUISITION CORP` for the pre-SPAC RKLB CUSIP, `ROCKET LAB USA INC` for the post-SPAC CUSIP, `ROCKET LAB CORP` for the post-redomicile CUSIP).
- `chain[].effective_date` (string (nullable)): ISO-8601 date this CUSIP became active. Null on the seed CUSIP (catalog-origin date is not always known; the chain only tracks the TRANSITION dates between CUSIPs, not the initial issuance).
- `chain[].reason` (string (nullable)): Corporate-action reason that triggered the CUSIP transition — one of `SPAC merger`, `Reorg`, `Redomicile`, `Acquisition`, `Spin-off`, `Reverse merger`, `Symbol change`. Null on the seed (initial-issuance) entry.
- `chain[].is_current` (boolean): `true` for exactly one entry — the CURRENT active CUSIP. `false` for all historical predecessors.
- `current_ticker` (string (nullable)): Convenience field — the canonical ticker for the CURRENT CUSIP (last chain entry). Null when the security is delisted or has no public-equity ticker.

**Since:** v1.0.0

**Utility:** Returns the complete chain of CUSIPs for a security that has undergone corporate actions (SPAC mergers, holding company reorgs, redomiciliations). Shows the progression from original -> intermediate -> current CUSIP with effective dates, reasons, and the current ticker. The single canonical answer to 'show me every CUSIP that has ever represented this security' — Phase 11 (initial chain table) + Phase 47 (unified-holder layer chain expansion) work product. Without chain awareness, ownership data appears to show 3 different securities instead of 1 (and 13F-derived position-history charts get clipped at every CUSIP transition).

**Use case:** Tracking Rocket Lab (RKLB) through its SPAC merger: `G9442R126` (Vector Acquisition Corp pre-SPAC) -> `773122106` (Rocket Lab USA post-SPAC) -> `773121108` (Rocket Lab Corporation post-redomicile). Without chain awareness, the position-history chart for RKLB clips at each CUSIP transition. With chain awareness, the underlying 13F holdings query expands to all 3 CUSIPs and the timeline is continuous. Also useful for any holdings-aggregation workflow that needs to roll up legacy CUSIPs (DLTR pre-Family-Dollar-merger, AVGO pre-VMware-acquisition, etc.).

**Parameters:**
- `cusip` (path, required): Any CUSIP in the chain (old or current). The endpoint walks the chain in BOTH directions from the input — pre-mergers AND post-mergers — to return the complete history. Examples: `G9442R126` (pre-SPAC RKLB) returns the same chain as `773121108` (current RKLB).

**Sample response:**
```json
{
  "cusip": "773121108",
  "chain": [
    {
      "cusip": "G9442R126",
      "issuer_name": "VECTOR ACQUISITION CORP",
      "effective_date": null,
      "reason": null,
      "is_current": false
    },
    {
      "cusip": "773122106",
      "issuer_name": "ROCKET LAB USA INC",
      "effective_date": "2021-08-25",
      "reason": "SPAC merger",
      "is_current": false
    },
    {
      "cusip": "773121108",
      "issuer_name": "ROCKET LAB CORPORATION",
      "effective_date": "2025-11-01",
      "reason": "Redomicile",
      "is_current": true
    }
  ],
  "current_ticker": "RKLB"
}
```

### GET /api/v1/cusip/ticker/{ticker}?chain=true

Resolve Ticker to CUSIP with full successor chain.

**Token cost:** 1 token per call

**Response fields:**
- `ticker` (string): Echoed canonical ticker (post-normalization to hyphen form).
- `cusip` (string): 9-character CUSIP for the CURRENT primary security mapped to this ticker. Same field as the no-chain variant; present even when `chain=true`.
- `issuer_name` (string): Issuer name of the CURRENT security (all-caps EDGAR convention).
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the CURRENT issuer.
- `cusip6` (string): 6-character CUSIP issuer prefix of the CURRENT CUSIP. NOTE: CUSIP6 changes across reorgs — do NOT use as a stable issuer identifier.
- `chain` (array (nullable)): Array of historical CUSIPs sharing this security's lineage, in CHRONOLOGICAL order (oldest first, current last). Only present when `?chain=true`. Each entry: `{ cusip: string, issuer_name: string, effective_date: string|null, reason: string|null, from_chain: boolean }`. The `from_chain: true` flag distinguishes chain predecessors from the seed CUSIP itself.

**Since:** v1.0.0

**Utility:** Ticker-keyed variant of [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain) — when you have the current ticker (`RKLB`) and need every CUSIP that has ever represented it (pre-SPAC + post-SPAC + post-redomicile). Without `chain=true` (default false), the endpoint behaves identically to the no-chain variant and returns the CURRENT CUSIP only. With `chain=true`, the response includes a `chain[]` array of all historical CUSIPs with `from_chain` flags. The most-natural entrypoint for ticker-shaped UI inputs that need chain-aware downstream queries.

**Use case:** Building comprehensive holdings queries that span CUSIP transitions — e.g. 'show me Berkshire's RKLB position from inception to today' requires querying 13F holdings across all 3 RKLB CUSIPs. Without the chain, the position appears to drop to 0 at each merger date and re-emerge under a new CUSIP. With the chain, the position-history chart is continuous. Also useful in 'reconcile a customer's ticker watchlist with their 13F-based position blotter' workflows that need historical-CUSIP coverage.

**Parameters:**
- `ticker` (path, required): Canonical hyphen-form ticker. v3.14.2 ticker-normalization shim applies (`BRK.A`/`BRK/A`/`BRKA` all coerce to `BRK-A`). The CURRENT ticker is required — historical-only tickers like `VACQ` (pre-SPAC RKLB) are not supported as input; use the CUSIP variant if you need to seed the chain walk from a historical entity.
- `chain` (query, optional, default: false): When `true`, response includes a `chain[]` array of all historical CUSIPs sharing this security's lineage. When `false` (default) or omitted, response is byte-identical to [GET /api/v1/cusip/ticker/{ticker}](/docs/reference-data/cusip-api/get-cusip-ticker) and returns CURRENT CUSIP only — backwards-compatible with pre-Phase-11 callers.

**Sample response:**
```json
{
  "ticker": "RKLB",
  "cusip": "773121108",
  "issuer_name": "ROCKET LAB CORPORATION",
  "cik": "0001819810",
  "cusip6": "773121",
  "chain": [
    {
      "cusip": "G9442R126",
      "issuer_name": "VECTOR ACQUISITION CORP",
      "effective_date": null,
      "reason": null,
      "from_chain": true
    },
    {
      "cusip": "773122106",
      "issuer_name": "ROCKET LAB USA INC",
      "effective_date": "2021-08-25",
      "reason": "SPAC merger",
      "from_chain": true
    },
    {
      "cusip": "773121108",
      "issuer_name": "ROCKET LAB CORPORATION",
      "effective_date": "2025-11-01",
      "reason": "Redomicile",
      "from_chain": false
    }
  ]
}
```

### GET /api/v1/cusip/cik/{cik}

Look up company CUSIP mappings by CIK number. Supports both short (e.g. 320193) and 10-digit zero-padded CIK formats.

**Token cost:** 1 token per call

**Response fields:**
- `cik` (string): Echoed CIK in 10-character zero-padded form regardless of input format.
- `issuer_name` (string): Issuer legal name from the canonical catalog (all-caps EDGAR convention).
- `securities` (array): Array of all CUSIPs registered to this CIK — one entry per security class (common stock, preferred, convertible, etc.). Multi-class issuers like BRK (2 classes) or AMZN-pre-split (1 class) return correspondingly-sized arrays. Order is by `security_group` priority then by ticker alphabetical (Stocks > Preferred > Warrants > Debt > Other) so common-equity classes appear first.
- `securities[].cusip` (string): 9-character CUSIP for this security class.
- `securities[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped tickers (debt securities, private placements).
- `securities[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`. Useful for filtering to common-equity-only or all-equity-classes views.
- `securities[].cusip6` (string): 6-character CUSIP issuer prefix. All securities for one CIK typically share the same CUSIP6 (Berkshire's BRK-A and BRK-B both share `084670`), but corporate-action successors can have different CUSIP6 prefixes (RKLB has CUSIP6 history `G9442R` -> `773122` -> `773121`).

**Since:** v3.14.0

**Utility:** Reverse lookup from SEC CIK to CUSIP and ticker — when your input is the SEC's canonical company identifier (e.g. you parsed a filing accession and want the CUSIP for downstream 13F holdings query). Returns ALL CUSIPs registered to the issuer, not just the primary — multi-class issuers like BRK (A + B classes), GOOGL (Alphabet A + C), and FTCH (with foreign-equivalent classes) can have 2-5 CUSIPs per CIK. Pair with [GET /api/v1/cusip/cusip6/{cusip6}](/docs/reference-data/cusip-api/get-cusip-cusip6) when you also want preferred / convertible / debt securities for the same issuer.

**Use case:** Filing-parsing pipelines that emit `(cik, accession_number)` rows and need to enrich with `(cusip, ticker)` for downstream holdings reconciliation. Also useful in 'show me all share classes for this issuer' workflows — Berkshire Hathaway CIK `0001067983` returns both BRK-A (`084670108`) and BRK-B (`084670702`) in one call.

**Parameters:**
- `cik` (path, required): SEC CIK number. Both formats accepted: 10-character zero-padded (`0000320193`) and short unpadded (`320193`). Server-side normalization handles both via `func.ltrim(cik, '0')` matching. Returns 404 when no CUSIP is registered to the CIK (rare; typically foreign-private issuers without ADR programs, or pre-registration shell companies).

**Sample response:**
```json
{
  "cik": "0001067983",
  "issuer_name": "BERKSHIRE HATHAWAY INC",
  "securities": [
    {
      "cusip": "084670108",
      "ticker": "BRK-A",
      "security_group": "Stocks",
      "cusip6": "084670"
    },
    {
      "cusip": "084670702",
      "ticker": "BRK-B",
      "security_group": "Stocks",
      "cusip6": "084670"
    }
  ]
}
```

### GET /api/v1/cusip/cusip6/{cusip6}

Look up all securities sharing a 6-digit CUSIP issuer prefix. Returns all 9-digit CUSIPs with matching first 6 characters (same issuer, different securities — common stock, preferred, warrants, etc.).

**Token cost:** 1 token per call

**Response fields:**
- `cusip6` (string): Echoed input CUSIP6 (uppercased).
- `issuer_name` (string): Most-common issuer name across all securities sharing this CUSIP6. For multi-entity prefixes (rare but possible after reorgs) this is the modal name; consult `securities[].issuer_name` for per-CUSIP detail.
- `securities` (array): Array of all 9-character CUSIPs sharing this issuer prefix. Order: by `security_group` priority then by ticker alphabetical (Stocks first, then ETFs / Preferred / Warrants / Debt / Other). For Apple `037833`: returns common stock; for Berkshire `084670`: returns BRK-A then BRK-B.
- `securities[].cusip` (string): Full 9-character CUSIP.
- `securities[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped securities (debt, private placements).
- `securities[].issuer_name` (string): Issuer name for THIS specific CUSIP — typically identical to the top-level `issuer_name` field but can vary slightly for amended-filings or post-reorg edge cases.
- `securities[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`. Filter to `Stocks` for common-equity-only views; `Preferred + Warrants` for hybrid-instrument exposure analysis.
- `securities[].cik` (string (nullable)): 10-character zero-padded SEC CIK for the issuer. Typically identical across all securities in the prefix (same legal entity).

**Since:** v3.14.0

**Utility:** Find all securities sharing a 6-digit CUSIP issuer prefix — typically returns more security classes than [GET /api/v1/cusip/cik/{cik}](/docs/reference-data/cusip-api/get-cusip-cik) because the CUSIP6 prefix groups by ISSUER OPERATIONALLY (CINS-assigned by CUSIP Global Services) rather than by SEC CIK. So a single CUSIP6 like `037833` (Apple) returns the common stock CUSIP plus any preferred / convertible / debt CUSIPs the same issuer has registered through CUSIP services. Useful when you need all security types (common + preferred + convertibles + bonds) for an issuer in one call. Note: CUSIP6 is NOT stable across reorgs — successor CUSIPs typically get new CUSIP6 prefixes (RKLB went `G9442R` -> `773122` -> `773121`).

**Use case:** Discovering all security classes (common, preferred, convertible, warrants, debt) for an issuer when you only have the 6-digit issuer code from a partial CUSIP reference. Also useful in 'find all securities Apple has issued' workflows where the customer wants common stock + any registered debt for credit-spread analysis.

**Parameters:**
- `cusip6` (path, required): 6-character CUSIP issuer prefix (case-insensitive). Real public-domain examples: `037833` (Apple), `594918` (Microsoft), `02079K` (Alphabet — covers both GOOGL `02079K305` and GOOG `02079K107`), `084670` (Berkshire — covers both BRK-A `084670108` and BRK-B `084670702`). Returns 404 when no securities are registered to the prefix.

**Sample response:**
```json
{
  "cusip6": "084670",
  "issuer_name": "BERKSHIRE HATHAWAY INC",
  "securities": [
    {
      "cusip": "084670108",
      "ticker": "BRK-A",
      "issuer_name": "BERKSHIRE HATHAWAY INC",
      "security_group": "Stocks",
      "cik": "0001067983"
    },
    {
      "cusip": "084670702",
      "ticker": "BRK-B",
      "issuer_name": "BERKSHIRE HATHAWAY INC",
      "security_group": "Stocks",
      "cik": "0001067983"
    }
  ]
}
```

### GET /api/v1/cusip/search

Full-text search across CUSIP mappings. Searches CUSIP, ticker, and security name fields. Returns only valid (active) mappings with pagination.

**Token cost:** 1 token per call

**Response fields:**
- `results` (array): Array of matching catalog rows. Order: by relevance score DESC (exact ticker matches first, then exact CUSIP-prefix matches, then trigram name-similarity score). Empty array on no matches — does NOT 404.
- `results[].cusip` (string): 9-character CUSIP.
- `results[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped securities.
- `results[].issuer_name` (string): Issuer name (all-caps EDGAR convention).
- `results[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`.
- `results[].cusip6` (string): 6-character CUSIP issuer prefix.
- `results[].score` (number): Relevance score in range [0, 1] — exact ticker match scores 1.0, exact CUSIP match scores 0.95, name-trigram similarity scores from 0.30-0.85 depending on overlap. Useful for client-side post-filtering (e.g. drop results below 0.40 to suppress weak matches).
- `meta` (object): Pagination block: `{ total: integer, limit: integer, offset: integer, query: string }`. `total` is the full match count across all pages — use for pagination control rendering.

**Since:** v3.14.0

**Utility:** Full-text search across CUSIP / ticker / issuer-name fields — the right entrypoint for typeahead UIs that accept any of those three input shapes (e.g. user types `Apple` or `AAPL` or `037` and the search palette resolves all 3 into the same CUSIP). Built atop the same `cusip_security_catalog` (~26K rows) but with PostgreSQL trigram fuzzy matching on the issuer-name field. Returns only ACTIVE mappings (excludes superseded predecessors of corporate-action chains — for chain expansion use the dedicated [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain) entrypoint). Pagination via standard `limit + offset`.

**Use case:** Building a CUSIP search interface where users can type partial input across any of the three fields. Also useful in 'reconcile a customer's free-form security mention against our canonical catalog' workflows — given user input `tesla` or `tesla motors`, return TSLA / `88160R101` / `TESLA INC` for downstream pipeline use.

**Parameters:**
- `q` (query, required): Search query (matches CUSIP, ticker, or security name). Case-insensitive. Trigram fuzzy matching on the name field — `apple` matches `APPLE INC` AND `APPLE HOSPITALITY REIT`. CUSIP fragment matching is exact-prefix (so `037` matches `037833100` but `833` does not). Ticker matching is exact OR prefix on canonical hyphen form (`BRK` matches both `BRK-A` and `BRK-B`).
- `limit` (query, optional, default: 50): Max results returned (1-100). Server caps at 100 — values > 100 silently clamp to 100.
- `offset` (query, optional, default: 0): Pagination offset for chunked retrieval. Pair with `limit` for `total // limit` page count.

**Sample response:**
```json
{
  "results": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "issuer_name": "APPLE INC",
      "security_group": "Stocks",
      "cusip6": "037833",
      "score": 1
    },
    {
      "cusip": "03784Y200",
      "ticker": "APLE",
      "issuer_name": "APPLE HOSPITALITY REIT INC",
      "security_group": "Stocks",
      "cusip6": "03784Y",
      "score": 0.62
    }
  ],
  "meta": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "query": "apple"
  }
}
```

### GET /api/v1/cusip/stats

CUSIP database statistics: total CUSIPs, mapped (with ticker), unmapped (no ticker), with CIK, and overall mapping rate percentage.

**Token cost:** 5 tokens per call

**Response fields:**
- `total_cusips` (integer): Total row count in `cusip_security_catalog`. Grows with new SEC filings + OpenFIGI nightly enrichment runs. Typical value: ~26,000 post v3.11.0 expansion to 6 security groups (was ~7,968 prior to the v3.11.0 catalog-broadening).
- `mapped` (integer): Count of CUSIPs with a non-null ticker mapping. Without `OPENFIGI_API_KEY` set, expect ~76% mapped (CUSIPs resolved via SEC company-tickers.json + filing-derived enrichment). With the key set, climbs to >98%.
- `unmapped` (integer): Count of CUSIPs with null ticker (no public-equity ticker found). Includes debt securities, private placements, delisted issuers, and OpenFIGI-coverage-gap CUSIPs. Typical: ~24% without OpenFIGI key, ~2% with key.
- `with_cik` (integer): Count of CUSIPs with non-null SEC CIK mapping. Bridges to filing-history endpoints. Typical: ~94% (most CUSIPs in the catalog originate from SEC-registered issuers).
- `mapping_rate` (number): Convenience field — `round(mapped / total_cusips * 100, 1)` as a decimal percent (e.g. 76.4 means 76.4% of CUSIPs are ticker-mapped). Display-ready for dashboards.
- `by_security_group` (object): Count breakdown by security_group classification — `{ Stocks: integer, ETFs: integer, Preferred: integer, Warrants: integer, Debt: integer, Other: integer }`. The 6-bucket schema established in v3.11.0. Useful for verifying coverage across all security types after a catalog refresh.
- `openfigi_enabled` (boolean): `true` when `OPENFIGI_API_KEY` is set in the FinRadar environment (changes batch size from 10 -> 100 CUSIPs/batch and delay from 2.4s -> 0.24s — critical for 13F deadline-day batch enrichment). `false` otherwise — expect lower mapping_rate.
- `last_refresh_at` (string (nullable)): ISO-8601 UTC timestamp of the most-recent catalog refresh (nightly OpenFIGI enrichment + SEC company-tickers.json sync). Null on cold-start or if the refresh DAG has never completed.

**Since:** v3.14.0

**Utility:** CUSIP catalog health metrics in one call — total catalog size, OpenFIGI ticker-resolution rate, CIK-coverage rate, security-group breakdown. The right endpoint for admin dashboards monitoring data quality on the cusip_security_catalog and for surfacing enrichment regressions when an ETL run fails to populate a batch of new CUSIPs. Without `OPENFIGI_API_KEY` set the typical mapped-rate sits around 76%; with the key set it climbs to >98%. Pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for cross-service health rollups.

**Use case:** Admin dashboard showing CUSIP mapping health — what percentage of CUSIPs have been resolved to tickers, how many have CIK mappings (for filing-history bridging), and the security-group distribution. Also useful for capacity planning ('we have 26K CUSIPs today, projecting 30K by end of year') and for SLA reporting to enterprise customers.

**Sample response:**
```json
{
  "total_cusips": 26080,
  "mapped": 25540,
  "unmapped": 540,
  "with_cik": 24515,
  "mapping_rate": 97.9,
  "by_security_group": {
    "Stocks": 8412,
    "ETFs": 3104,
    "Preferred": 1287,
    "Warrants": 482,
    "Debt": 11890,
    "Other": 905
  },
  "openfigi_enabled": true,
  "last_refresh_at": "2026-05-02T03:14:22Z"
}
```

---

## Search & Extraction

Advanced text search and content extraction.

### POST /api/v1/scrapping/query/

Advanced Boolean Search.

**Token cost:** 25 tokens per call

**Response fields:**
- `filings` (array): Array of filings matching the query, in sec-api.io's exact response shape. Sorted by `filedAt DESC` (newest first). Empty array on no match — never null. Compatible with existing client code that already parses sec-api.io responses.
- `filings[].accessionNo` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Matches sec-api.io's `accessionNo` field naming. Pass to `GET /api/v1/sec/filings/{accession_number}` to drill into the filing's documents in FinRadar's flatter shape.
- `filings[].cik` (string): Filer CIK as a 10-character zero-padded string. The same CIK always refers to the same legal entity across decades — a stable join key against EDGAR submissions, our `filings` table, and Sharadar SF1.
- `filings[].ticker` (string (nullable)): Ticker resolved from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class.
- `filings[].formType` (string): Canonical SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, `20-F`). Amendment variants append `/A`. NT-prefixed and -NT-suffixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim — these have no information table.
- `filings[].filedAt` (string): ISO-8601 UTC timestamp of the filing's SEC acceptance moment. Matches sec-api.io's `filedAt` field shape (full timestamp, NOT just the date).
- `filings[].periodOfReport` (string (nullable)): ISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end-date for 10-K/10-Q, the trade date for Form 4, etc.). Null for filings that don't have a meaningful period (e.g. some 8-Ks, S-1 initial registrations). Differs from `filedAt` — `periodOfReport` is the as-of date, `filedAt` is the disclosure date.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use as the human-readable link in dashboards; for programmatic document access use the `/html` companion endpoints which return parsed content.
- `total` (object): sec-api.io-compatible total-hits block: `{ value: integer, relation: 'eq' | 'gte' }`. The deep-pagination cap fires at 10000 hits — beyond that, switch to date-range chunking (`filedAt:[A TO B]`) since pagination cannot reach further.
- `total.value` (integer): Total hit count for the full query. Exact when `relation='eq'`; lower-bound when `relation='gte'` (i.e. 'at least this many; the deep-pagination cap was reached').
- `total.relation` (string): `eq` = exact total; `gte` = the deep-pagination cap was hit (only triggers when matching > 10000 filings). Use to detect when you need to switch to date-range chunking for full enumeration.

**Since:** v1.0.0

**Utility:** sec-api.io-compatible advanced filing search using Lucene-syntax boolean queries — drop-in for customers migrating from sec-api.io's `/full-text-search` query endpoint. Supports field-scoped filters (`ticker:`, `formType:`, `cik:`, `filedAt:[from TO to]`), boolean operators (`AND`/`OR`/`NOT`), wildcards (`tesla*`), and grouping (`(formType:10-K OR formType:10-Q) AND ticker:AAPL`). The single most powerful metadata-query endpoint in the FinRadar surface — analyst pipelines that need 'all 10-Ks from S&P 500 issuers in 2025' in one shot. Returns paginated filing metadata in sec-api.io's exact response shape (`filings[]` + `total: {value, relation}`). For full-text inside filing exhibits use `POST /api/v1/scrapping/search/`; for raw row-shaped reads use `GET /api/v1/sec/filings`.

**Use case:** Precise filtering: 'Give me all 10-Ks from Apple or Microsoft filed in 2023'.

**Parameters:**
- `query` (body, required): Lucene-style query string. Field-scoped: `ticker:AAPL`, `formType:"10-K"` (quote multi-word values), `cik:0000320193`, `filedAt:[2025-01-01 TO 2025-12-31]`. Operators: `AND`, `OR`, `NOT`. Wildcards: `tesla*`, `apple?`. Grouping: `(formType:10-K OR formType:10-Q) AND ticker:AAPL`. Bare-word queries match against issuer.name. Identical syntax to sec-api.io's full-text-search endpoint.
- `limit` (body, optional, default: 50): Maximum filings returned, capped at 50 server-side per page (matches sec-api.io's per-page cap). For deeper pagination use the `from` field if your client supports it; for full backfills, prefer date-range chunking via the `query.filedAt:[A TO B]` syntax.

**Sample response:**
```json
{
  "filings": [
    {
      "accessionNo": "0000320193-25-000123",
      "cik": "0000320193",
      "ticker": "AAPL",
      "formType": "10-K",
      "filedAt": "2025-11-01T20:14:32.000Z",
      "periodOfReport": "2025-09-28",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    }
  ],
  "total": {
    "value": 1,
    "relation": "eq"
  }
}
```

### POST /api/v1/scrapping/search/

Full-Text Search.

**Token cost:** 25 tokens per call

**Response fields:**
- `hits` (array): Array of text-match windows, sorted by relevance (BM25-style scoring) then `filed_date DESC` as a tiebreaker. A single filing can contribute multiple hits if the query phrase appears in multiple sections. Empty array on no match — never null.
- `hits[].accession_number` (string): SEC accession number of the filing containing this hit. Pass to `GET /api/v1/sec/filings/{accession_number}` for filing metadata, or to `GET /api/v1/scrapping/extractor` (with the matching `section`) to retrieve the full item text.
- `hits[].ticker` (string (nullable)): Resolved ticker for the issuer (canonical hyphen form). Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs). Useful for drilling: filter hits to S&P 500 issuers client-side via the resolved ticker.
- `hits[].form_type` (string): Canonical SEC form type containing the hit (e.g. `10-K`, `10-Q`, `8-K`, `DEF 14A`, `S-1`, `20-F`). Filter client-side to narrow the corpus by form (e.g. only `8-K`s for material-event surveillance).
- `hits[].filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date in ET. Sort hit lists by this descending to surface most-recent occurrences. Newer hits typically score lower than older hits in BM25 unless the recency-boost flag is on (off by default).
- `hits[].section` (string): Item or exhibit identifier where the match was located (e.g. `Item 7` for MD&A, `Item 1A` for Risk Factors, `EX-99.1` for press-release exhibits, `EX-10.1` for material contracts). Pass this directly to `/scrapping/extractor`'s `item` parameter to retrieve the full section.
- `hits[].snippet` (string): 200-300 character text window centered on the match, with the query phrase wrapped in HTML `<em>` tags for direct rendering. Edge characters may be word-broken — for clean rendering use a CSS truncation/ellipsis pattern. Plain text otherwise (no other HTML).
- `meta` (object): Result metadata: `{ total: integer, next_cursor: string|null }`. `total` is the full-corpus match count (cap-aware — values > 10000 surface as `gte`-style estimates). `next_cursor` is the opaque pagination cursor for the next page; null on last page.

**Since:** v1.0.0

**Utility:** Full-text search across the actual extracted text content of every SEC filing — 10-K Risk Factors, 10-Q MD&A, 8-K material event narratives, exhibit text, and proxy statements. The differentiator vs metadata-only `/scrapping/query/`: this scans the words IN the filings, not just the filing headers. Drives keyword surveillance workflows (e.g. 'every 8-K mentioning bankruptcy filed this week', 'every 10-K with going-concern doubt language', 'every proxy mentioning a specific named executive'). Returns hit windows with the matching phrase wrapped in `<em>` tags for direct highlight rendering. Use this to locate the filings, then call `/scrapping/extractor` to retrieve the full item once you've found the right hit.

**Use case:** Searching for specific keywords like 'bankruptcy' or 'merger' across millions of filings.

**Parameters:**
- `query` (body, required): Search term — single word, multi-word phrase (auto-quoted as a phrase search), or quoted exact-match string. Boolean operators NOT supported on this endpoint (use `/scrapping/query/` for boolean syntax). Multi-word queries match the phrase exactly, not the bag-of-words. Stemming and case-folding apply (`bankruptcy` matches `bankrupt` and `BANKRUPTCY`).
- `limit` (body, optional, default: 10): Maximum hit windows returned, capped at 50 server-side. Each hit is a 200-300 character text window centered on the match — for narrower scrolls, drop limit to 5-10; for sweeping audits, set to 50 and paginate via `meta.next_cursor`.

**Sample response:**
```json
{
  "hits": [
    {
      "accession_number": "0000320193-25-000123",
      "ticker": "AAPL",
      "form_type": "10-K",
      "filed_date": "2025-11-01",
      "section": "Item 1A",
      "snippet": "...material adverse effect on our <em>supply chain</em> and..."
    }
  ],
  "meta": {
    "total": 412,
    "next_cursor": "eyJpZCI6..."
  }
}
```

### GET /api/v1/scrapping/extractor

Extract a specific item section from a SEC filing — a sec-api.io Extractor replica. Supports 10-K, 10-Q and 8-K form types (20-F / 40-F are rejected with 400). The COMPLETE item section is returned in a single response — no length cap or truncation (a large 10-K Item 1A can run tens of thousands of characters).

**Token cost:** 25 tokens per call

**Response fields:**
- `(response body)` (string): This endpoint returns the extracted section as a RAW STRING body — NOT a JSON envelope. Content-Type is `text/plain` for `type=text` and `text/html` for `type=html`. The `text/html` body is allowlist-sanitized (nh3) before return (no `<script>`, no event-handler attributes, no non-http(s) URLs) and PRESERVES inline heading style (font-weight / font-size / text-decoration) while dropping color/background/positioning. The `X-Extractor-Mode` response header reports which path produced the body (`text` | `structured` | `legacy_html` | `notfound` | `pending`). An invalid item-for-form, or an unsupported form (20-F / 40-F), returns HTTP 400 (and is NOT billed). A valid item that is simply absent from the filing returns HTTP 404 (also NOT billed). On a cold-cache first fetch of a large filing the server may return HTTP 503 + `Retry-After` with `X-Extractor-Mode: pending` (also NOT billed) while it prepares the section in the background — retry to get the body. Body length ranges from ~1K to 100K+ characters (Item 1A on a large 10-K can exceed 100K).

**Since:** v3.3.1

**Utility:** Surgical item-level extraction from 10-K, 10-Q and 8-K filings — return just the Risk Factors (10-K Item 1A), just the MD&A (10-K Item 7 / 10-Q Part I Item 2), or a single 8-K event item (e.g. 2.02 Results of Operations), without parsing the full filing. Powers sentiment-analysis pipelines, NLP topic models, year-over-year diff tools, and LLM-grounded research workflows that need surgically-clean input text. ONE in-house BeautifulSoup engine locates the section and renders it two ways (`type=text` plain text, `type=html` style-preserving HTML). 10-K items supported: 1, 1A, 1B, 1C, 2, 3, 4, 5, 6, 7, 7A, 8, 9, 9A, 9B, 9C, 10–16 (bare codes). 10-Q items supported: PART-PREFIXED `part1item1`…`part2item6` (e.g. `part1item2` = MD&A, `part2item1a` = Risk Factors) — the Part prefix disambiguates the Part I / Part II Item-number collision. 8-K items supported: dotted event codes 1.01–9.01 (e.g. 2.02, 5.02, 8.01) plus `signature`. Foreign annual reports (20-F / 40-F) are NOT supported here — use the stock-research business-description endpoint for those. Use `POST /api/v1/scrapping/search/` to locate the right filing first.

**Use case:** Extracting 'Risk Factors' (10-K Item 1A) for sentiment analysis, the MD&A from a 10-Q (Part I Item 2), or an 8-K's 'Results of Operations' (Item 2.02) for earnings-event monitoring.

**Parameters:**
- `url` (query, required): Direct URL of the filing's primary HTML document on SEC EDGAR (NOT the index page — must be the actual HTML body of the 10-K/20-F). Get this from `filings[].linkToFilingDetails` then drill into the document URL, or from the `filing_url` field on `/api/v1/sec/filings`. Server-side rejected if the URL is not on the `sec.gov` domain or returns non-HTML content.
- `item` (query, required): Item code to extract — the FORMAT depends on `form_type`. **10-K** bare canonical codes: `1`, `1A`, `1B`, `1C`, `2`, `3`, `4`, `5`, `6`, `7`, `7A`, `8`, `9`, `9A`, `9B`, `9C`, `10`–`16` (case-insensitive, `1a` = `1A`). **10-Q** PART-PREFIXED codes: `part1item1`…`part2item6` (e.g. `part1item2` = MD&A, `part2item1a` = Risk Factors) — the Part prefix is REQUIRED so a Part I vs Part II Item number can never resolve to the wrong section; a bare `item=1` on a 10-Q is rejected with 400. **8-K** dotted event codes: `2.02`, `5.02`, `9.01`, … (the hyphen form `2-2` is also accepted and normalized to `2.02`) plus `signature` — 8-K codes require `form_type=8-K`. An item code that is not valid for the given form returns **400** (refunded, not billed). A valid item that is simply absent from that particular filing returns **404** (also refunded).
- `type` (query, optional, default: text): Output format — ONE located section, two renderings (the in-house engine runs the SAME detection for both). `text` (default) returns clean plain-text: tags stripped, HTML entities kept literal (e.g. `&#160;`), tables wrapped between `##TABLE_START` / `##TABLE_END` markers — best for NLP pipelines and LLM grounding. `html` returns STYLE-PRESERVING HTML: the filing's native heading styling (inline `font-weight` / `font-size` / `text-decoration`) is KEPT, while `color` / background / positioning and ALL XSS vectors (`<script>` tags, event-handler attributes, `javascript:` URLs) are stripped via an allowlist sanitizer (nh3) — safe to render in a browser. The response is a RAW string body (Content-Type `text/plain` for `text`, `text/html` for `html`), NOT a JSON envelope. Read the `X-Extractor-Mode` response header to see which path produced the body. On a cold-cache first fetch of a large filing the server may return HTTP 503 with `X-Extractor-Mode: pending` and a `Retry-After` header while it prepares the section in the background — this response is NOT billed; retry after a few seconds. Cost is identical across formats.
- `form_type` (query, optional, default: 10-K): Form type of the filing — selects the item-code grammar and detection rules. One of `10-K` (default), `10-Q`, or `8-K`. Any other value (e.g. `20-F`, `40-F`) returns **400** ('not supported'), refunded. Because the `item` grammar is form-specific (10-Q needs Part-prefixed codes like `part1item2`, 8-K needs dotted codes like `2.02`), you MUST set `form_type` correctly for 10-Q and 8-K — leaving the `10-K` default with a 10-Q/8-K item yields a 400.

**Sample response:**
```json
"<p style=\"font-weight:bold;font-size:10pt\">ITEM 1A. RISK FACTORS</p>\n<p style=\"font-size:10pt;font-weight:normal\">You should carefully consider the risks described below together with the other information set forth in this report, which could materially affect our business, financial condition and operating results...</p>"
```

### GET /api/v1/scrapping/xbrl

Convert XBRL to JSON. Pass either the XBRL document URL OR the accession number — accession is auto-extracted from the URL if only the URL is provided.

**Token cost:** 25 tokens per call

**Response fields:**
- `accession_number` (string): SEC accession number of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format (always normalized to dashed form regardless of input).
- `form_type` (string): Source filing's form type as detected from the XBRL instance metadata (typically `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`). Useful for cost-budgeting downstream processing (10-Ks have 800-2000 facts; 8-Ks typically have 5-50).
- `period_end` (string): ISO `YYYY-MM-DD` reporting period end of the filing's primary context (the fiscal-quarter or fiscal-year end). For 10-K/10-Q this is the canonical period the financials cover; for 8-K it's the event date.
- `facts` (array): Array of XBRL fact rows. One row per `(concept, period, dimensions)` tuple — same concept can appear multiple times if reported across multiple periods or dimensional members (e.g. revenue by geographic segment). Empty array for filings that have no XBRL (rare; typically only NT amendments and some pre-2010 archival filings).
- `facts[].concept` (string): Concept name in `prefix:LocalName` format. Standard concepts use the `us-gaap:` prefix (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`); company-specific extensions use the company's own prefix (e.g. `aapl:iPhone`, `tsla:VehicleSales`). Pass to `GET /api/v1/facts/by-concept` for cross-company aggregations of the same concept.
- `facts[].value` (number (nullable)): Numeric fact value in the unit specified by `facts[].unit`. Null for textual or non-numeric facts (e.g. company description, accounting policy strings). NOT scale-adjusted — values are reported as-filed; reconcile against `unit` to interpret (e.g. value=391035 + unit=USD-thousands means $391.035M).
- `facts[].unit` (string (nullable)): XBRL unit reference. Common values: `USD` (US dollars at 1:1 scale), `shares` (raw share count), `pure` (dimensionless ratios — typically `0-1`), `USD-per-share` (per-share dollar values), `iso4217:JPY`/`iso4217:EUR` (foreign currencies). Null only when `value` is null (textual facts). Always check unit before arithmetic — companies routinely mix `USD` and `USD-thousands` within the same filing.
- `facts[].period_start` (string (nullable)): ISO `YYYY-MM-DD` start date for duration concepts (income-statement and cash-flow facts that cover a period). Null for instant concepts (balance-sheet facts that are point-in-time at `period_end`). Use the `period_start` + `period_end` pair to detect Q vs YTD vs TTM scope.
- `facts[].period_end` (string): ISO `YYYY-MM-DD` end date for the fact. For instant concepts this is the as-of date; for duration concepts this is the period end. Always present.
- `facts[].dimensions` (object (nullable)): XBRL dimensional context as a `{axis: member}` map (e.g. `{StatementBusinessSegmentsAxis: 'IPhoneSegmentMember'}`). Null when the fact has no dimensional qualifier (the most common case — un-dimensioned facts represent the consolidated entity). Use to filter segment-level vs total-level facts (`facts.filter(f => f.dimensions === null)` returns the consolidated view).

**Since:** v1.0.0

**Utility:** Parses a single SEC XBRL filing's instance document into a clean array of fact rows: `concept`, `value`, `unit`, `period_start`, `period_end`, `dimensions`. Use this when you need the AS-FILED facts for a specific accession (e.g. to reconcile a 10-K's reported revenue against your downstream model, or to extract a custom company-specific concept like `aapl:iPhone`). For cross-company standardized financial-statement queries — where you want apples-to-apples Revenue/NetIncome across 7,000+ filers — use `GET /api/v1/financials/metrics` instead, which standardizes the messy as-filed facts into a clean canonical schema. Either input is sufficient: pass the direct XBRL document URL, or pass just the accession number and we auto-resolve the document.

**Use case:** Extracting financial statements (Balance Sheet, Income Statement) in a structured format.

**Parameters:**
- `xbrl_url` (query, optional): Direct URL of the XBRL instance document on SEC EDGAR (the `.xml` or inline-XBRL `.htm` file containing tagged facts — NOT the filing index page). Server-side rejected if not on `sec.gov`. At least one of `xbrl_url` or `accession_number` is required; if both are passed, `xbrl_url` takes precedence.
- `accession_number` (query, optional): SEC accession number with or without dashes (e.g. `0000320193-24-000123` or `000032019324000123` both work). When passed alone, the server auto-resolves the primary XBRL instance document by fetching the filing's index page. At least one of `xbrl_url` or `accession_number` is required.

**Sample response:**
```json
{
  "accession_number": "0000320193-25-000123",
  "form_type": "10-K",
  "period_end": "2025-09-28",
  "facts": [
    {
      "concept": "Revenues",
      "value": 391035000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28"
    },
    {
      "concept": "NetIncomeLoss",
      "value": 96995000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28"
    }
  ]
}
```

### GET /api/v1/scrapping

Live SEC EDGAR scrape with form-type + CIK + date filtering. Returns filings synthesized by a Python subprocess that scrapes EDGAR's search pages — heavier and slower than the local-index `/api/v1/sec/filings` endpoint. Use this when you need filings that haven't been ingested locally yet, or when you need EDGAR's search-page-specific fields not stored in the local index.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of the resolved query parameters used for the EDGAR scrape — useful for debugging when results don't match expectations.
- `query.formType` (string): Echoed form type (uppercased). Confirms the `form_Type` param was parsed correctly.
- `query.result` (integer): Count of filings returned in `filings[]` after date filtering. Equals `filings.length`.
- `filings` (array): Array of filing records as scraped from SEC EDGAR's search pages. Schema differs from `GET /api/v1/sec/filings`'s normalized schema — uses EDGAR-native field names. Empty array on no match. The cost-zero distinction: this is a heavyweight call (10 tokens) that runs a Python subprocess against EDGAR; use the local index endpoint when possible.
- `filings[].accession_Number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. CamelCase field name (`accession_Number`) reflects EDGAR's stored form.
- `filings[].cik` (string): Filer CIK as zero-padded 10-character string.
- `filings[].formType` (string): Canonical SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`).
- `filings[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET. CamelCase field name reflects EDGAR's stored form.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page. Pass this to [GET /api/v1/sec/document?url=...](/docs/sec-filings/sec-filings-api/get-sec-document) to fetch the filing body.

**Since:** v1.0.0

**Utility:** Live scrape against SEC EDGAR's search pages — heavier (10 token cost reflects the full-EDGAR roundtrip via a Python subprocess) and slower than `GET /api/v1/sec/filings` (which hits the local index instantly and costs only 5 tokens). Use this when: (a) you need filings that haven't been ingested locally yet (very recent filings before the RSS poller catches them), (b) you specifically want EDGAR's search-result schema rather than FinRadar's normalized schema, (c) you're integrating from a tutorial that referenced this endpoint and don't want to refactor. For 99% of workflows prefer [GET /api/v1/sec/filings](/docs/sec-filings/sec-filings-api/get-sec-filings) — it's faster, cheaper, and self-healing (auto-backfills via this scrape on first-touch). Note: returns a different envelope shape than the rest of the SEC Filings API (`{query, filings}` rather than `ApiResponse.success`).

**Use case:** Tutorial follow-along where the example is parameterized for `/scrapping`. For new integrations, prefer `/sec/filings`.

**Parameters:**
- `form_Type` (query, optional, default: 10-K): Form type to scrape (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). Note the CamelCase param name (`form_Type` not `form_type`) — preserved verbatim from EDGAR's URL convention. Defaults to `10-K` when omitted.
- `cik` (query, optional): 10-char zero-padded CIK to filter by. Use the CIK rather than ticker — EDGAR's search index is CIK-keyed. Resolve a ticker → CIK via [GET /api/v1/scrapping/cik](/docs/sec-filings/search-and-extraction/get-scrapping-cik) first.
- `count` (query, optional, default: 0): Number of filings to return. `0` (default) means "unlimited" — beware on large issuers. Cap at 40 for predictable latency.
- `size` (query, optional, default: 10): Page size for EDGAR's pagination (1-40). Mirrors EDGAR's `count` URL param verbatim. Lower values reduce per-call latency.
- `start_Date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. CamelCase param name (`start_Date`) preserved from EDGAR's URL convention. Filtered client-side after EDGAR returns — does NOT reduce upstream load.
- `end_Date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Filtered client-side after EDGAR returns.

**Sample response:**
```json
{
  "query": {
    "formType": "10-K",
    "result": 1
  },
  "filings": [
    {
      "accession_Number": "0000320193-25-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2025-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    }
  ]
}
```

### GET /api/v1/scrapping/cik

Get filings for a specific CIK via EDGAR scrape. Returns filings filtered by form type and optional date range. Useful when you need EDGAR's search-result schema for a specific CIK rather than FinRadar's normalized schema.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of the resolved query parameters used for the EDGAR scrape — useful for debugging when results don't match expectations.
- `query.formType` (string): Echoed form type (uppercased).
- `query.result` (integer): Count of filings returned in `filings[]` after EDGAR-level date filtering.
- `query.count` (integer): Echoed `count` parameter — useful for assertion in tests.
- `filings` (array): Array of filing records as scraped from SEC EDGAR's filer-detail pages. Schema uses EDGAR-native field names. Empty array on no match — never null.
- `filings[].accession_Number` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `filings[].cik` (string): Filer CIK as zero-padded 10-character string. Echoes the input.
- `filings[].formType` (string): Canonical SEC form type as filed (echoes the `form_Type` filter).
- `filings[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET. Within the `start_Date`..`end_Date` window when those filters are passed.
- `filings[].linkToFilingDetails` (string): Canonical SEC EDGAR URL for the filing's index page. Pass to [GET /api/v1/sec/document?url=...](/docs/sec-filings/sec-filings-api/get-sec-document) to fetch the filing body.

**Since:** v1.0.0

**Utility:** CIK-keyed live EDGAR scrape — pass a 10-char zero-padded CIK and a form type, receive that filer's filings of that type as scraped from EDGAR's search pages. Heavier than `GET /api/v1/sec/filings?cik=...` (which is the local-index path) — use this when: (a) the local index is missing recent filings for this CIK and you need EDGAR's live data, (b) you specifically need EDGAR's search-result schema, (c) you're following a tutorial that referenced this endpoint. Date filtering happens at SEC level so date-bounded queries are server-efficient. The non-standard CamelCase param names (`form_Type`, `start_Date`, `end_Date`) are preserved verbatim from EDGAR's URL convention.

**Use case:** Given Apple's CIK (0000320193), retrieve their last 10 10-K filings from EDGAR directly with `cik=0000320193&form_Type=10-K&count=10`.

**Parameters:**
- `cik` (query, required): 10-char zero-padded CIK to query (e.g. `0000320193` for Apple). Returns 400 BAD_REQUEST when missing. Resolve a ticker → CIK via [GET /api/v1/scrapping/cik](/docs/sec-filings/search-and-extraction/get-scrapping-cik) — wait, that's THIS endpoint — use [GET /api/v1/sec/entities](/docs/sec-filings/sec-filings-api/get-sec-entities) which returns `(entity_name, cik)` pairs, or query [GET /api/v1/sec/filings?ticker=...](/docs/sec-filings/sec-filings-api/get-sec-filings)'s response which surfaces the CIK in `meta.cik`.
- `form_Type` (query, optional, default: 10-K): Form type to filter by (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). CamelCase param name preserved from EDGAR's URL convention. Defaults to `10-K`.
- `count` (query, optional, default: 10): Maximum number of filings to return (1-40 recommended). Date filtering happens at SEC level so this is the upper bound on EDGAR's return set, not just the post-filter count.
- `start_Date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. Filtered at SEC level — reduces upstream load.
- `end_Date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Filtered at SEC level.

**Sample response:**
```json
{
  "query": {
    "formType": "10-K",
    "result": 2,
    "count": 10
  },
  "filings": [
    {
      "accession_Number": "0000320193-25-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2025-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/0000320193-25-000123-index.htm"
    },
    {
      "accession_Number": "0000320193-24-000123",
      "cik": "0000320193",
      "formType": "10-K",
      "filingDate": "2024-11-01",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.htm"
    }
  ]
}
```

### GET /api/v1/scrapping/form-10

Scrape 10-K and 10-Q filings. Returns filing metadata + extraction-ready URLs for the primary document. Use /api/v1/scrapping/extractor to extract specific sections (Item 1A Risk Factors, Item 7 MD&A, etc.).

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.formType` (string): Always `"Form 10"` (covers both 10-K and 10-Q variants).
- `query.link` (string): Echoed input URL — useful for tracing the scrape source.
- `data` (object): Scrape result envelope.
- `data.status` (string): Scrape outcome — `"success"` on parse + DB-persist success, `"error"` on subprocess or parse failure.
- `data.message` (string (nullable)): Human-readable status message (e.g. `"Filing saved successfully"` on success, exception text on error).
- `data.filing_id` (integer (nullable)): Internal `filings.id` row ID assigned when the scrape result was persisted to the local DB. Null on scrape error.
- `data.uuid` (string (nullable)): UUIDv4 generated server-side for cross-environment tracking of the persisted record.
- `data.data` (object): Parsed filing record — see `data.data.*` fields. Uses sec-api.io-style CamelCase field names.
- `data.data.cik` (string (nullable)): Filer CIK as parsed from the index page (zero-padding NOT applied — may be the un-padded form). Null when the index page format is unrecognized.
- `data.data.ticker` (string (nullable)): Resolved ticker via SEC's `company_tickers.json` lookup (matched by zero-padded CIK). Empty string when the CIK has no public ticker.
- `data.data.formType` (string (nullable)): Form type as parsed from the filer info block (e.g. `10-K`, `10-Q`).
- `data.data.description` (string): Filing description from EDGAR's filing-name header (e.g. `"Apple Inc. 10-K"`).
- `data.data.accessionNo` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `data.data.filingdate` (string): Filing date as displayed on EDGAR's index page (text format — typically `YYYY-MM-DD` but exact form depends on EDGAR's display convention).
- `data.data.accepted` (string): Filing accepted timestamp as displayed on EDGAR (typically `YYYY-MM-DD HH:MM:SS`).
- `data.data.periodOfReport` (string): Period of report as displayed on EDGAR (typically `YYYY-MM-DD` for 10-K/10-Q — the fiscal-period-end date).
- `data.data.documentFormatFiles` (array): Array of structured document descriptors `[{Seq, Description, Document, Type, Size}, ...]` from the index page's "Document Format Files" table. The primary HTML/PDF body of the filing is in this list.
- `data.data.dataFiles` (array): Array of XBRL/data file descriptors from the index page's "Data Files" table. Populated when XBRL is embedded; empty array on filings without XBRL.
- `data.data.companyNameLong` (string): Filer's full legal name with embedded EDGAR metadata (e.g. `"APPLE INC. (CIK: 0000320193) (Filer)"`).
- `data.data.companyName` (string): Cleaned filer name without embedded metadata (e.g. `"APPLE INC."`).
- `data.data.linkToXBRL` (string): Direct URL to the XBRL instance document. Pair with [GET /api/v1/scrapping/xbrl?xbrl_url=...](/docs/sec-filings/search-and-extraction/get-scrapping-xbrl) for parsed financial facts.
- `data.data.linkToTxt` (string): Direct URL to the filing's primary HTML or TXT document body. Pair with [GET /api/v1/scrapping/extractor?url=...](/docs/sec-filings/search-and-extraction/get-scrapping-extractor) for surgical item extraction.
- `data.data.original_link` (string): Echoed input `link` parameter.

**Since:** v1.0.0

**Utility:** Single-filing 10-K/10-Q scraper — pass the EDGAR index-page URL of a filing and receive full filer metadata (CIK, ticker, fiscal year end, state of incorporation, SIC, file number), the structured `documentFormatFiles[]` and `dataFiles[]` lists from the index page, and direct URLs to the primary document HTML and the XBRL instance. Use this when you have a 10-K/10-Q URL (from EDGAR search, an RSS alert, a research email) and want the structured filing record without writing your own EDGAR scraper. The 10-token cost reflects the full-EDGAR roundtrip + the BeautifulSoup parse. For surgical item extraction (just Item 1A Risk Factors, just Item 7 MD&A) prefer [GET /api/v1/scrapping/extractor](/docs/sec-filings/search-and-extraction/get-scrapping-extractor) which costs the same but returns the parsed item text directly. For the local-index version (which gives you the same `all_links` array but at 5 tokens), use [GET /api/v1/sec/filings/{accession_number}](/docs/sec-filings/sec-filings-api/get-sec-filings-accession-number).

**Use case:** An RSS alert delivered an Apple 10-K URL — call this endpoint to get the parsed filer metadata + the XBRL instance URL + the primary HTML URL in one call.

**Parameters:**
- `link` (query, required): Full SEC EDGAR URL of the filing's index page (NOT the primary document — must be the index page that lists all documents in the filing package). Get from the `linkToFilingDetails` field in `/scrapping/cik` responses, or from the `primary_link` field in `/api/v1/sec/filings` responses. Returns 400 BAD_REQUEST when missing. Server-side fetches via Python subprocess with a 5-minute timeout.

**Sample response:**
```json
{
  "query": {
    "formType": "Form 10",
    "link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K"
  },
  "data": {
    "status": "success",
    "message": "Filing saved successfully",
    "filing_id": 18234567,
    "uuid": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2",
    "data": {
      "cik": "0000320193",
      "ticker": "AAPL",
      "formType": "10-K",
      "description": "Apple Inc. 10-K",
      "accessionNo": "0000320193-25-000123",
      "filingdate": "2025-11-01",
      "accepted": "2025-11-01 20:14:32",
      "document": "aapl-20250928.htm",
      "periodOfReport": "2025-09-28",
      "documentFormatFiles": [
        {
          "Seq": "1",
          "Description": "10-K",
          "Document": "aapl-20250928.htm",
          "Type": "10-K",
          "Size": "12943821"
        }
      ],
      "dataFiles": [
        {
          "Seq": "2",
          "Description": "XBRL Instance Document",
          "Document": "aapl-20250928.xml",
          "Type": "EX-101.INS",
          "Size": "412390"
        }
      ],
      "companyNameLong": "APPLE INC. (CIK: 0000320193) (Filer)",
      "companyName": "APPLE INC.",
      "entities": [],
      "linkToXBRL": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.xml",
      "linkToTxt": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000123/aapl-20250928.htm",
      "original_link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=10-K"
    }
  }
}
```

### GET /api/v1/scrapping/form-13f

Scrape 13F-HR institutional-holdings filings for a specific CIK. Returns parsed filing metadata + the holdings information table (one row per portfolio position) with CUSIP-level enrichment (ticker, security name, FIGI). Use this for institutional-manager portfolio analysis when you need EDGAR-native field shapes; for the curated FinRadar 13F surface use /api/v1/13f/filer/{cik}/holdings.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.cik` (string): Echoed CIK.
- `query.formType` (string): Always `"13-F"` (note the dash — preserved from EDGAR's stored form, distinct from the canonical `13F-HR` used in the local index).
- `query.start_date` (string (nullable)): Echoed start_date param. Null when omitted.
- `query.end_date` (string (nullable)): Echoed end_date param. Null when omitted.
- `query.result` (integer): Count of filings returned in `data` (when `data` is an array) or `1` (when `data` is a single filing object).
- `data` (array): Array of 13F-HR filings, sorted by `filed_date DESC` (newest first). Each element is a parsed 13F filing with embedded holdings table — see `data[].*` for shape. Single-element when `count=1`; up to `count` elements otherwise. Empty array when no filings match — never null.
- `data[].accessionNo` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`.
- `data[].cik` (string): Institutional manager CIK (echoes the input).
- `data[].companyName` (string): Manager's legal entity name as registered with SEC (e.g. `BERKSHIRE HATHAWAY INC`).
- `data[].formType` (string): Form type — `13F-HR` for the standard quarterly filing or `13F-HR/A` for amendments. NT-suffixed forms (`13F-NT`) appear here too — these have no information table to drill into.
- `data[].filingDate` (string): ISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET.
- `data[].periodOfReport` (string): ISO date `YYYY-MM-DD` of the as-of date for the holdings table (typically last day of the calendar quarter — `2025-03-31`, `2025-06-30`, `2025-09-30`, `2025-12-31`).
- `data[].linkToFilingDetails` (string): SEC EDGAR URL for the filing's index page.
- `data[].linkToInformationTable` (string (nullable)): Direct URL to the information-table XML file (the structured holdings list). Null on `13F-NT` filings which have no information table.
- `data[].holdings` (array): Array of portfolio positions parsed from the information table. One row per `(CUSIP, security_class)` pair. Empty array on `13F-NT` filings or filings with empty information tables (rare but legitimate).
- `data[].holdings[].cusip` (string): 9-character CUSIP identifier of the security held.
- `data[].holdings[].nameOfIssuer` (string): Issuer name as reported in the information table (often differs cosmetically from the issuer's canonical name — dedupe via CUSIP not name).
- `data[].holdings[].titleOfClass` (string): Security class (e.g. `COM`, `COM CL A`, `PUT`, `CALL`).
- `data[].holdings[].value` (integer): Market value of the position in USD (NOT in thousands — server-side normalized from the 2022-09-onward `value_in_dollars` form). Rationale: pre-2022-09 13F filings reported `value` in USD-thousands; we convert client-side to a unified USD scale.
- `data[].holdings[].shares` (integer): Share count held (or principal amount for debt instruments).
- `data[].holdings[].sshPrnamtType` (string): Share/principal type — `SH` (shares) or `PRN` (principal amount). Distinguishes equity holdings from debt holdings.
- `data[].holdings[].putCall` (string (nullable)): Option type for derivative positions — `PUT` or `CALL`. Null on direct equity holdings (the most common case).
- `data[].holdings[].ticker` (string (nullable)): Resolved ticker via the local `cusip_mappings` table. Null when the CUSIP is unmapped (private securities, OTC, very-recently-issued).
- `data[].holdings[].security_name` (string (nullable)): Canonical security name from `cusip_mappings`.
- `data[].holdings[].security_type` (string (nullable)): Security type (e.g. `Common Stock`, `Preferred Stock`, `Warrant`, `Option`, `ADR`).

**Since:** v1.0.0

**Utility:** Live 13F-HR scraper — pass an institutional manager's 10-char CIK and receive their most recent 13F-HR filings with full holdings tables (CUSIP, security_name, value_in_thousands, shares, voting_authority breakdown). CUSIPs are enriched server-side via the local `cusip_mappings` table to add ticker, security_type, FIGI, and exchange code. The right surface for: building a custom institutional-portfolio dashboard, replicating sec-api.io's 13F response shape for a migration, exporting BlackRock / Berkshire / Vanguard quarterly holdings to CSV. Heavy (10 tokens) — runs a Python subprocess that fetches the index page + the information table XML, parses both, then enriches CUSIPs via the local DB. For the curated FinRadar 13F surface (faster, cheaper, with split-adjusted positions) use [GET /api/v1/13f/filer/{cik}/holdings](/docs/institutional-holdings/form-13f-api/get-13f-filer-cik-holdings) instead — recommended for new integrations.

**Use case:** Pull Berkshire Hathaway's last 4 quarterly 13F holdings (CIK 0001067983, count=4) to track Buffett's position changes quarter-over-quarter.

**Parameters:**
- `cik` (query, required): Institutional manager CIK as a digit-only string, max 10 digits (e.g. `0001067983` for Berkshire Hathaway, `1364742` for BlackRock). Returns 400 BAD_REQUEST when missing or non-numeric. Resolve a manager name → CIK via [GET /api/v1/sec/entities?form_type=13F-HR](/docs/sec-filings/sec-filings-api/get-sec-entities).
- `start_date` (query, optional): Lower-bound filing date in `YYYY-MM-DD` format. Returns 400 on invalid format. Filtered at SEC level — reduces upstream load.
- `end_date` (query, optional): Upper-bound filing date in `YYYY-MM-DD` format. Returns 400 on invalid format.
- `count` (query, optional, default: 10): Maximum number of 13F-HR filings to return (must be 1-40). Returns 400 outside that range. For quarterly tracking use `count=4` (last year); for full historical use `count=40` (which spans ~10 years for most managers).

**Sample response:**
```json
{
  "query": {
    "cik": "0001067983",
    "formType": "13-F",
    "start_date": null,
    "end_date": null,
    "result": 1
  },
  "data": [
    {
      "accessionNo": "0001067983-25-000004",
      "cik": "0001067983",
      "companyName": "BERKSHIRE HATHAWAY INC",
      "formType": "13F-HR",
      "filingDate": "2025-11-14",
      "periodOfReport": "2025-09-30",
      "linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/1067983/000106798325000004/0001067983-25-000004-index.htm",
      "linkToInformationTable": "https://www.sec.gov/Archives/edgar/data/1067983/000106798325000004/infotable.xml",
      "holdings": [
        {
          "cusip": "037833100",
          "nameOfIssuer": "APPLE INC",
          "titleOfClass": "COM",
          "value": 78240194000,
          "shares": 300000000,
          "sshPrnamtType": "SH",
          "putCall": null,
          "ticker": "AAPL",
          "security_name": "Apple Inc",
          "security_type": "Common Stock"
        }
      ]
    }
  ]
}
```

### GET /api/v1/scrapping/insider-trading

Scrape an insider trading filing (Form 3 / 4 / 5) by URL. Returns parsed insider identity, issuer, and per-transaction details (transaction date, code, shares, price, post-transaction holdings). Use this for one-off Form 4 lookups when you have the URL; for the curated FinRadar insider transactions surface use /insider-module/api/insiders/transactions/latest.

**Token cost:** 10 tokens per call

**Response fields:**
- `query` (object): Echo of input parameters.
- `query.formType` (string): Always `"Form 4"` — endpoint name preserved even when the underlying filing is a Form 3 or Form 5.
- `query.link` (string): Echoed input URL.
- `data` (object): Parsed Form 3/4/5 record — see `data.*` fields. Camel-cased field names preserved from EDGAR's stored form.
- `data.formtype` (string): Detected form type — `3`, `4`, `5`, `4/A`, etc. Use to route processing logic (Form 3 = initial holdings; Form 4 = changes; Form 5 = annual reconciliation).
- `data.formtitle` (string): Filing title as displayed in the EDGAR viewer (e.g. `"FORM 4 STATEMENT OF CHANGES IN BENEFICIAL OWNERSHIP"`).
- `data.formstatement` (string): The legal statement block from the form header — typically references Section 16(a) of the Securities Exchange Act.
- `data.omb_approval` (object): OMB approval block — `{ombnumber, hoursperresponse}`. Useful for forensic / audit-trail work; ignore for analytics.
- `data.notSubjectToSection16` (boolean): `true` when the insider has marked the "no longer subject to Section 16" checkbox (e.g. departing executives filing a final Form 4). False otherwise.
- `data.rule10b51Plan` (boolean): `true` when the transaction is executed under a pre-arranged Rule 10b5-1 plan (a SEC-sanctioned defense against insider-trading allegations — "I scheduled this sale 6 months ago, not based on material non-public info"). Critical signal for insider-transaction analytics — Rule 10b5-1 sales are pre-planned, raw discretionary sales aren't.
- `data.issuer` (object): Issuer info — see `data.issuer.*` fields.
- `data.issuer.cik` (string (nullable)): Issuer CIK as parsed from the form's issuer block. Null when the parse fails (rare).
- `data.issuer.name` (string (nullable)): Issuer's legal entity name (e.g. `"APPLE INC"`).
- `data.issuer.tradingSymbol` (string (nullable)): Issuer's ticker as reported on the Form 4 (e.g. `"AAPL"`). Authoritative for the filing — use this rather than CIK→ticker lookup if available.
- `data.issuer.transactiondate` (string (nullable)): Date of earliest transaction in the filing (typically the trade date for Form 4).
- `data.amendmentDate` (string (nullable)): Date of original filing when this is an amendment (`/A` suffix). Null on non-amendments.
- `data.individualOrJoint` (string (nullable)): `Individual` or `Joint/Group` — Form 4 supports group filings by multiple insiders sharing a single submission.
- `data.reportingOwners` (array): Array of reporting owners — typically 1 element on individual filings, multiple on joint/group filings. Each entry: `{name, cik, address, relationship: {director, officer, tenPercentOwner, other, officerTitle}}`.
- `data.nonDerivativeTransactions` (array): Array of non-derivative (i.e. direct equity) transactions. Each entry: `{title, transactionDate, transactionCode, transactionAmount, transactionPrice, sharesOwnedFollowingTransaction, ownership}`. Empty array when no direct-equity activity.
- `data.derivativeTransactions` (array): Array of derivative (option / warrant / convertible) transactions. Includes additional fields for strike price, expiration, underlying security. Empty array when no derivative activity.
- `data.signature` (object (nullable)): Signature block — `{signatureName, signatureDate}`. The signature is the insider's electronic signature confirming the filing.

**Since:** v1.0.0

**Utility:** Single-filing Form 3/4/5 scraper — pass an insider-filing URL and receive full structured data: insider identity (name, CIK, role flags for Director/Officer/10%-Owner), issuer info (CIK, name, ticker), per-transaction rows (transaction date, transaction code A/D/M/F/G/X, shares, price, post-transaction holdings), and the Rule 10b5-1 / Section 16 status flags. Heavy (10 tokens) because the Python subprocess fetches + BeautifulSoup-parses the EDGAR Form 4 XML viewer page. For NEW integrations strongly prefer [GET /insider-module/api/insiders/transactions/latest](/docs/insiders/insider-trading-api/get-insiders-transactions-latest) — that's the curated FinRadar insider surface with `total_beneficial_ownership` aggregation and Sharadar sector enrichment, faster + structured for screening. The scrapping endpoint is preserved for: (a) sec-api.io migration compatibility, (b) tutorial follow-along, (c) one-off URL-driven lookups where you don't need the Form-4-as-a-Service structure.

**Use case:** Got a Form 4 URL from an RSS alert ("Tim Cook just sold AAPL") — call this endpoint to immediately parse the transaction details (price, shares, post-transaction holdings).

**Parameters:**
- `link` (query, required): Full SEC EDGAR URL of the Form 4 (or Form 3 / Form 5) viewer page (the page that displays the formatted form, not the XML directly). Returns 400 BAD_REQUEST when missing. Get from `linkToFilingDetails` in `/scrapping/cik` responses or from RSS alert payloads. Server-side fetches via Python subprocess with a 5-minute timeout.

**Sample response:**
```json
{
  "query": {
    "formType": "Form 4",
    "link": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0001214156&type=4"
  },
  "data": {
    "formtype": "4",
    "formtitle": "FORM 4 STATEMENT OF CHANGES IN BENEFICIAL OWNERSHIP",
    "formstatement": "OMB APPROVAL Filed pursuant to Section 16(a)...",
    "omb_approval": {
      "ombnumber": "3235-0287",
      "hoursperresponse": "0.5"
    },
    "notSubjectToSection16": false,
    "rule10b51Plan": true,
    "issuer": {
      "cik": "0000320193",
      "name": "APPLE INC",
      "tradingSymbol": "AAPL",
      "transactiondate": "2026-04-15"
    },
    "amendmentDate": null,
    "individualOrJoint": "Individual",
    "reportingOwners": [
      {
        "name": "COOK TIMOTHY D",
        "cik": "0001214156",
        "relationship": {
          "director": false,
          "officer": true,
          "tenPercentOwner": false,
          "other": false,
          "officerTitle": "Chief Executive Officer"
        }
      }
    ],
    "nonDerivativeTransactions": [
      {
        "title": "Common Stock",
        "transactionDate": "2026-04-15",
        "transactionCode": "S",
        "transactionAmount": 50000,
        "transactionPrice": 178.42,
        "sharesOwnedFollowingTransaction": 3128240,
        "ownership": "D"
      }
    ],
    "derivativeTransactions": [],
    "signature": {
      "signatureName": "/s/ Sam Whittington, Attorney-in-Fact",
      "signatureDate": "2026-04-17"
    }
  }
}
```

### GET /api/v1/scrapping/public/{filepath}

Public scraped-file fetch by file path. Reads pre-cached scrape outputs from the public scrapping cache. Used by clients that have a cached file URL from a prior scrape call.

**Token cost:** 10 tokens per call

**Response fields:**
- `content` (string): Raw artifact contents. For text content types (`text/html`, `text/plain`, `application/xml`) returned as decoded UTF-8 text. For binary content types (`application/pdf`, `image/*`) returned as base64-encoded string — decode client-side before consuming. Always non-empty (404 returned when cache miss; never empty-string).
- `content_type` (string): Original SEC `Content-Type` header preserved verbatim (e.g. `text/html; charset=utf-8`, `application/pdf`, `application/xml`, `image/png`). Use this to dispatch the correct decoder client-side — base64 vs UTF-8 — based on the MIME prefix.
- `cached_at` (string): ISO-8601 UTC timestamp when this artifact was first cached at the gateway. The 24-hour TTL is computed from this timestamp — values older than 24h indicate the cache will be revalidated against SEC on the next miss. Use to detect freshness for time-sensitive workflows.
- `size_bytes` (integer): Decoded artifact size in bytes. For text artifacts this is the UTF-8 byte length; for binary artifacts this is the post-base64-decode byte length (i.e. the actual file size, not the inflated base64-string length). Useful for client-side size budgeting (e.g. reject artifacts > 50 MB before downloading).

**Since:** v1.0.0

**Utility:** Fetch a previously-cached SEC filing artifact (raw HTML body, exhibit attachment, XBRL document, image) from FinRadar's gateway cache instead of hitting SEC EDGAR directly. The gateway caches artifacts with a 24-hour TTL — useful for clients that want to avoid SEC's rate limits (10 req/sec per IP) or want deterministic latency for repeated reads of the same artifact. Returns the original SEC `Content-Type` header so binary artifacts (PDFs, images) round-trip correctly. The cache is populated by prior scrape calls — pass a `filepath` you obtained from a previous `/scrapping/extractor` or `/scrapping/form-10` response. For structured item extraction prefer `/scrapping/extractor`; for PDF rendering use `POST /api/v1/scrapping/pdf`.

**Parameters:**
- `filepath` (path, required): Cache-relative path to the artifact (typically mirrors the SEC EDGAR archive path: `edgar/data/{cik}/{accession-no-dashes}/{filename}`). Returned by prior scrape calls in their `cached_filepath` field. URL-encode forward slashes if your HTTP client doesn't auto-encode path params. Returns 404 if the artifact is not cached or has expired past the 24h TTL.

**Sample response:**
```json
{
  "content": "<html><head><title>Form 10-K</title></head>...",
  "content_type": "text/html",
  "cached_at": "2026-05-01T20:55:12.000Z",
  "size_bytes": 481032
}
```

### GET /api/v1/scrapping/sandbox

Scrapping sandbox endpoint. Used for development + integration testing of the scrapping pipeline. Returns synthetic but schema-correct payloads.

**Token cost:** 10 tokens per call

**Response fields:**
- `message` (string): Always the literal string `"sandbox response"` — useful as a smoke-test assertion in CI pipelines (`assert resp.json()['message'] == 'sandbox response'`).
- `request_id` (string): Per-call UUID generated server-side. Surface this in support tickets when integration debugging — operations can grep this directly out of nginx + main_api logs to trace the exact request lifecycle (gateway routing, auth resolution, token debit, response).
- `auth_method` (string): How the gateway authenticated the request: `api_key` (X-API-Key header), `jwt` (Authorization Bearer), or `session` (cookie-based, internal-only). Most production integrations should see `api_key` — anything else may indicate auth-header mis-wiring.
- `cost_debited` (integer): Tokens debited from your balance for this call. Always 10 on the sandbox endpoint. Echoes the `X-Tokens-Charged` response header — useful for asserting your billing-ledger client correctly mirrors the server-side debit.
- `remaining_balance` (integer): Token balance remaining on the account AFTER this debit (i.e. `balance_before - cost_debited`). Use to assert your local balance cache stays in sync with the server-side ledger. When this approaches zero, expect 402 Payment Required on subsequent calls.
- `as_of` (string): ISO-8601 UTC timestamp the response was generated server-side (NOT cached — always reflects request time, since this endpoint is uncached so callers can verify rate-limit + debit semantics on every call).

**Since:** v1.0.0

**Utility:** Verify your API key, the rate-limit headers, and your token-debit ledger end-to-end without consuming production data — call this once on integration day to confirm everything wires up. Returns a deterministic synthetic payload that's schema-identical to what real scrapping endpoints return (same auth headers, same cost-debit semantics, same `request_id` shape). Cost is intentionally non-zero (10 tokens) so the debit shows up in your `/account/transactions` ledger and validates your billing wiring before you run heavier real calls. Idempotent — every call returns the same payload (modulo `request_id`, `as_of`, and `remaining_balance`).

**Sample response:**
```json
{
  "message": "sandbox response",
  "request_id": "a1b2c3d4-...",
  "auth_method": "api_key",
  "cost_debited": 10,
  "remaining_balance": 198432,
  "as_of": "2026-05-01T20:55:12.000Z"
}
```

---

## Daily Index API

Access bulk daily index files.

### GET /api/v1/index

Get daily Master Index.

**Token cost:** 1 token per call

**Response fields:**
- `date` (string): ISO `YYYY-MM-DD` date echoed back. Useful for asserting your client's date construction (timezone bugs are common — confirm against this echo).
- `accessions` (array): Array of accession-row entries for filings accepted on the requested date, sorted by `accepted_at ASC` (chronological — earliest filings first). Empty array on weekends, federal holidays, and dates outside SEC coverage (NOT 404 — clients should treat empty as 'no filings that day' not as an error).
- `accessions[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/api/v1/sec/filings/{accession_number}` for full filing detail or to the form-type-specific drill-down endpoints.
- `accessions[].cik` (string): Filer CIK in 10-character zero-padded form. The stable identifier for joining against subsequent filing-detail or ownership queries.
- `accessions[].form_type` (string): Canonical SEC form type (e.g. `4`, `13F-HR`, `8-K`, `10-K`, `S-1`, `13D/A`). Use to filter the per-day list to the form types your sync pipeline cares about — Form 4 is the highest-volume entry on most days (~80% of weekday filings).
- `accessions[].accepted_at` (string): ISO-8601 UTC timestamp of SEC EDGAR's acceptance moment. Use for intra-day ordering — ET market-hours filings cluster around 09:00-21:00 ET; overnight is quiet (10pm-6am ET no new filings). Expected total range matches the requested calendar date in ET.
- `count` (integer): Total accession count for the date — matches `accessions.length`. Useful for top-level audit metrics ('SEC accepted X filings yesterday'). Typical values: weekdays 5K-50K (off-season vs filing-season); weekends and holidays 0.

**Since:** v1.0.0

**Utility:** The cheapest billed endpoint (1 token) — returns the daily SEC EDGAR master-index for a given date as a flat list of accession numbers + CIKs + form types + acceptance timestamps. Mirrors EDGAR's daily index format (which itself mirrors SEC's `daily-index/full-index/YYYY/QTRn/master.YYYYMMDD.idx` files) but normalized to JSON or CSV and cached for 60 seconds. The right endpoint for: building a local mirror of SEC filings (sync workflows that walk dates sequentially), audit-trail reconciliation, and high-frequency polling cursors that don't want to burn quota. Cheaper than `/api/v1/sec/filings` because it's a flat-list lookup against the daily-index table — no full filtering / pagination machinery.

**Use case:** Syncing a local database with the SEC's daily output for complete coverage.

**Parameters:**
- `date` (query, required): ISO `YYYY-MM-DD` date for which to retrieve the master-index. Returns 404 for future dates and dates before SEC EDGAR's electronic-filing era (1993). Note: weekends + federal holidays return empty `accessions` arrays (SEC doesn't accept filings on those days) — your sync code should handle this without erroring.
- `format` (query, optional, default: json): Output format — `json` (default; structured response with `date` + `accessions[]` + `count`) or `csv` (newline-delimited rows: `accession_number,cik,form_type,accepted_at`). Use CSV for streaming to file or piping to Postgres `\COPY`; use JSON for in-process consumption.

**Sample response:**
```json
{
  "date": "2026-05-01",
  "accessions": [
    {
      "accession_number": "0001127602-26-001234",
      "cik": "0000320193",
      "form_type": "4",
      "accepted_at": "2026-05-01T20:14:32.000Z"
    }
  ],
  "count": 1
}
```

---

## Download API

Download filing documents.

### POST /api/v1/scrapping/pdf

Download filing as PDF, HTML, or plain text. Auto-detects CIK from the SEC URL (or accepts an explicit `cik` body field as fallback). iXBRL viewer links (containing `/ix?doc=`) are normalized server-side.

**Token cost:** 25 tokens per call

**Response fields:**
- `pdf_url` (string): Signed S3 URL for the rendered output (PDF, HTML, or TXT — name is `pdf_url` for legacy reasons regardless of `type`). Valid for 24 hours from `rendered_at` — fetch the file before `expires_at`. Direct download — no auth required for the signed URL itself, the signature handles authorization.
- `page_count` (integer): Number of pages in the rendered output. For PDF: actual page count (10-K outputs typically 100-400, proxy statements 30-150, 8-K with exhibits 5-50). For HTML/TXT: synthetic page count assuming ~3000 chars per page. Useful for client-side cost estimation when feeding the document into LLMs.
- `rendered_at` (string): ISO-8601 UTC timestamp the headless-Chrome render completed. Renders are cached server-side for 7 days keyed by `(link, type)`; values older than 7 days indicate a fresh re-render was triggered (cold path).
- `expires_at` (string): ISO-8601 UTC timestamp the signed S3 URL expires (always `rendered_at + 24h`). After expiry the URL returns 403 — re-call this endpoint to mint a new signed URL (cached render path; 25-token cost still applies but render itself is reused for 7 days).

**Since:** v1.0.0

**Utility:** Render any SEC filing or exhibit URL to a PDF (or HTML / plain text) for archival, investor memos, regulatory submissions, or simply human-readable distribution. Runs a headless Chrome render under the hood — supports the full SEC filing surface including 10-K/10-Q (often 100-400 page documents), 8-Ks with embedded press-release exhibits, proxy statements with vote tabulations, S-1 prospectuses with financial-statement tables. iXBRL viewer URLs (`https://www.sec.gov/ix?doc=/...`) are auto-cleaned to point at the underlying document. Returns a signed S3 URL valid for 24 hours — fetch the actual file from there. The 25-token cost reflects the heavy headless-Chrome render. For raw cached HTML/PDF without re-rendering use `GET /api/v1/scrapping/public/{filepath}`; for surgical item-level extraction use `/scrapping/extractor`.

**Use case:** Generating a PDF for an investor presentation.

**Parameters:**
- `link` (body, required): Direct SEC document URL — the filing's primary HTML document (NOT the index page; must be the actual content URL). Server-side rejected if not on the `sec.gov` domain. iXBRL viewer URLs (`https://www.sec.gov/ix?doc=/...`) are auto-normalized to the underlying document URL — pass either form.
- `type` (body, optional, default: pdf): Output format. `pdf` (default) — full headless-Chrome render with embedded fonts, tables, and images preserved. `html` — cleaned HTML with embedded styles inlined (lighter weight, smaller files). `txt` — plain-text strip-down for NLP pipelines and LLM grounding (loses table structure but tiny files).
- `fileName` (body, optional): Custom filename for the download (extension auto-appended based on `type`). Useful for archival workflows where you want predictable filenames (e.g. `{ticker}-{form_type}-{fiscal_year}`). Defaults to a hash-based filename derived from the source URL when omitted.

**Sample response:**
```json
{
  "pdf_url": "https://finradar-pdf.s3.amazonaws.com/AAPL-10K-2025.pdf?X-Amz-Signature=...",
  "page_count": 124,
  "rendered_at": "2026-05-01T20:55:12.000Z",
  "expires_at": "2026-05-02T20:55:12.000Z"
}
```

---

## Main API Stream

Real-time feed of new SEC filings.

### WS WebSocket (Namespace: /sec)

Listen for new SEC filings (10-K, 8-K, 4, etc.) as they are ingested.

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Always the literal string `"new_filing"` for individual-filing events. For batch events the per-row event field is omitted — the wrapping event name is `new_filings_batch` and each row is a FilingObject.
- `accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Use as a deduplication key client-side — same filing will NOT be re-emitted within a session, but reconnects may replay the last few minutes.
- `cik` (string): Filer CIK in 10-character zero-padded form. Use for client-side per-issuer filtering (e.g. only process filings from your watchlist of CIKs).
- `ticker` (string (nullable)): Resolved ticker from CIK→ticker lookup at filing time (canonical hyphen form). Null when the filer has no public-equity ticker. Useful as the primary filter key for trading-desk consumers.
- `form_type` (string): Canonical form type (`4`, `8-K`, `10-K`, `13F-HR`, `S-1`, etc.). Subscribe to per-form-type rooms (`join: form_4`) to filter server-side and reduce event volume.
- `filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date in ET. Distinct from `accepted_at` — `filed_date` is the calendar date for compliance/UI display; `accepted_at` is the precise timestamp.
- `accepted_at` (string): ISO-8601 UTC timestamp of SEC EDGAR's acceptance moment. Use for intra-day ordering and latency measurement (compare against your client receipt time — should typically be < 60 seconds).
- `filing_url` (string): Canonical SEC EDGAR URL for the filing's index page. Use as the human-readable link in dashboards; for programmatic content access drill into `/api/v1/sec/filings/{accession_number}/html` or `/scrapping/extractor`.

**Since:** v1.0.0

**Utility:** Real-time push stream of newly-accepted SEC filings — connect once via Socket.IO and receive every filing as it lands in our DB (typically within 30-60 seconds of EDGAR acceptance). Drop-in replacement for sec-api.io's WebSocket: same event shape, same field naming, same per-form-type subscription model. The right choice for low-latency trading workflows that need filing-level signals (8-Ks for material events, Form 4s for insider trades, 13D/G for ownership changes) faster than polling the REST endpoints can deliver. Per-form-type rooms (e.g. `join: form_4`) let you filter server-side rather than receiving the firehose. The 100-token cost is a FLAT per-UTC-day connection fee — reconnects on the same UTC day are free, so disconnects (network blips, deploys) don't multiply your costs. For per-message billing semantics, no charge per event — just the daily connection fee.

**Use case:** Triggering an analysis pipeline instantly when a specific company files an 8-K.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query (logs in access logs). 100-token/day fee on first connect of the UTC day. Free-tier OK. `?token=` removed v3.20.2.
- `namespace` (config, required, default: /sec): Socket.IO namespace to connect to. `/sec` is the canonical SEC-filings stream. The connection URL is `<base>/socket.io/?EIO=4&transport=websocket` and the namespace is selected via Socket.IO client API (`io('/sec')`), NOT via URL path.

**Events (server → client):**
- `connect`: Connection established. No payload — fire your `subscribe` action next to filter the firehose.
- `new_filings_batch`: Batch of new filings (1-50 entries). Payload: `Array<FilingObject>` where each FilingObject has the shape described in `responseSchema`. Server batches multiple-filing-bursts into one event when they land within 100ms of each other.

**Sample response:**
```json
{
  "event": "new_filing",
  "accession_number": "0001127602-26-001234",
  "cik": "0000320193",
  "ticker": "AAPL",
  "form_type": "4",
  "filed_date": "2026-05-01",
  "accepted_at": "2026-05-01T20:14:32.000Z",
  "filing_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193"
}
```

---

## Insider API Stream

Real-time insider transaction feed.

### WS WebSocket (Path: /insider-module/socket.io)

Stream of parsed insider transactions and subscription management.

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Event name — typically `"new_transaction"` for individual transactions or `"filing_processed"` for batched per-filing events. Use to dispatch handler functions client-side.
- `transaction_id` (integer): Stable internal primary key from `insiders_transactions`. Use as a deduplication key — the stream MAY replay the most-recent few minutes on reconnect.
- `ticker` (string): Issuer ticker (canonical hyphen form). Pre-filtered server-side against the `tickers` subscription filter when set — clients that subscribed to a watchlist will only receive matching tickers.
- `insider_name` (string): Reporting-person name as filed on Form 4 (typically all-caps EDGAR convention). Casing preserved verbatim; for stable identifiers use `insider_cik`.
- `insider_cik` (string): Reporting-person CIK in 10-character zero-padded form. The stable identifier for cross-event correlation (track all transactions by one insider).
- `standard_type` (string): Normalized transaction type — one of `purchase`, `sale`, `grant`, `exercise`, `gift`, `other`. The high-signal types for trading workflows are `purchase` and `sale`.
- `shares` (number): Share count for the transaction (split-adjusted). Always positive; direction encoded in `standard_type`.
- `price_per_share` (number (nullable)): Per-share transaction price in USD. Null for code-A grants and code-G gifts (no consideration). Pre-filtering by `min_value` excludes null-price events.
- `transaction_value` (number (nullable)): Computed `shares × price_per_share` in USD. Null when price is null. Pre-filtered server-side against the `min_value` subscription filter when set.
- `transaction_date` (string): ISO `YYYY-MM-DD` trade-execution date (NOT the filing date — Form 4 filing has 2-business-day window). For latency-critical workflows compare `transaction_date` against the event-receipt timestamp to gauge market reaction window.
- `sector` (string (nullable)): Sharadar sector classification. Null when ticker is unmapped in Sharadar. Use for client-side sector filtering on top of the server-side ticker filter.
- `industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped.

**Since:** v1.0.0

**Utility:** Real-time push stream of parsed insider transactions (Form 4 / 3 / 5) — receive each transaction within 30-60 seconds of EDGAR acceptance, AFTER our parser has extracted the structured fields (insider name, transaction type, shares, price). Server-side filtering supports `tickers` (whitelist), `min_value` (USD threshold), and `is_c_suite` (CEO/CFO/COO only) so high-value workflows like 'every CEO purchase > $1M' don't require client-side filtering of the firehose. The right choice for low-latency trading desks running event-driven insider-signal strategies — strictly faster than the daily-recommendations endpoint (which lags 24h) and the cluster endpoint (which lags 7 days). 100-token flat per-UTC-day connection fee — reconnects on same UTC day are free.

**Use case:** Monitoring CEO purchases > $1M in real-time.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query. Pair with `path: '/insider-module/socket.io'`. 100-token/day fee. `?token=` removed v3.20.2.
- `path` (config, required, default: /insider-module/socket.io): Custom Socket.IO HTTP path (different from the `/sec` and `/13f` streams which use the default path). Pass to your Socket.IO client constructor as `io(url, { path: '/insider-module/socket.io', auth: {...} })`. Failing to set this will return 404 on the upgrade request.
- `namespace` (config, required, default: /insider-module): Socket.IO namespace. Connect via `io('/insider-module', {...})`. Distinct from the path — namespace is a Socket.IO routing concept (selected via client API), path is the HTTP endpoint for upgrade.

**Events (server → client):**
- `filing_processed`: New Transaction. Payload: { ticker, insider_name, transaction_value, ... }
- `subscribed`: Confirmation of filter update.

**Actions (client → server):**
- `subscribe`: Filter stream.
  ```json
  {
    "tickers": [
      "AAPL",
      "TSLA"
    ],
    "min_value": 100000,
    "is_c_suite": true
  }
  ```

**Sample response:**
```json
{
  "event": "new_transaction",
  "transaction_id": 9341128,
  "ticker": "AAPL",
  "insider_name": "COOK TIMOTHY D",
  "insider_cik": "0001214156",
  "standard_type": "sale",
  "shares": 50000,
  "price_per_share": 175.25,
  "transaction_value": 8762500,
  "transaction_date": "2026-05-01",
  "sector": "Technology",
  "industry": "Consumer Electronics"
}
```

---

## 13F Live Stream

Real-time enriched 13F institutional holdings feed. Receive parsed, CUSIP-enriched filings as they are processed, with subscription filters for CIK, ticker, AUM threshold, and filing type. Supports catch-up on connect and subscription persistence across reconnects.

### WS WebSocket (Namespace: /13f)

Stream of enriched 13F institutional filings with real-time position change analysis. Subscribe to summary (compact ~1KB) or full (complete holdings ~50-500KB) channels. Filters by CIK, ticker held, minimum AUM, and filing type. Catch-up delivery on connect sends recent filings matching your filters. Subscriptions persist across reconnects (7-day TTL).

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Event name — `13f_summary` for compact channel, `13f_holdings` for full channel, `13f_heartbeat` for keep-alive (every 30 seconds), `subscribed` / `subscription_restored` / `unsubscribed` for subscription-state events. Use to dispatch handlers.
- `accession_number` (string): SEC accession in canonical `XXXXXXXXXX-YY-NNNNNN` format. NOTE: the per-event payload uses `accession_no` (underscore form) NOT `accession_number` — see notes block. Use as deduplication key.
- `cik` (string): Filer CIK in 10-character zero-padded form (server-side normalized regardless of input form). Use for client-side per-fund routing.
- `filer_name` (string): Filer name as filed (typically all-caps EDGAR convention). For aliasing to user-friendly names (Buffett vs Berkshire) use `/api/v1/form-13f/filers` with the alias lookup.
- `period_of_report` (string): ISO `YYYY-MM-DD` quarter end (always 03-31 / 06-30 / 09-30 / 12-31). The reporting period the 13F covers.
- `filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date. Compared against `period_of_report` reveals filing-cadence patterns — late-quarter filers hit closer to the 45-day deadline.
- `total_value_usd` (number (nullable)): Reported aggregate portfolio value. IMPORTANT: emitted in SEC's 'thousands' convention — multiply by 1000 for actual USD. Example: `267890123` means $267.9 billion. Null when value not yet computable.
- `holdings_count` (integer (nullable)): Number of position rows in the filing's information table. Null on 13F-NT filings (notice-of-no-table — these always have 0 holdings). Berkshire-shaped books: ~50; index-fund books (Vanguard, BlackRock): 3000-9000+.

**Since:** v1.0.0

**Utility:** Real-time push stream of 13F institutional-holdings filings — receive each filing within ~60 seconds of EDGAR acceptance, FULLY ENRICHED with position-change analysis (categorized into `new`/`closed`/`increased`/`decreased`/`unchanged` with top-20 items per category). Two-channel subscription: `summary` (compact ~1KB with top-10 holdings + statistics — drives dashboard tickers) or `full` (complete ~50-500KB position list with voting authority + investment discretion — drives heavy-analytics consumers). Server-side filtering on CIK whitelist, ticker-held whitelist, minimum AUM, and form type — eliminates client-side firehose handling. Catch-up delivery on connect replays the most-recent 50 filings matching your filters; subscriptions persist across reconnects with 7-day TTL so deploys/network blips don't lose state. The right choice for hedge-fund-tracker dashboards (StockCircle/WhaleWisdom-style) and institutional-flow trading desks. 100-token flat per-UTC-day connection fee.

**Use case:** Monitor when Berkshire Hathaway files a new 13F, track any fund buying NVDA, or alert when a $1B+ fund makes portfolio changes.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query. 100-token/day fee on first connect of the UTC day. Free-tier OK. `?token=` removed v3.20.2.
- `path` (config, required, default: /socket.io): Socket.IO HTTP path. Default `/socket.io` — same as the Main API stream (`/sec` namespace) and DIFFERENT from the Insider stream which uses a custom path. Pass to your client as `io(url, { path: '/socket.io' })`.
- `namespace` (config, required, default: /13f): Socket.IO namespace. Connect via `io('/13f', {...})`. The connection multiplexes onto the same HTTP path as the `/sec` stream — only one TCP socket needed even if you subscribe to both namespaces.

**Events (server → client):**
- `13f_summary`: Compact filing summary (~1KB) with fund metadata, top 10 holdings, and position change statistics. Catch-up events include is_catchup: true.
  ```json
  {
    "event": "13f_summary",
    "fund": {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC"
    },
    "period_of_report": "2024-09-30",
    "filed_at": "2024-11-14T16:04:32",
    "table_value_total": 267890123,
    "accession_no": "0001067983-24-000123",
    "form_type": "13F-HR",
    "is_amendment": false,
    "holdings_count": 42,
    "holdings": [
      {
        "cusip": "037833100",
        "ticker": "AAPL",
        "name": "APPLE INC",
        "value": 91900000,
        "shares": 400000000,
        "rank": 1,
        "percent_portfolio": 34.32,
        "change_shares": -25000000,
        "change_percent": -5.88,
        "title_of_class": "COM",
        "share_type": "SH",
        "put_call": null,
        "figi": "BBG000B9XRY4"
      }
    ],
    "statistics": {
      "new_positions": 3,
      "increased_positions": 8,
      "decreased_positions": 12,
      "closed_positions": 2,
      "unchanged_positions": 17,
      "prior_quarter_available": true
    },
    "timestamps": {
      "rss_ingested_at": "2024-11-14T16:05:00Z",
      "parsed_at": "2024-11-14T16:05:15Z",
      "enriched_at": "2024-11-14T16:05:20Z",
      "emitted_at": "2024-11-14T16:05:21Z"
    },
    "is_catchup": false
  }
  ```
- `13f_holdings`: Full holdings payload (~50-500KB) with ALL positions and categorized position change analysis. Requires 'full' channel subscription.
  ```json
  {
    "event": "13f_holdings",
    "fund": {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC"
    },
    "period_of_report": "2024-09-30",
    "filed_at": "2024-11-14T16:04:32",
    "table_value_total": 267890123,
    "accession_no": "0001067983-24-000123",
    "form_type": "13F-HR",
    "is_amendment": false,
    "holdings": [
      {
        "cusip": "037833100",
        "ticker": "AAPL",
        "name": "APPLE INC",
        "value": 91900000,
        "shares": 400000000,
        "rank": 1,
        "percent_portfolio": 34.32,
        "change_shares": -25000000,
        "change_percent": -5.88,
        "title_of_class": "COM",
        "share_type": "SH",
        "put_call": null,
        "investment_discretion": "SOLE",
        "other_managers": null,
        "voting_authority": {
          "sole": 400000000,
          "shared": 0,
          "none": 0
        },
        "figi": "BBG000B9XRY4",
        "composite_figi": "BBG000B9XRY4"
      }
    ],
    "analysis": {
      "new": {
        "total": 3,
        "items": [
          "... top 20 new positions ..."
        ]
      },
      "closed": {
        "total": 2,
        "items": [
          "... top 20 with value_sold ..."
        ]
      },
      "increased": {
        "total": 8,
        "items": [
          "... top 20 ..."
        ]
      },
      "decreased": {
        "total": 12,
        "items": [
          "... top 20 ..."
        ]
      },
      "unchanged": {
        "total": 17,
        "items": [
          "... top 20 ..."
        ]
      }
    },
    "timestamps": {
      "rss_ingested_at": "2024-11-14T16:05:00Z",
      "parsed_at": "2024-11-14T16:05:15Z",
      "enriched_at": "2024-11-14T16:05:20Z",
      "emitted_at": "2024-11-14T16:05:21Z"
    }
  }
  ```
- `13f_heartbeat`: Server heartbeat every 30 seconds. Use to detect stale connections.
  ```json
  {
    "status": "alive",
    "timestamp": "2024-11-14T16:05:30Z",
    "connected_clients": 5
  }
  ```
- `subscribed`: Acknowledgment after subscribe. Triggers catch-up delivery of recent matching filings.
  ```json
  {
    "status": "success",
    "channels": [
      "summary"
    ],
    "ciks": [
      "1067983"
    ],
    "form_types": [
      "13F-HR"
    ],
    "tickers": [
      "AAPL",
      "NVDA"
    ],
    "min_value": 1000000
  }
  ```
- `subscription_restored`: Sent on reconnect when prior subscription is auto-restored (7-day TTL). Same shape as 'subscribed'. Sync your UI filter state to this.
  ```json
  {
    "status": "success",
    "channels": [
      "summary"
    ],
    "ciks": [
      "1067983"
    ],
    "form_types": [
      "13F-HR"
    ],
    "tickers": [
      "AAPL",
      "NVDA"
    ],
    "min_value": 1000000
  }
  ```
- `unsubscribed`: Acknowledgment after unsubscribe. Subscription reset to defaults (summary channel, no filters).
  ```json
  {
    "status": "success"
  }
  ```

**Actions (client → server):**
- `subscribe`: Set subscription filters. All fields optional — omit or pass empty arrays for 'all'. Triggers catch-up delivery of recent filings matching the new filters. Subscriptions persist across reconnects for 7 days.
  ```json
  {
    "channels": [
      "summary",
      "full"
    ],
    "ciks": [
      "1067983",
      "1318605"
    ],
    "form_types": [
      "13F-HR"
    ],
    "tickers": [
      "AAPL",
      "NVDA",
      "TSLA"
    ],
    "min_value": 1000000000
  }
  ```
- `unsubscribe`: Reset subscription to defaults (summary channel, no filters). Client remains connected and receives all filings on the summary channel.

**Notes:**
- IMPORTANT: table_value_total is in SEC 'thousands' convention. Multiply by 1000 to get actual USD. Example: table_value_total=267890123 means $267.9 billion.
- min_value filter also uses SEC thousands: to filter for funds with $1B+ AUM, send min_value: 1000000 (i.e. $1B / 1000).
- CIKs accept both zero-padded (0001067983) and unpadded (1067983) formats.
- Ticker filter matches any filing whose holdings contain that ticker — independent of CIK filter.
- Catch-up events have is_catchup: true in the payload. Most recent 50 matching filings are replayed on subscribe.
- The accession_no field uses underscores (not accession_number) — this is the dedup key.

**Sample response:**
```json
{
  "event": "new_13f_filing",
  "accession_number": "0000950123-26-001234",
  "cik": "0001067983",
  "filer_name": "BERKSHIRE HATHAWAY INC",
  "period_of_report": "2025-12-31",
  "filed_date": "2026-02-14",
  "total_value_usd": 308000000000,
  "holdings_count": 47
}
```

---

## 13D/G Live Stream

Real-time Schedule 13D/13G beneficial-ownership feed. Receive each parsed 13D/13G filing (and amendments) the moment it is ingested, with subscription filters for issuer, filer, form type, ownership %, amendment/conversion, purpose, and threshold crossings. The pushed body is byte-identical to the 13D/13G filing detail REST response. Supports catch-up on connect and subscription persistence across reconnects (7-day TTL).

### WS WebSocket (Namespace: /13dg)

Stream of parsed Schedule 13D/13G beneficial-ownership filings. A single `13dg_filing` event per filing carries the COMPLETE detail object — identical to GET /api/v1/ownership/beneficial-ownership/filings/{accession} — including all filers, positions (sole/shared voting & dispositive power), classified purpose with intent flags, exhibits, structured items, and (for amendments) the amendment delta block (prior/current %, threshold crossings, conversions). Server-side filtering eliminates client-side firehose handling. Catch-up delivery on connect replays recent matching filings; subscriptions persist across reconnects (7-day TTL).

**Token cost:** 100 tokens per connection-day (flat rate; reconnects on the same UTC day are free)

**Response fields:**
- `event` (string): Event name — `13dg_filing` for a parsed filing, `13dg_heartbeat` for keep-alive (every 30 s), `subscribed` / `subscription_restored` / `unsubscribed` for subscription-state events. Use to dispatch handlers.
- `accessionNo` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Deduplication key.
- `formType` (string): Normalized form type: SC_13D, SC_13D_A, SC_13G, or SC_13G_A.
- `issuer` (object): Subject company — { name, cik, ticker, cusip, classOfSecurities }.
- `aggregatePercent` (number (nullable)): Aggregate percent of class beneficially owned across all reporting persons on the cover page.
- `filers` (array): Reporting persons (one filing may have many — group filings). Each carries identity, reporting-person type, citizenship, group membership, and legal-disclosure flags.
- `positions` (array): Per-filer ownership positions with sole/shared voting and dispositive power, source of funds, and share breakdowns.
- `purpose` (object (nullable)): Classified Item 4 purpose: primary category + 18 boolean intent flags (seeksBoard, seeksMergerAcquisition, …).
- `amendment` (object (nullable)): Present only when isAmendment=true. Prior/current %, share/percent change, threshold crossings (5/10/15/20% + direction), and conversion flags (13G↔13D).

**Since:** v3.38.0

**Utility:** Real-time push stream of Schedule 13D/13G beneficial-ownership filings — receive each filing within seconds of being parsed, FULLY STRUCTURED (the exact same object the detail REST endpoint returns, so no follow-up call is needed). Unlike the quarterly-batched 13F stream, 13D/G filings are event-driven and arrive throughout the year — this is the activist-and-ownership-change firehose. Server-side filtering on issuer (CIK + ticker), filer (CIK + name substring), form type (13D vs 13G vs amendments), minimum ownership %, isAmendment, isConversion, purpose category, and threshold crossings (5/10/15/20%). The right choice for activist-campaign trackers, ownership-change alerting, and 13D/G analytics desks. 100-token flat per-UTC-day connection fee.

**Use case:** Alert the instant an activist files a 13D on a watchlist name, track every new filing by a specific fund (e.g. Icahn, Elliott), or flag any beneficial owner crossing the 5%/10% ownership threshold — in real time, with the full structured filing in a single push.

**Parameters:**
- `api_key` (auth, required): API key. Three methods (first match): Socket.IO `auth.api_key` payload (recommended), HTTP header `X-API-Key` or `Authorization: Bearer`, or `?api_key=` query. 100-token/day fee on first connect of the UTC day, charged separately per namespace. Free-tier OK.
- `path` (config, required, default: /socket.io): Socket.IO HTTP path. Default `/socket.io` — the same path the `/sec` and `/13f` streams use; the connection multiplexes namespaces onto a single TCP socket. Pass to your client as `io(url, { path: '/socket.io' })`.
- `namespace` (config, required, default: /13dg): Socket.IO namespace. Connect via `io('/13dg', {...})`. Carries both Schedule 13D and 13G (and their /A amendments) — filter by `form_types` if you want only one.

**Events (server → client):**
- `13dg_filing`: A parsed Schedule 13D/13G filing. Body is byte-identical to the detail REST response (GET /beneficial-ownership/filings/{accession}) plus an `event` tag. Catch-up replays include is_catchup: true.
  ```json
  {
    "event": "13dg_filing",
    "accessionNo": "0001193125-26-041429",
    "formType": "SC_13D_A",
    "filedAt": "2026-02-14T16:04:32",
    "dateOfEvent": "2026-02-10",
    "isAmendment": true,
    "amendmentNumber": 3,
    "nameOfIssuer": "EXAMPLE CORP",
    "cusip": [
      "123456789"
    ],
    "titleOfSecurities": "Common Stock",
    "issuer": {
      "name": "EXAMPLE CORP",
      "cik": "0000123456",
      "ticker": "EXMP",
      "cusip": "123456789",
      "classOfSecurities": "Common Stock"
    },
    "aggregatePercent": 9.8,
    "aggregateShares": 12345678,
    "filerCategory": "ACTIVE",
    "isConversion": false,
    "filers": [
      {
        "filerName": "EXAMPLE ACTIVIST LP",
        "filerCik": "0009876543",
        "reportingPersonType": "PN",
        "entityType": "entity",
        "citizenship": "DE",
        "isGroupMember": true,
        "filerSequence": 1,
        "unifiedHolderUuid": "…"
      }
    ],
    "positions": [
      {
        "percentOfClass": 9.8,
        "sharesBeneficiallyOwned": 12345678,
        "classOfSecurities": "Common Stock",
        "soleVotingPower": 12345678,
        "sharedVotingPower": 0,
        "soleDispositivePower": 12345678,
        "sharedDispositivePower": 0,
        "sourceOfFunds": [
          "WC"
        ],
        "typeOfReportingPerson": [
          "PN"
        ]
      }
    ],
    "purpose": {
      "purposeCategory": "ACTIVIST",
      "classificationMethod": "RULE_BASED",
      "isPassiveInvestment": false,
      "intentFlags": {
        "seeksBoard": true,
        "seeksMergerAcquisition": false,
        "…": "…"
      },
      "purposeSummary": "…"
    },
    "exhibits": [
      {
        "exhibitNumber": "99.1",
        "exhibitType": "Joint Filing Agreement",
        "documentUrl": "https://www.sec.gov/…"
      }
    ],
    "items": {
      "4": {
        "…": "…"
      }
    },
    "amendment": {
      "amendmentNumber": 3,
      "priorPercent": 5.1,
      "currentPercent": 9.8,
      "percentChange": 4.7,
      "priorShares": 6400000,
      "currentShares": 12345678,
      "sharesChange": 5945678,
      "thresholdCrossings": {
        "crossed5Percent": false,
        "crossed10Percent": false,
        "crossed15Percent": false,
        "crossed20Percent": false,
        "direction": "up"
      },
      "isTypeConversion": false,
      "purposeChanged": false
    },
    "is_catchup": false
  }
  ```
- `13dg_heartbeat`: Server heartbeat every 30 seconds. Use to detect stale connections.
  ```json
  {
    "status": "alive",
    "timestamp": "2026-02-14T16:05:30Z",
    "connected_clients": 3
  }
  ```
- `subscribed`: Acknowledgment after subscribe. Echoes the resolved filter set and triggers catch-up delivery of recent matching filings.
  ```json
  {
    "status": "success",
    "issuer_tickers": [
      "EXMP"
    ],
    "form_types": [
      "SC_13D",
      "SC_13D_A"
    ],
    "min_ownership": 5,
    "is_amendment": null,
    "threshold_crossings": [
      "5",
      "10"
    ]
  }
  ```
- `subscription_restored`: Sent on reconnect when a prior subscription is auto-restored (7-day TTL). Same shape as 'subscribed'. Sync your UI filter state to this.
  ```json
  {
    "status": "success",
    "issuer_tickers": [
      "EXMP"
    ],
    "form_types": [
      "SC_13D"
    ],
    "min_ownership": 5
  }
  ```
- `unsubscribed`: Acknowledgment after unsubscribe. Subscription reset to defaults (all filings, no filters).
  ```json
  {
    "status": "success",
    "message": "Filters cleared, receiving all 13D/G filings"
  }
  ```

**Actions (client → server):**
- `subscribe`: Set subscription filters. All fields optional — omit or pass empty arrays/null for 'all'. Triggers catch-up delivery of recent filings matching the new filters. Subscriptions persist across reconnects for 7 days. All present filters are ANDed; CIKs are leading-zero-insensitive; tickers and purpose categories are case-insensitive; filer_names is a case-insensitive substring match against any filer on the filing; threshold_crossings matches if the filing crossed ANY of the requested levels.
  ```json
  {
    "issuer_ciks": [
      "320193"
    ],
    "issuer_tickers": [
      "AAPL",
      "EXMP"
    ],
    "filer_ciks": [
      "9876543"
    ],
    "filer_names": [
      "icahn",
      "elliott"
    ],
    "form_types": [
      "SC_13D",
      "SC_13D_A"
    ],
    "min_ownership": 5,
    "is_amendment": true,
    "is_conversion": false,
    "purpose_categories": [
      "ACTIVIST"
    ],
    "threshold_crossings": [
      "5",
      "10"
    ]
  }
  ```
- `unsubscribe`: Reset subscription to defaults (all filings, no filters). Client remains connected.

**Notes:**
- A single `13dg_filing` event carries the COMPLETE filing — identical to the detail REST endpoint's `data` object (minus the REST envelope), plus an `event` tag and `is_catchup` flag. No follow-up REST call is needed.
- form_types use the normalized underscore form: SC_13D, SC_13D_A, SC_13G, SC_13G_A. The subscribe action also accepts slashed/spaced forms (e.g. 'SC 13D/A') and normalizes them.
- min_ownership is a PERCENT of class (e.g. 5.0 = 5%), not SEC thousands. A filing with null aggregatePercent never matches a min_ownership filter.
- issuer/filer CIKs accept both zero-padded (0000320193) and unpadded (320193) forms.
- Catch-up events have is_catchup: true. Most recent matching filings are replayed on subscribe (up to 20).
- is_amendment / is_conversion are tri-state: pass true or false to constrain, omit (null) for no constraint.

**Sample response:**
```json
{
  "event": "13dg_filing",
  "accessionNo": "0001193125-26-041429",
  "formType": "SC_13D_A",
  "issuer": {
    "name": "EXAMPLE CORP",
    "cik": "0000123456",
    "ticker": "EXMP"
  },
  "aggregatePercent": 9.8
}
```

---

## Sniper Module

High-level API for scheduling and managing automated filing detections.

### POST /api/v1/sniper/targets

Create a new Sniper Target.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `target_id` (string): Unique target identifier (format: `tgt_<base62-12chars>`). Pass to [POST /api/v1/sniper/targets/{target_id}/stop](/docs/sniper/sniper-module/post-sniper-targets-target-id-stop) for early cancellation, or to [GET /api/v1/sniper/targets](/docs/sniper/sniper-module/get-sniper-targets) when paginating.
- `ticker` (string): Echoed canonical hyphen-form ticker.
- `status` (string): Lifecycle state — `CREATED` (target stored but `start_time` is in the future), `ACTIVE` (currently monitoring; this is the typical immediate-creation state), `STOPPED` (terminal — window expired, manual stop, or filing-hit fired).
- `start_time` (string): ISO 8601 UTC start of the monitoring window. Either explicitly provided or set to creation time.
- `end_time` (string): ISO 8601 UTC end of the monitoring window. Computed from `start_time + duration_minutes` when `duration_minutes` was provided.
- `form_types` (array (nullable)): Echoed form-type filter array. Null when no filter was provided (fires on ANY new filing).
- `webhook_url` (string (nullable)): Echoed webhook URL — either the explicit per-target URL or the account-level default. Null when no webhook is configured (the sniper still fires WS push but skips HTTP webhook).
- `created_at` (string): ISO 8601 UTC creation timestamp (server-side).
- `filing_uuid` (string (nullable)): Foreign key to `filings.uuid` once the hit has been parsed and ingested. Null until the 13F parse pipeline reaches the `parsed` or later `processing_state`.
- `processing_state` (string (nullable)): Parse-pipeline stage, orthogonal to `status`. One of: `detected` (filing URL captured, parse queued), `parsing` (parser running), `parsed` (holdings extracted), `enriched` (OpenFIGI ticker enrichment complete), `no_holdings` (13F-NT or empty holdings table), `parse_failed` (parse error; sniper falls back to bare filing-URL notification). Null until the sniper has fired at least one hit.
- `holdings_count` (integer (nullable)): Number of holdings rows extracted from `form_13f_holdings` when `processing_state` is `parsed` or later. Null when parse has not completed or the filing carries no holdings table (13F-NT).
- `parsed_at` (string (nullable)): ISO 8601 UTC timestamp when the 13F parse pipeline completed (`processing_state` transitioned to `parsed`). Null until parse completes.
- `enriched_at` (string (nullable)): ISO 8601 UTC timestamp when OpenFIGI ticker enrichment completed (`processing_state` transitioned to `enriched`). Null until enrichment completes or if enrichment is skipped.
- `candidate_urls` (array (nullable)): Range-scan window of predicted filing URLs assembled at target creation time — array of `{ accession: string, url: string }` objects. Lets clients pre-render expected filing links before the sniper actually fires. Null when no range-scan was performed.

**Since:** v1.0.0

**Utility:** Schedule a monitoring job for a specific ticker — the Sniper module fires WS push notifications + webhook callbacks the moment a matching SEC filing arrives for the ticker during the active window. Used for time-bounded high-conviction monitoring (e.g. 'watch TSLA for 10-K release tonight') rather than long-running watchlist subscriptions. Each target moves through a 3-state lifecycle: `CREATED` (target stored, not yet active) -> `ACTIVE` (within `start_time .. end_time` window, monitoring) -> `STOPPED` (window expired, manual stop, or filing-hit terminal). Pricing: `cost: 0` to create the target itself, but each TARGET COSTS A TIER PER ACTIVE PERIOD against the customer's plan — see the per-tier sniper allowance in the Account section.

**Use case:** Setting up an automated buy trigger for TSLA immediately upon 10-K release — customer creates a sniper target with `ticker=TSLA`, `duration_minutes=120` to cover the expected after-market filing window. When the 10-K filing hits SEC EDGAR, the Sniper fires (a) a WS push to active connections, (b) an HTTP POST to the customer's configured webhook URL (see [Webhooks > POST {your_webhook_url}](/docs/webhooks/webhooks/post-webhook-url)). Also useful for activist-tracker workflows ('watch ULTA for 13D/G release in next 5 trading days').

**Parameters:**
- `ticker` (body, required): Canonical hyphen-form ticker (e.g. `BRK-A` not `BRK.A`). Server applies the v3.14.2 ticker-normalization shim. Returns 400 when the ticker is unknown to the catalog (run [GET /api/v1/cusip/ticker/{ticker}](/docs/reference-data/cusip-api/get-cusip-ticker) to verify before creating the target).
- `duration_minutes` (body, optional, default: 60): How long to monitor (1-1440). When `start_time` and `end_time` are both omitted, the target activates IMMEDIATELY and runs for `duration_minutes` from creation. When `start_time` is provided, runs from `start_time` for `duration_minutes`. Mutually exclusive with `end_time` (provide either `duration_minutes` OR `end_time`, not both).
- `start_time` (body, optional): ISO 8601 UTC start time. Omit for immediate activation. Useful for scheduling monitoring of upcoming earnings windows (e.g. `start_time=2026-04-30T20:00:00Z` for an after-market AAPL 10-Q expected at 8pm UTC).
- `end_time` (body, optional): ISO 8601 UTC end time. Mutually exclusive with `duration_minutes`. Server returns 400 when both are provided. Maximum window is 24 hours from `start_time`.
- `form_types` (body, optional): Optional array of SEC form types to filter on. Omit to fire on ANY new filing for the ticker; provide to restrict (e.g. `["10-K", "10-Q"]` for earnings-only).
- `webhook_url` (body, optional): Optional customer webhook URL to POST the event payload to when the sniper fires. Falls back to the customer's account-level default webhook URL if omitted (configured under `/account/settings/webhooks`).

**Sample response:**
```json
{
  "target_id": "tgt_abc123def456",
  "ticker": "TSLA",
  "status": "ACTIVE",
  "start_time": "2026-05-02T20:00:00Z",
  "end_time": "2026-05-02T22:00:00Z",
  "form_types": [
    "10-K",
    "10-Q",
    "8-K"
  ],
  "webhook_url": "https://customer.example.com/sniper-callback",
  "created_at": "2026-05-02T19:58:42Z",
  "filing_uuid": null,
  "processing_state": null,
  "holdings_count": null,
  "parsed_at": null,
  "enriched_at": null,
  "candidate_urls": null
}
```

### GET /api/v1/sniper/targets

List all active and past targets.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `targets` (array): Array of sniper target rows owned by the authenticated user. Order: by `created_at DESC` (newest first). Empty array on users who have never created a sniper.
- `targets[].target_id` (string): Unique target identifier (format: `tgt_<base62-12chars>`).
- `targets[].ticker` (string): Canonical hyphen-form ticker.
- `targets[].status` (string): Lifecycle state — `CREATED` / `ACTIVE` / `STOPPED`.
- `targets[].start_time` (string): ISO 8601 UTC start of monitoring window.
- `targets[].end_time` (string): ISO 8601 UTC end of monitoring window.
- `targets[].form_types` (array (nullable)): Form-type filter array (null = fires on any filing).
- `targets[].webhook_url` (string (nullable)): Webhook URL configured for this target. Null when no webhook is configured.
- `targets[].resolution_reason` (string (nullable)): Terminal-state resolution — `window_expired` / `manual_stop` / `filing_hit`. Null while target is `CREATED` or `ACTIVE`.
- `targets[].last_event` (object (nullable)): Most-recent matching SEC filing event for this target — `{ accession_number: string, form_type: string, filed_at: string }` for `filing_hit` resolutions, null otherwise.
- `targets[].created_at` (string): ISO 8601 UTC creation timestamp.
- `targets[].filing_uuid` (string (nullable)): Foreign key to `filings.uuid` once the hit has been parsed and ingested. Null until the 13F parse pipeline reaches the `parsed` or later `processing_state`.
- `targets[].processing_state` (string (nullable)): Parse-pipeline stage, orthogonal to `status`. One of: `detected` (filing URL captured, parse queued), `parsing` (parser running), `parsed` (holdings extracted), `enriched` (OpenFIGI ticker enrichment complete), `no_holdings` (13F-NT or empty holdings table), `parse_failed` (parse error; sniper falls back to bare filing-URL notification). Null until the sniper has fired at least one hit.
- `targets[].holdings_count` (integer (nullable)): Number of holdings rows extracted from `form_13f_holdings` when `processing_state` is `parsed` or later. Null when parse has not completed or the filing carries no holdings table (13F-NT).
- `targets[].parsed_at` (string (nullable)): ISO 8601 UTC timestamp when the 13F parse pipeline completed (`processing_state` transitioned to `parsed`). Null until parse completes.
- `targets[].enriched_at` (string (nullable)): ISO 8601 UTC timestamp when OpenFIGI ticker enrichment completed (`processing_state` transitioned to `enriched`). Null until enrichment completes or if enrichment is skipped.
- `targets[].candidate_urls` (array (nullable)): Range-scan window of predicted filing URLs assembled at target creation time — array of `{ accession: string, url: string }` objects. Lets clients pre-render expected filing links before the sniper actually fires. Null when no range-scan was performed.
- `meta` (object): Pagination + summary block: `{ total: integer, limit: integer, offset: integer, active_count: integer, slots_available: integer }`. `slots_available` shows the user's remaining plan-allocated sniper budget (5 - active_count for Paid tier, 0 for Free tier).

**Since:** v1.0.0

**Utility:** List all sniper targets owned by the authenticated user — active (`status=ACTIVE`), pending (`status=CREATED`), and historical (`status=STOPPED`). The natural backend for a sniper-management dashboard. Filter by status to surface only currently-active monitoring jobs, or list all for an audit trail. Each target row includes lifecycle metadata (status / start / end times), the configured `form_types` filter, the webhook URL, and — for STOPPED targets — the resolution_reason (`window_expired` / `manual_stop` / `filing_hit`) and any associated `last_event` payload summary.

**Use case:** Displaying a dashboard of ongoing monitoring tasks — show the user their currently-active snipers, snipers scheduled to start soon, and recently-stopped snipers with their resolution outcomes. Also useful for SLA audits ('did the sniper for our TSLA earnings target fire correctly?') and for plan-budget visibility ('how many of my 5 paid-tier sniper slots are currently active?').

**Parameters:**
- `status` (query, optional): Filter by lifecycle state — `CREATED` (pending future start) / `ACTIVE` (currently monitoring) / `STOPPED` (terminal). Omit for all states.
- `ticker` (query, optional): Filter by ticker (canonical hyphen form). Useful for 'show me all snipers I've ever created on AAPL' history queries.
- `limit` (query, optional, default: 50): Max targets returned (1-200).
- `offset` (query, optional, default: 0): Pagination offset for chunked retrieval.

**Sample response:**
```json
{
  "targets": [
    {
      "target_id": "tgt_abc123def456",
      "ticker": "TSLA",
      "status": "ACTIVE",
      "start_time": "2026-05-02T20:00:00Z",
      "end_time": "2026-05-02T22:00:00Z",
      "form_types": [
        "10-K",
        "10-Q",
        "8-K"
      ],
      "webhook_url": "https://customer.example.com/sniper-callback",
      "resolution_reason": null,
      "last_event": null,
      "created_at": "2026-05-02T19:58:42Z",
      "filing_uuid": null,
      "processing_state": "detected",
      "holdings_count": null,
      "parsed_at": null,
      "enriched_at": null,
      "candidate_urls": [
        {
          "accession": "0000320193-26-000101",
          "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000101/0000320193-26-000101-index.htm"
        }
      ]
    },
    {
      "target_id": "tgt_xyz789uvw012",
      "ticker": "AAPL",
      "status": "STOPPED",
      "start_time": "2026-05-01T20:00:00Z",
      "end_time": "2026-05-01T22:00:00Z",
      "form_types": [
        "10-Q"
      ],
      "webhook_url": "https://customer.example.com/sniper-callback",
      "resolution_reason": "filing_hit",
      "last_event": {
        "accession_number": "0000320193-26-000064",
        "form_type": "10-Q",
        "filed_at": "2026-05-01T20:14:32Z"
      },
      "created_at": "2026-05-01T19:30:00Z",
      "filing_uuid": "f3a1bc82-7d4e-4c12-9e5f-2a8b6d3c10f7",
      "processing_state": "enriched",
      "holdings_count": 284,
      "parsed_at": "2026-05-01T20:16:04Z",
      "enriched_at": "2026-05-01T20:17:31Z",
      "candidate_urls": null
    }
  ],
  "meta": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "active_count": 1,
    "slots_available": 4
  }
}
```

### POST /api/v1/sniper/targets/{target_id}/stop

Stop an active sniper target.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `target_id` (string): Echoed target identifier.
- `ticker` (string): Echoed canonical hyphen-form ticker.
- `status` (string): Always `STOPPED` after this call (terminal state).
- `resolution_reason` (string): Always `manual_stop` for stop calls (vs `window_expired` for natural-end stops or `filing_hit` for filing-fired stops).
- `stopped_at` (string): ISO 8601 UTC timestamp of the stop event (server-side).
- `slots_available` (integer): Updated remaining plan-allocated sniper-slot budget after the stop. Useful for refreshing the 'X of 5 slots used' indicator in the UI immediately on stop response.

**Since:** v1.0.0

**Utility:** Cancel an active or pending sniper target — moves the target to terminal `STOPPED` state with `resolution_reason='manual_stop'`. Frees the plan-allocated sniper slot for another target. Idempotent (calling stop on an already-STOPPED target returns 200 with the same body, NOT a 409 conflict). Use when (a) the customer has already manually traded the news, (b) the underlying trade thesis has changed, or (c) the customer needs to free a sniper slot for a higher-priority target. Server-side: cancels the underlying timer + queues, removes the target from the active-monitoring set, and (if `webhook_url` is configured) does NOT fire a stop notification to the webhook (stop events are not webhook-broadcasted).

**Use case:** Stopping a sniper monitor early — common scenario: customer set up a TSLA earnings sniper for an after-market window, but TSLA pre-announced earlier and the customer manually traded the news. Stop the sniper to free the plan-allocated slot. Also useful in 'I created the wrong sniper' rollback flows ('I meant AAPL not AAPL.MX').

**Parameters:**
- `target_id` (path, required): Target ID (format: `tgt_<base62-12chars>`). From [POST /api/v1/sniper/targets](/docs/sniper/sniper-module/post-sniper-targets) creation response or [GET /api/v1/sniper/targets](/docs/sniper/sniper-module/get-sniper-targets) listing. Returns 404 when the target_id is unknown OR is owned by a different user (no information leak about other users' targets).

**Sample response:**
```json
{
  "target_id": "tgt_abc123def456",
  "ticker": "TSLA",
  "status": "STOPPED",
  "resolution_reason": "manual_stop",
  "stopped_at": "2026-05-02T21:42:18Z",
  "slots_available": 5
}
```

---

## Payments Module

Programmatic balance management for API usage.

### POST /api/v1/payments/create-intent

Create a Stripe Payment Intent for a one-time top-up of the USD `credit_balance` wallet. EXEMPT (`cost: 0`). Returns the client secret — pass to Stripe Elements client-side to collect card details. Minimum top-up: $5.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx. Always present in the standardised `ApiResponse` wrapper used across `/api/v1/*`.
- `request_id` (string (nullable)): Per-request correlation ID (set by Flask `g.request_id`). Pass in support tickets to look up the call in server logs.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated.
- `data` (object): Payload object containing the Stripe client secret.
- `data.clientSecret` (string): Stripe Payment Intent client secret in `pi_XXXXXXX_secret_YYYYYYY` format. Pass to `stripe.confirmCardPayment(clientSecret)` client-side via Stripe Elements. Single-use — once confirmed (success or failure) it cannot be re-used; create a new intent for a retry. Embeds the user's `uuid` and `type=TOPUP` in Stripe-side metadata so the webhook handler (`_fulfill_topup`) can credit the correct wallet on success.

**Since:** v1.0.0

**Utility:** Server-side wrapper for `stripe.PaymentIntent.create` — initialises a one-time top-up of the user's USD credit balance (the `users.credit_balance` wallet, NOT the token ledger). EXEMPT (`cost: 0`). Returns a Stripe `client_secret` which the frontend passes to Stripe Elements (`stripe.confirmCardPayment(clientSecret)`) to collect card details client-side without the card data ever touching our servers (PCI scope-out). On successful charge, Stripe webhooks `payment_intent.succeeded` to /api/v1/payments/webhook, which calls `_fulfill_topup` to credit the wallet. Use [POST /api/v1/payments/verify](/docs/account/payments-module/post-payments-verify) as a fallback when webhook delivery is delayed/lost. NB: this endpoint creates a Stripe Customer record on first use (idempotent — `stripe_customer_id` is cached on the user row).

**Use case:** Frontend 'Top up balance' modal: user enters $25 → POST here → receives `client_secret` → Stripe Elements form mounted with the secret → user enters card → `confirmCardPayment` fires → Stripe processes → webhook fulfils → modal polls /api/v1/account/balance to show updated balance.

**Parameters:**
- `amount` (body, required): Top-up amount in USD (NOT in cents — server multiplies by 100 internally to send `amount_cents` to Stripe). Minimum 5; below 5 returns 400 with `Minimum top-up is $5`. Float accepted (e.g. 12.50) — fractional cents are rounded by `int(amount_dollars * 100)`.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ1",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": {
    "clientSecret": "pi_3OqK2jK9L8pQ4xZ1_secret_xVZq8nL7aP2kT6sB1mDfHj9vC"
  }
}
```

### POST /api/v1/payments/verify

Manually verify a Stripe Payment Intent and fulfill the top-up if it succeeded. EXEMPT (`cost: 0`). Webhook-fallback path — use when /payments/webhook delivery was delayed or lost. Idempotent: a Transaction already linked to the intent is treated as already-processed.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
- `request_id` (string (nullable)): Per-request correlation ID. Pass in support tickets.
- `timestamp` (string): ISO-8601 UTC timestamp the response was generated.
- `data` (object): Payload — verification result + post-fulfilment balance.
- `data.status` (string): `verified` when the intent was found, security-checked, and (if not yet processed) fulfilled. Returns 400 with `Payment not successful or pending` if the Stripe intent's status is not `succeeded` (e.g. still `processing` or `requires_action`).
- `data.balance` (number): Current `users.credit_balance` in USD AFTER any newly-applied top-up (or unchanged if the verify was a no-op due to prior fulfilment). Use to update the UI balance chip without a separate /account/balance call.

**Since:** v1.0.0

**Utility:** Manual fallback for the webhook fulfilment path. EXEMPT (`cost: 0`). Calls `stripe.PaymentIntent.retrieve(payment_intent_id)` server-side; if the intent's `metadata.user_uuid` matches the authenticated user (security check) AND the status is `succeeded` AND no `Transaction` row already references this intent (idempotency), then `_fulfill_topup` runs to credit the wallet — same code path as the webhook handler, so the result is identical. Use this when Stripe webhook delivery was delayed or lost (network blip, infrastructure outage, webhook secret mismatch); the frontend can poll this endpoint for ~30 seconds after `confirmCardPayment` resolves to give the webhook a chance to fire first, then fall back to verify.

**Use case:** Frontend top-up flow: after `stripe.confirmCardPayment` resolves with `paymentIntent.status === 'succeeded'`, poll /api/v1/account/balance every 2 seconds for up to 30 seconds to see if the webhook credited the wallet. If still not credited, call POST /payments/verify to force-credit. UI shows 'Confirming top-up...' during the poll.

**Parameters:**
- `payment_intent_id` (body, required): Stripe Payment Intent ID returned from POST /payments/create-intent (the `pi_XXXXXX` portion of the `clientSecret`). Must belong to the authenticated user — server cross-checks against the intent's `metadata.user_uuid` and returns 500 with `Payment Intent does not belong to user` on mismatch.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ2",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": {
    "status": "verified",
    "balance": 41.5
  }
}
```

---

## Proxy Management

Manage rotation proxies for high-frequency scraping.

### GET /api/v1/admin/proxyserver

List all active proxies.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Retrieve the current pool of rotation proxies.

**Use case:** Monitoring infrastructure health and verifying available proxy count.

### POST /api/v1/admin/proxyserver

Add a new proxy to the rotation pool.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Register a new proxy for the Sniper module.

**Use case:** Programmatically scaling the proxy pool during high-load periods.

**Parameters:**
- `ip_add` (body, required): Proxy URL (e.g. http://user:pass@host:port)

### DELETE /api/v1/admin/proxyserver/{uuid}

Remove a proxy from rotation.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Decommission a dead or slow proxy.

**Use case:** Automated cleanup of failing proxies detected by health checks.

**Parameters:**
- `uuid` (path, required): Proxy UUID

---

## Admin: Filer Aliases

Manage the curated filer_aliases table that maps well-known fund manager names, nicknames, and abbreviations to their institutional fund CIKs. These aliases power the /form-13f/filers search — e.g. searching 'buffett' finds Berkshire Hathaway, 'ackman' finds Pershing Square.

### GET /api/v1/admin/filer-aliases

List all filer aliases, optionally filtered by search term or CIK.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Browse or search the alias database. Useful for auditing existing mappings before adding new ones.

**Use case:** Checking which aliases already exist for a fund, or finding all aliases that contain 'tiger'.

**Parameters:**
- `q` (query, optional): Search aliases by name (case-insensitive substring match)
- `cik` (query, optional): Filter aliases by CIK (exact match)

### POST /api/v1/admin/filer-aliases

Add a new filer alias mapping.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Create a new alias that maps a well-known name or abbreviation to a fund CIK. Once added, the alias is immediately searchable in the /form-13f/filers endpoint.

**Use case:** Adding 'Uncle Warren' as an alias for Berkshire Hathaway (CIK 0001067983), or 'RenTech' for Renaissance Technologies.

**Parameters:**
- `alias_name` (body, required): The alias string (e.g. 'buffett', 'ackman', 'RenTech')
- `cik` (body, required): The fund CIK this alias maps to (e.g. '0001067983')
- `alias_type` (body, optional): Category of alias (e.g. 'manager_name', 'nickname', 'abbreviation')
- `notes` (body, optional): Optional notes about this alias

### PUT /api/v1/admin/filer-aliases/:id

Update an existing filer alias by its ID.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Modify the alias name, type, or notes for an existing alias mapping.

**Use case:** Correcting a typo in an alias name, changing alias_type from 'nickname' to 'manager', or adding notes.

**Parameters:**
- `id` (path, required): Alias record ID
- `alias_name` (body, optional): Updated alias name
- `alias_type` (body, optional): Updated alias type (manager, founder, nickname, ticker, abbreviation)
- `notes` (body, optional): Updated notes

### DELETE /api/v1/admin/filer-aliases/:id

Delete a filer alias by its ID.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Remove an incorrect or outdated alias mapping.

**Use case:** Cleaning up a misattributed alias or removing a duplicate entry.

**Parameters:**
- `id` (path, required): Alias record ID

### POST /api/v1/admin/filer-aliases/bulk

Bulk add multiple filer aliases in one request.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Efficiently seed or update the aliases table with multiple mappings at once.

**Use case:** Initial seeding of 50+ well-known fund manager aliases, or importing aliases from a spreadsheet.

**Parameters:**
- `aliases` (body, required): Array of alias objects, each with: alias_name (required), cik (required), alias_type (optional), notes (optional)

---

## Form 13F API

Complete SEC Form 13F institutional holdings API. Covers raw filings search, portfolio analysis, fund reports, market-wide aggregation, and CUSIP chain tracking. All endpoints consolidated under /api/v1/form-13f/. Legacy paths (/api/v1/institutional/* and /api/v1/13f/*) redirect here automatically.

### GET /api/v1/form-13f/fund/{cik}

Get detailed fund report with paginated holdings, quarter selection, filing metadata, and raw 13F fields.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `fund` (object): Fund identity block — `{ cik, name, signing_officer, latest_filed_at }`. The `cik` is echoed back as a 10-char zero-padded string per the Phase 47-era zero-padding normalization (handles 6/7/10-char input forms). `name` is preserved verbatim from the most recent 13F-HR filing (typically all-caps in EDGAR convention).
- `period` (string): ISO `YYYY-MM-DD` reporting period end (always a calendar quarter end: 03-31, 06-30, 09-30, 12-31). 13F-HR is filed quarterly, due within 45 days of this date. Echoed back from the request — when omitted from input, defaults to the latest available quarter for this fund.
- `filing` (object): Filing-level metadata for this `(cik, period)` row: `{ accession_no, form_type, is_amendment, filed_at, table_value_total, table_entry_total, value_corrected, correction_method, original_value_total }`. `accession_no` is the 18-char dashed format `XXXXXXXXXX-YY-NNNNNN`. `value_corrected` flags Plan 51 holdings-quality corrections (USD-thousands → USD direct normalization for pre-2022-09 filings). `table_value_total` is in USD (post-correction).
- `filing.accession_no` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0001067983-26-000123`). Pass to `POST /api/v1/form-13f/holdings` (via `accessionNo:...` query) or `GET /api/v1/sec/filings/{accession_number}` for the raw filing artifact.
- `filing.form_type` (string): SEC form type — `13F-HR` (original holdings report) or `13F-HR/A` (amendment). 13F-NT (notice-of-no-information) filings are skipped server-side and never surface here. Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `filing.is_amendment` (boolean): True when `form_type` ends with `/A` — i.e. this row replaces an earlier original 13F-HR for the same `(cik, period)`. Amendments collapse to the latest filing per `(cik, period)` so the `holdings` array reflects the corrected book.
- `holdings` (array): Paginated array of position rows — one per CUSIP. Sorted by `value_usd DESC` by default. Each row carries the raw 13F fields preserved as filed (title_of_class, share_type, put_call, investment_discretion, voting_authority, figi). Page size controlled by `limit`/`size`; offset by `offset`/`from`.
- `holdings[].cusip` (string): 9-character CUSIP as filed. The natural primary key for the position. 8-char CUSIPs (missing check digit) are zero-padded server-side. Apple's canonical CUSIP is `037833100`.
- `holdings[].ticker` (string (nullable)): Resolved ticker from CUSIP→ticker mapping via `cusip_security_catalog`. Null when (a) the security has no ticker (debt instruments, private placements), (b) the CUSIP is unmapped (~3% of rows in steady state), or (c) the issuer was delisted before our enrichment ran. Multi-class issuers preserve the actual filed class (e.g. `BRK-A` vs `BRK-B`).
- `holdings[].name_of_issuer` (string): Issuer name AS FILED on the 13F (typically all-caps in EDGAR convention, e.g. `APPLE INC`). NOT enriched from Sharadar — for the canonical name use the `cusip_security_catalog` lookup.
- `holdings[].title_of_class` (string): Security class designation as filed (e.g. `COM` for common stock, `CL A` for class A, `PFD` for preferred). Preserved verbatim from EDGAR. Useful for distinguishing share classes when an issuer has multiple (e.g. Berkshire `BRK-A` vs `BRK-B`).
- `holdings[].share_type` (string): Share-vs-principal indicator: `SH` (shares — equity) or `PRN` (principal — debt). Critical for unit-correctness: `SH` rows have share-count semantics; `PRN` rows have face-value semantics. Frontends should split equity from debt views using this field.
- `holdings[].put_call` (string (nullable)): Derivative position type: `Put`, `Call`, or null for common stock. Options positions are a small minority of 13F filings (most managers report only equity); when present, treat them as a separate signal class — option holdings can dwarf the common-stock book in notional value. Only surfaces non-null values when `include_options=true` is passed; default-mode rows are long-equity-only and `put_call` is always null.
- `holdings[].is_option` (boolean): Phase 68: explicit options-vs-equity classifier on every row regardless of mode. Always `false` in default-mode responses (long-equity-only). When `include_options=true` is passed, options rows return `is_option=true` (with `put_call` populated); equity rows return `is_option=false`. Lets clients filter client-side without inspecting `put_call`. Strictly additive — pre-Phase-68 callers see this as a new always-false field.
- `holdings[].shares` (number): Share count as reported on the 13F. NOT split-adjusted server-side (preserves the as-filed view) — for split-adjusted aggregations use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/ticker-research/...). Phase 52 split-adjustment work is shipped end-to-end on the aggregation surface; raw rows here remain as-filed for audit fidelity.
- `holdings[].value_usd` (number): Total position USD value AS FILED. Pre-Q3 2022 SEC instruction was 'value reported in thousands'; post-Q3 2022 instruction is 'value reported in actual dollars' — FinRadar's parser auto-detects and normalizes via the `holdings_quality` side-table (Plan 51). The `filing.value_corrected` flag surfaces when correction was applied.
- `holdings[].investment_discretion` (string): Discretion category: `SOLE` (sole investment discretion), `SHARED-DEFINED`, `SHARED-OTHER`, or `NONE`. Indicates the manager's level of control over the position. `SOLE` is the most common in active hedge-fund books.
- `holdings[].voting_authority` (object): Voting authority breakdown — `{ sole, shared, none }`. Sum equals `shares` for equity positions. Useful for distinguishing actively-voted positions (`sole > 0`) from custodial-style holdings (`none > 0`).
- `holdings[].figi` (string (nullable)): OpenFIGI security identifier from CUSIP→FIGI enrichment (when `OPENFIGI_API_KEY` is configured). Null for unmapped CUSIPs. The FIGI is the cross-vendor instrument key used by Bloomberg, Refinitiv, and other market-data providers.
- `analysis` (object (nullable)): Position-change analysis arrays (top 20 per category): `{ new_buys, closed, increased, decreased, unchanged }`. Each array is sorted by `value_usd DESC`. Computed from the prior-quarter `(cik, period - 3M)` baseline. Null for funds with no prior-quarter row (initial filing).
- `sector_allocation` (array (nullable)): Per-sector breakdown of portfolio value: `[{ sector, total_value_usd, position_count, pct_of_portfolio }, ...]` sorted by `total_value_usd DESC`. Sectors are Sharadar-classified. Null when sector enrichment hasn't completed for this filing yet.
- `activity` (object (nullable)): Phase 68.3 (since v3.39.0). Present ONLY when `?include_activity=true` (and `detail=full`). Fund-level quarter-over-quarter 13F activity metrics (WhaleWisdom-parity), all fund-wide (unaffected by `status=`): `market_value` / `prior_market_value` (USD total, current and prior quarter) and `market_value_change_pct`; `inflow_value` (USD of newly-opened positions) / `outflow_value` (prior USD of fully-exited positions); `net_flow_pct` = (inflow − outflow) / market_value × 100; `turnover_pct` = (new_count + sold_out_count) / (holdings_count + sold_out_count) × 100 — the denominator is WhaleWisdom note 1's 'total # of holdings for the quarter' = positions still held PLUS the names fully sold out this quarter (corrected in v3.43.0, PR #422; the prior `/ holdings_count` dropped the sold-out names and over-reported turnover, e.g. Berkshire 2026-03-31 read 65.52% instead of 42.22%); `turnover_alt_pct` = min(inflow, outflow) / market_value × 100; the bucket counts `new_count` / `increased_count` / `decreased_count` / `unchanged_count` / `sold_out_count` and `holdings_count` (current positions = new+increased+decreased+unchanged); and `time_held_top10_qtrs` / `time_held_top20_qtrs` / `time_held_all_qtrs` — average holding period in quarters (days ÷ 91.25) over the top-10 / top-20 / all positions by value, sourced best-effort from the `sec_13f_holdings_analytics` cache (`null` until that cache is warm for this `(cik, period)`). `has_prior_quarter` is `false` on a fund's first filing, in which case every prior-dependent metric (`prior_market_value`, `market_value_change_pct`, `net_flow_pct`, `turnover_pct`, `turnover_alt_pct`) is `null` while the counts remain populated.
- `meta` (object): Pagination metadata: `{ pagination: { total, limit, offset, has_more } }`. `total` reflects the full holdings count for this `(cik, period)` (not just the page); `has_more` is convenience-flag for cursor-style UI.

**Utility:** Retrieve portfolio for any quarter, sector allocation, and position changes (new, closed, increased, decreased). Response includes filed_at timestamp, table_value_total, filing-level fields (accession_no, form_type, is_amendment, table_entry_total, value_corrected, correction_method, original_value_total), and per-holding raw 13F fields (title_of_class, share_type, put_call, investment_discretion, voting_authority, figi). Holdings are paginated; analysis arrays show top 20 per category.

**Use case:** Building a dashboard to track Berkshire Hathaway's latest portfolio moves, comparing Q3 vs Q4 holdings, identifying options positions via put_call, distinguishing bonds (PRN) from shares (SH), or paging through Vanguard's 4,000+ holdings.

**Parameters:**
- `cik` (path, required): Fund CIK (e.g. 0001067983)
- `period` (query, optional): Report period date YYYY-MM-DD (e.g. 2024-09-30). Defaults to latest.
- `limit` (query, optional, default: 50): Holdings per page (1-200). Accepted alias: `size`.
- `offset` (query, optional, default: 0): Pagination offset. Accepted alias: `from`.
- `include_options` (query, optional, default: false): When `true`, response includes options positions (puts/calls) alongside long-equity holdings — `holdings[].is_option=true` and `holdings[].put_call='Put'/'Call'` mark each option row. Default `false` returns long-equity-only (matches pre-Phase-68 behavior of every existing caller — hedge-fund-search inline reports, screener, basket aggregator, /13f WebSocket). Cache key is keyed by this flag, so the two response shapes cache independently. Most filers carry zero options (Berkshire, Vanguard, BlackRock); options-heavy books include Scion Asset Mgmt (CIK 1649339), Pershing Square, etc.
- `include_analytics` (query, optional, default: false): Phase 69 Plan 05 (since v3.23.0). When `true`, each `holdings[]` row gains 11 per-position cost-basis analytics fields: `avg_buy_price`, `current_price`, `cost_basis`, `market_value`, `unrealized_pnl`, `unrealized_pnl_pct`, `holding_period_days`, `holding_period_quarters`, `first_added`, `last_share_delta`, `last_transaction_quarter` (plus `sector` when /fund/{cik}'s row doesn't already carry one). Same VWAP-of-quarterly-closes methodology as the now-deprecated `/holdings-analytics` route — see that endpoint's responseSchema entries for per-field semantics, units, and null cases. Default `false` returns the byte-identical pre-Phase-69 response shape (no new fields). Cache key includes this flag as a dimension so the four combinations (no flags / opts / analytics / both) cache independently. If `CostBasisService` raises for an exotic CIK, the analytics decoration is skipped with a warning log — the default `/fund/{cik}` response is never broken by an analytics failure. Same opt-in flag pattern as `?include_options=true` (PR #149).
- `options_only` (query, optional, default: false): Phase 73-02 (since v3.24.0). When `true`, response carries ONLY options rows (`holdings[].is_option=true` with `put_call='Put'/'Call'`) — equity is excluded. Lets clients fetch the Options-tab payload for `/filer/<slug>-<cik>/` without pulling the full 2K-5K-row equity book (~50 options rows for option-heavy filers like Duquesne / Scion / Pershing Square; 0 rows for Berkshire / Vanguard / BlackRock who report no options). Overrides `include_options` when both are sent (`options_only` is a strict subset). Default `false` keeps the byte-identical pre-Phase-73-02 behavior for every existing caller. Cache key partitions independently — flipping the flag triggers a cold path on first request, with `:options-only` suffix replacing `:opts` so the three response shapes (default / `:opts` / `:options-only`) never collide. Pairs with the Phase 73-01 matview-dedup fix (PR #181, since v3.24.0) which recovered ~1.49M previously-hidden option rows for filers holding common+options on the same CUSIP — both shipped together so options-heavy filer pages render the correct count in one efficient call.
- `sort_by` (query, optional, default: value): Phase 72-02 + 72-03 (since v3.23.0). Server-side sort column applied to the FULL `holdings[]` list BEFORE pagination — i.e. cross-page sort, not per-page. Default `value` (alias `market_value`) sorts by position USD value descending. Whitelist: `ticker`, `name`, `share_type`, `value`/`market_value`, `rank`, `percent_portfolio`, `shares`, `status`, `change_percent` (the 9 columns visible on the filer page) PLUS — when `include_analytics=true` is set — 9 analytics-decorator fields: `unrealized_pnl_pct`, `unrealized_pnl`, `cost_basis`, `avg_buy_price`, `current_price`, `holding_period_days`, `holding_period_quarters`, `first_added`, `last_transaction_quarter`. Date keys (`first_added`, `last_transaction_quarter`) compare lexicographically — equivalent to chronological for ISO `YYYY-MM-DD`. Invalid `sort_by` silently falls back to `value desc` so callers never see 4xx for typos. Cache key partitions on `(sort_by, sort_order)`; the historic default (`value`, `desc`) omits the suffix so pre-Phase-72 cache entries remain byte-for-byte valid. Powers the column-header click-to-sort behavior on the `/filer/<slug>-<cik>/` page for BlackRock-class filers (5K+ holdings) where client-side sort is impossibly large.
- `sort_order` (query, optional, default: desc): Phase 72-02 (since v3.23.0). Sort direction: `asc` (ascending) or `desc` (descending). Default `desc`. Invalid values silently fall back to `desc`. Cache key includes this dimension when combined with non-default `sort_by`.
- `status` (query, optional, default: all): PR #285 (since v3.37.0). Server-side filter that restricts the `holdings[]` list to a single position-classification bucket — applied AFTER `_compute_analysis` assigns each holding its `status`, BEFORE sort + pagination. Whitelist: `all` (default — no filter, byte-for-byte pre-PR behavior), `new`, `increased`, `decreased`, `unchanged`, `closed`. Unknown values silently fall through unchanged (same convention as `sort_by`). `closed` is special-cased — closed positions are absent from the current `holdings` list (they were in the prior quarter but not current), so the handler synthesizes standard-shape rows from the `closed_list` analysis bucket with `shares=0`, `value=0`, `change_percent=-100`, `status='Closed'`, and the prior values preserved as `shares_sold` / `value_sold` so the frontend can render them into the same holdings table. `meta.pagination.total` reflects the FILTERED count (so the infinite-scroll holdings table on `/filer/<slug>-<cik>/` paginates correctly across status pills); `analysis.*.total` continues to reflect the UNFILTERED per-category totals (so the pill counts stay accurate regardless of which filter is active). Cache key partitions on `status`; the default `all` omits the suffix so pre-PR cache entries remain byte-for-byte valid. Mirrors the precedent on `GET /api/v1/tickers/{ticker}/holders?status=`.
- `include_activity` (query, optional, default: false): Phase 68.3 (since v3.39.0). When `true`, the response gains a fund-level `activity` object (see the `activity` responseSchema entry) with WhaleWisdom-parity quarter-over-quarter portfolio metrics: prior-quarter market value + % change, inflow/outflow USD, net-flow %, turnover % and turnover-alt %, the new / sold-out / increased / decreased / unchanged position counts, and average holding period (in quarters) for the top-10 / top-20 / all positions by value. Computed REQUEST-TIME from the current + prior-quarter holdings the report already loads — no extra quarter fan-out — plus at most ONE indexed lookup into the `sec_13f_holdings_analytics` warm cache for the time-held averages. Fund-wide regardless of any `status=` filter (the metrics are snapshotted before `status=` narrows `holdings[]`). On a fund's first 13F filing the prior-dependent metrics are `null`. The three `time_held_*` fields are best-effort: `null` until the Phase 79 cost-basis analytics cache is warm for this `(cik, period)` (the other activity scalars are always populated). Applies to `detail=full` only — the `summary` shape omits the block. Default `false` returns the byte-identical pre-Phase-68.3 response (no `activity` key). Cache key partitions on this flag (`:activity` suffix) so activity / non-activity responses cache independently and every pre-flag entry stays valid. Same opt-in flag pattern as `include_options` / `include_analytics`.

**Sample response:**
```json
{
  "fund": {
    "cik": "0001067983",
    "name": "BERKSHIRE HATHAWAY INC",
    "signing_officer": "WARREN E BUFFETT",
    "latest_filed_at": "2026-02-14T15:32:11.000Z"
  },
  "period": "2025-09-30",
  "filing": {
    "accession_no": "0001067983-25-000452",
    "form_type": "13F-HR",
    "is_amendment": false,
    "filed_at": "2025-11-14T17:08:23.000Z",
    "table_value_total": 308000000000,
    "table_entry_total": 47,
    "value_corrected": false,
    "correction_method": null,
    "original_value_total": null
  },
  "holdings": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "name_of_issuer": "APPLE INC",
      "title_of_class": "COM",
      "share_type": "SH",
      "put_call": null,
      "is_option": false,
      "shares": 300000000,
      "value_usd": 78240000000,
      "investment_discretion": "SOLE",
      "voting_authority": {
        "sole": 300000000,
        "shared": 0,
        "none": 0
      },
      "figi": "BBG000B9XRY4"
    }
  ],
  "analysis": {
    "new_buys": [],
    "closed": [],
    "increased": [],
    "decreased": [
      {
        "ticker": "AAPL",
        "change_shares": -10000000,
        "change_pct": -3.2
      }
    ],
    "unchanged": []
  },
  "sector_allocation": [
    {
      "sector": "Technology",
      "total_value_usd": 80000000000,
      "position_count": 2,
      "pct_of_portfolio": 26
    },
    {
      "sector": "Financial Services",
      "total_value_usd": 95000000000,
      "position_count": 8,
      "pct_of_portfolio": 30.8
    }
  ],
  "meta": {
    "pagination": {
      "total": 47,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  }
}
```

### GET /api/v1/form-13f/fund/{cik}/periods

List all available report periods for a fund.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `cik` (string): Fund CIK as a 10-character zero-padded string. Echoed back from the request — useful for asserting your client passed the CIK you intended after the server's CIK-padding normalization (handles 6/7/10-char input forms).
- `periods` (array): Array of ISO `YYYY-MM-DD` quarter-end dates for which this fund has a parsed 13F-HR (or 13F-HR/A) filing in FinRadar's coverage. Sorted newest-first. Always calendar quarter ends (03-31, 06-30, 09-30, 12-31). Coverage starts ~2013-Q1 for active filers; older dates indicate longer-standing managers like Berkshire Hathaway (FinRadar's coverage start). Empty array when the CIK is registered but has never filed a 13F-HR.
- `periods[]` (string): Single ISO `YYYY-MM-DD` reporting period end. 13F-HR is filed quarterly within 45 days of this date. Pass back as the `period` query param to [GET /api/v1/form-13f/fund/{cik}](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-cik) to drill into that quarter's holdings.
- `latest_period` (string (nullable)): Convenience pointer to `periods[0]` (the newest quarter). Null on empty array. Useful for quick 'latest filed quarter' lookups without indexing into the array client-side.
- `count` (integer): Total number of distinct quarters in `periods[]`. Active large managers (Berkshire, Vanguard, BlackRock) have 50+ quarters going back to 2013; newer managers have lower counts.

**Utility:** Discover which quarters are available before querying a specific period. Returns dates sorted newest-first.

**Use case:** Populating a quarter-selector dropdown (Q3 2024, Q2 2024, ...) in the hedge fund analyzer UI.

**Parameters:**
- `cik` (path, required): Fund CIK (e.g. 0001067983)

**Sample response:**
```json
{
  "cik": "0001067983",
  "periods": [
    "2025-12-31",
    "2025-09-30",
    "2025-06-30",
    "2025-03-31",
    "2024-12-31"
  ],
  "latest_period": "2025-12-31",
  "count": 5
}
```

### POST /api/v1/form-13f/fund/bulk

Bulk query multiple funds in one request (basket analysis).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `period` (string): ISO `YYYY-MM-DD` reporting period applied to all funds in the bulk query (always a calendar quarter end). When omitted from input, defaults to the latest quarter for which ALL requested CIKs have a filing — funds missing a filing for this period appear in the `funds` array with `status: 'no_filing'`.
- `detail` (string): Echoed back from the request. `summary` (default) returns each fund's top-10 holdings + portfolio totals; `full` returns the complete holdings array per fund (paginated via `size`/`from`). Use `summary` for basket-overview UIs; `full` for deep-dive analysis where you need every position.
- `funds` (array): Array of per-fund report rows — one entry per requested CIK. Order matches the order of CIKs in the request. Funds without a filing for the requested `period` appear here with `status: 'no_filing'` and `holdings: []` rather than being silently dropped — clients can detect coverage gaps.
- `funds[].cik` (string): 10-char zero-padded CIK echoed from the request. Use as a stable join key in client-side basket aggregation. Berkshire = `0001067983`, Bridgewater = `0001350694`, Renaissance = `0001037389`.
- `funds[].name` (string): Registrant name AS FILED on the most recent 13F-HR (typically all-caps in EDGAR convention). NOT alias-normalized — for the user-friendly alias (e.g. 'Warren Buffett') consult the `filer_aliases` admin table via [GET /api/v1/form-13f/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers).
- `funds[].status` (string): Per-fund result status: `ok` (filing found and parsed), `no_filing` (CIK exists but no 13F for this period), `unknown_cik` (CIK not in our 13F filer universe). Frontends should branch on this before reading `holdings`.
- `funds[].portfolio_value_usd` (number (nullable)): Total portfolio USD value (sum of `holdings[].value_usd`, post-Plan-51 thousands-vs-actual normalization). Null when `status != 'ok'`. Berkshire Q4 2025 ≈ $310B; mid-tier hedge funds $1-10B; family offices $50M-1B.
- `funds[].holdings_count` (integer (nullable)): Number of position rows in this fund's filing for the requested period. Null when `status != 'ok'`. Berkshire-shaped books: ~50; mid-tier hedge funds: 50-500; index-fund books (Vanguard, BlackRock): 3000-9000+.
- `funds[].holdings` (array (nullable)): Position rows — top 10 by `value_usd` when `detail=summary`, OR paginated full list when `detail=full`. Each row carries the same shape as `GET /api/v1/form-13f/fund/{cik}` holdings: `{ cusip, ticker, name_of_issuer, shares, value_usd, put_call, ... }`. Null when `status != 'ok'`.
- `funds[].error` (string (nullable)): Per-fund error message — populated only when `status` is `no_filing` or `unknown_cik`. Examples: `'No 13F-HR filing for period 2025-09-30'`, `'CIK 0009999999 not found in 13F filer universe'`. Use to surface gaps in basket coverage.
- `meta` (object): Bulk-query metadata: `{ requested_count, ok_count, no_filing_count, unknown_cik_count, detail }`. Useful for surfacing coverage stats: 'Basket: 15 of 20 funds reporting for Q4 2025'.

**Utility:** Retrieve reports for up to 20 funds at once. Supports configurable detail level: 'summary' (metadata + top 10 holdings) or 'full' (complete report with analysis).

**Use case:** Building a 'basket' of hedge funds (e.g. Tiger Global + Citadel + Renaissance) and generating an aggregated portfolio view without 20 sequential API calls.

**Parameters:**
- `ciks` (body, required): Array of CIK strings, max 20. e.g. ["1067983", "1649339"]
- `period` (query, optional): Report period YYYY-MM-DD. Applied to all funds.
- `detail` (query, optional, default: summary): 'summary' or 'full'. Summary returns top 10 holdings only.
- `size` (query, optional, default: 50): Holdings per page (only for detail=full). Accepted alias: `limit`.
- `from` (query, optional, default: 0): Pagination offset (only for detail=full). Accepted alias: `offset`.

**Sample response:**
```json
{
  "period": "2025-09-30",
  "detail": "summary",
  "funds": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "status": "ok",
      "portfolio_value_usd": 308000000000,
      "holdings_count": 47,
      "holdings": [
        {
          "cusip": "037833100",
          "ticker": "AAPL",
          "name_of_issuer": "APPLE INC",
          "shares": 300000000,
          "value_usd": 78240000000,
          "put_call": null
        }
      ]
    },
    {
      "cik": "0001037389",
      "name": "RENAISSANCE TECHNOLOGIES LLC",
      "status": "ok",
      "portfolio_value_usd": 78000000000,
      "holdings_count": 3850,
      "holdings": [
        {
          "cusip": "594918104",
          "ticker": "MSFT",
          "name_of_issuer": "MICROSOFT CORP",
          "shares": 4500000,
          "value_usd": 1898000000,
          "put_call": null
        }
      ]
    }
  ],
  "meta": {
    "requested_count": 2,
    "ok_count": 2,
    "no_filing_count": 0,
    "unknown_cik_count": 0,
    "detail": "summary"
  }
}
```

### GET /api/v1/form-13f/fund/{cik}/cusip/{cusip}/history

Per-quarter share + value history for a single (fund, CUSIP) position — the chronological trail of one security held by one filer across every 13F-HR quarter we have on file.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `cik` (string): 10-char zero-padded fund CIK echoed from the request — useful for asserting your client passed the CIK you intended after CIK-padding normalization.
- `cusip` (string): Canonical CUSIP echoed from the request (uppercase-normalized server-side).
- `ticker` (string (nullable)): Resolved ticker via `cusip_mappings` (best-effort LEFT JOIN). Null when the CUSIP is unmapped (~3% in steady state) or for delisted issuers without a current ticker.
- `name` (string (nullable)): Issuer name (`cusip_mappings.security_name`, typically all-caps EDGAR convention — e.g. `APPLE INC`). Null when no mapping row exists.
- `quarters` (integer): Convenience pointer to `history.length` — number of distinct quarter-end dates in the response. Active long-term holdings show 30+ quarters (Berkshire AAPL = ~40 quarters since 2016-Q1); new positions show 1-2 quarters.
- `split_adjusted` (boolean): True when at least one stock-split factor was applied to `history[].shares` (i.e. the security split at some point after one of the reported quarters). False when no splits were found for the ticker or the ticker could not be resolved (in which case `shares` == `shares_raw` for every row).
- `splits` (array): The split events (from the Sharadar `all_stocks_actions` feed, ticker-keyed) used to forward-adjust shares — `[{ date: 'YYYY-MM-DD', ratio: number }]`, e.g. AAPL = `[{date:'2014-06-09',ratio:7},{date:'2020-08-31',ratio:4}]`. Empty `[]` when none apply. Provided for transparency/reconciliation.
- `history` (array): Per-quarter rows sorted by `quarter_date` ASC (oldest first). One entry per `period_of_report` where this CUSIP appears in the fund's chosen 13F filing for that quarter. Positions that were fully sold (closed) simply stop appearing — there is no synthetic 0-share row.
- `history[].quarter_date` (string): ISO `YYYY-MM-DD` of the filing's `period_of_report` (always a calendar quarter end: 03-31, 06-30, 09-30, 12-31).
- `history[].shares` (integer): Sum of `number_of_shares` across all sub-advisor partitions for this (filing, CUSIP), FORWARD-ADJUSTED to the latest split basis using the Sharadar split feed — so a stock split is NOT mislabelled as a giant phantom buy/sell. Continuous across splits: a 4:1 split nets to ~0, and only real trading moves the count. Use `shares_raw` for the literal as-filed value. (Same split-adjustment methodology as [GET /api/v1/tickers/{ticker}/fund-trends](/docs/ticker-research/get-tickers-ticker-fund-trends).)
- `history[].shares_raw` (integer): The literal as-filed `number_of_shares` sum for this quarter, BEFORE split adjustment — kept for reconciliation against the raw 13F filing. Equals `shares` when no split applies to this quarter.
- `history[].value` (integer): Sum of `value_of_shares` across all sub-advisor partitions for this (filing, CUSIP). USD, post-Plan-51 thousands-vs-actual normalization. For BlackRock/Vanguard-class index books a single position can be $200B+; mid-tier hedge fund positions are typically $10M-$1B.
- `history[].shares_delta` (integer): `shares - prev_shares` computed on the SPLIT-ADJUSTED counts (`prev_shares=0` on the first entry). Positive = bought; negative = trimmed; zero = held flat. Because shares are split-adjusted, a split no longer shows as a phantom delta — e.g. Berkshire's 2020-09-30 AAPL row (the quarter of the 4:1 split) is now `shares_delta = -36,326,710` (the real trim), not the raw `+699,139,988` jump a naive as-filed delta would report.
- `history[].transaction_type` (string): Classification of this quarter's transition: `new` (first entry, or re-entry after a temporary sell-out reflected as a zero row — note that the SQL today only returns quarters where the position exists with non-zero shares, so re-entries appear as fresh `new` rather than `re-opened`), `increased` (delta > 0), `decreased` (delta < 0), `unchanged` (delta == 0).

**Since:** 3.25.0

**Utility:** Drill into ONE position's full timeline: every quarter the position appeared in the fund's 13F, the split-adjusted share count, the reported USD value, the QoQ share delta, and a transaction-type classification (`new` / `increased` / `decreased` / `unchanged`). Mirrors the same canonical filing-selection logic as [GET /api/v1/form-13f/fund/{cik}](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-cik) — for each `period_of_report` we pick the filing with the MOST non-option holdings (#264 amendment-handling pattern) so a 4-holding 'correction' amendment doesn't overwrite the 36-holding original. CUSIP-keyed (not ticker) because tickers change on mergers / spinoffs / reuse — CUSIPs are the canonical 13F security identifier.

**Use case:** Powering the chevron-expanded position row on `/filer/<slug>-<cik>/` — a per-position transaction-timeline chart (bars = shares held per quarter, line = USD value, colored markers for `new` / `increased` / `decreased` transitions). Also useful for headline narratives like Berkshire's AAPL buying spree 2016-2018 (`/fund/0001067983/cusip/037833100/history` returns the full ramp: 9.8M shares in 2016-Q1 → 251.9M in 2018-Q2).

**Parameters:**
- `cik` (path, required): Fund CIK in 10-char zero-padded form (e.g. `0001067983` for Berkshire Hathaway, `0001536411` for Duquesne Family Office). Server-side normalization handles 6/7/10-char input forms (the endpoint accepts `1067983` and pads it for you).
- `cusip` (path, required): Canonical 9-character CUSIP for the security (`current_cusip` column in `normalized_holdings_deduped`). Pass the `cusip` (or `canonicalCusip` for chained-CUSIP fallback) from any holdings row on [GET /api/v1/form-13f/fund/{cik}](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-cik). Validated server-side: alphanumeric only, ≤ 12 chars — anything else returns 400 BAD_REQUEST.

**Sample response:**
```json
{
  "cik": "0001067983",
  "cusip": "037833100",
  "ticker": "AAPL",
  "name": "APPLE INC",
  "quarters": 4,
  "split_adjusted": true,
  "splits": [
    {
      "date": "2000-06-21",
      "ratio": 2
    },
    {
      "date": "2005-02-28",
      "ratio": 2
    },
    {
      "date": "2014-06-09",
      "ratio": 7
    },
    {
      "date": "2020-08-31",
      "ratio": 4
    }
  ],
  "history": [
    {
      "quarter_date": "2016-03-31",
      "shares": 39246988,
      "shares_raw": 9811747,
      "value": 1069382000,
      "shares_delta": 39246988,
      "transaction_type": "new"
    },
    {
      "quarter_date": "2016-06-30",
      "shares": 60910808,
      "shares_raw": 15227702,
      "value": 1455768000,
      "shares_delta": 21663820,
      "transaction_type": "increased"
    },
    {
      "quarter_date": "2016-09-30",
      "shares": 60910808,
      "shares_raw": 15227702,
      "value": 1722896000,
      "shares_delta": 0,
      "transaction_type": "unchanged"
    },
    {
      "quarter_date": "2016-12-31",
      "shares": 229438608,
      "shares_raw": 57359652,
      "value": 6644905000,
      "shares_delta": 168527800,
      "transaction_type": "increased"
    }
  ]
}
```

### GET /api/v1/form-13f/fund/{cik}/holdings-analytics

DEPRECATED (Phase 69 Plan 05, since v3.23.0) — 302 redirects to `/api/v1/form-13f/fund/{cik}?include_analytics=true`. Use that flag on the canonical /fund/{cik} route for all new integrations. Kept live as a redirect for existing customers (e.g. the WordPress filer-proxy adapter) during their migration window.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `cik` (string): 10-char zero-padded fund CIK echoed back from the request.
- `holdings_count` (integer): Number of current positions in the response (positions with `final_shares > 0` after the chronological cost-basis walk). Excludes positions that have been fully sold out — those reset cost basis on sell-out and are not surfaced as 'current' holdings.
- `summary` (object): Portfolio-level rollups: `{ total_cost_basis, total_market_value, total_unrealized_pnl, total_unrealized_pnl_pct, avg_holding_period_days }`. All USD; null when current prices are unavailable.
- `summary.total_cost_basis` (number (nullable)): Sum of `holdings[].cost_basis` across the portfolio. Reflects the cumulative VWAP-estimated dollar amount the fund has put to work in current positions. Null when no holdings have a computed cost basis.
- `summary.total_market_value` (number (nullable)): Sum of `holdings[].market_value` across the portfolio (using each position's most recent close × split-adjusted shares). USD. Null when current prices are unavailable for all holdings.
- `summary.total_unrealized_pnl` (number (nullable)): `total_market_value - total_cost_basis`. Positive = portfolio in the money on a cost basis; negative = portfolio underwater. Excludes any realized P&L from sold positions (those reset on sell-out).
- `summary.total_unrealized_pnl_pct` (number (nullable)): `(total_unrealized_pnl / total_cost_basis) × 100`. Portfolio-wide unrealized return percentage on cost basis. Null when `total_cost_basis` is null or zero.
- `summary.avg_holding_period_days` (integer (nullable)): Mean of `holdings[].holding_period_days` across positions with a populated value. Useful as a 'patience proxy' — Berkshire-style books show 1500+ days; quant books show 90-180 days.
- `holdings` (array): Per-position rows sorted by `sort_by` / `order`. Each row carries cost-basis economics, holding period, and (Phase 68) sector + last-transaction enrichment. Long-equity only — options are excluded by design (use `/fund/{cik}?include_options=true` for the options book).
- `holdings[].cusip` (string): 9-char CUSIP — natural primary key for the position. Apple's canonical CUSIP is `037833100`.
- `holdings[].ticker` (string (nullable)): Resolved ticker via `cusip_mappings`. Null for unmapped CUSIPs (~3% in steady state). Multi-class issuers preserve the actual filed class (e.g. `BRK-A` vs `BRK-B`).
- `holdings[].name` (string): Issuer name as filed (typically all-caps EDGAR convention, e.g. `APPLE INC`). Falls back to the CUSIP itself when no name is available.
- `holdings[].shares` (integer): Current split-adjusted share count (final position size after the chronological walk). Phase 52 split-adjustment is honored — a 4:1 split is reflected in this number, not just in `last_share_delta`.
- `holdings[].avg_buy_price` (number (nullable)): VWAP-estimated average buy price across all share-increase quarters in this position's history. Computed using the mean daily closing price during each quarter of share increase. Resets on full sell-out. NOT actual transaction prices — surfaced verbatim in `meta.disclaimer`. Null when the fund has held the position with zero shares throughout the window.
- `holdings[].current_price` (number (nullable)): Most-recent close price for the resolved ticker. Null when the ticker is unmapped or the price feed is missing recent data (e.g. delisted issuers).
- `holdings[].cost_basis` (number (nullable)): `avg_buy_price × final_shares` (USD). The total dollar amount the fund has put to work in this position on a VWAP-estimated basis. Null when `avg_buy_price` is null.
- `holdings[].market_value` (number (nullable)): `current_price × final_shares` (USD). Position size at most-recent close. Null when `current_price` or `avg_buy_price` is unavailable.
- `holdings[].unrealized_pnl` (number (nullable)): `market_value - cost_basis` (USD). Positive = position in the money; negative = position underwater. Null when `market_value` is null.
- `holdings[].unrealized_pnl_pct` (number (nullable)): `(current_price / avg_buy_price - 1) × 100`. Unrealized return percentage on the position. Null when `avg_buy_price` is null or zero. Use as the sort key for a 'biggest gainers/losers' table view.
- `holdings[].holding_period_days` (integer (nullable)): Days from `first_added` (the first quarter the fund acquired any shares) to the latest quarter in the response. Null when the position has been held with zero shares throughout the window.
- `holdings[].holding_period_quarters` (integer (nullable)): Number of quarterly 13F-HR snapshots in which the fund reported a non-zero share count for this position since `first_added`. Diverges from `holding_period_days / 90` when the fund had a temporary full sell-out and re-entered.
- `holdings[].first_added` (string (nullable)): ISO `YYYY-MM-DD` quarter-end date of the first 13F filing in which the fund reported any shares of this CUSIP. Survives across temporary sell-outs (the chronological walk resets cost basis but not `first_added`).
- `holdings[].sector` (string (nullable)): Phase 68 enrichment: GICS-style sector for the holding. Resolution priority: (1) `cusip_mappings.ticker` → `all_stocks_list.sector` (canonical, Phase 53 hyphen-normalized); (2) `holding_info.sector` fallback (excluding the literal `'Equity'` which is not a real sector). Null for un-mapped CUSIPs and for CUSIPs whose all_stocks_list row has a null/empty sector. Use to populate a Sector column + Industry filter dropdown on per-filer Holdings tables.
- `holdings[].last_transaction_quarter` (string (nullable)): Phase 68 enrichment: ISO `YYYY-MM-DD` quarter-end date of the most-recent quarter where the fund's split-adjusted share count CHANGED (non-zero delta). Tracked AFTER split-adjustment, so a 4:1 stock split alone does NOT register as a transaction (delta == 0 post-adjustment) — real buys/sells layered on top of a split quarter still register correctly. Null for positions that have been static since `first_added`. Powers the 'Latest Trades' sort mode on `/filer/<slug>-<cik>/`.
- `holdings[].last_share_delta` (integer): Phase 68 enrichment: signed split-adjusted share movement on `last_transaction_quarter`. Positive = added shares; negative = trimmed shares; 0 = position has been static since `first_added` (in which case `last_transaction_quarter` is null). Use the magnitude to surface the size of the most recent activity ('Berkshire trimmed AAPL by 100M shares in Q3 2025').
- `meta.sort_by` (string): Echoed-back sort key from the request.
- `meta.order` (string): Echoed-back sort order from the request.
- `meta.disclaimer` (string): Cost-basis estimation disclaimer surfaced verbatim: average buy prices are VWAP estimates of daily closing prices during the quarter of each share increase, NOT actual transaction prices. Display this on any UI that surfaces `avg_buy_price` or `unrealized_pnl_pct` to set user expectations correctly.

**Utility:** DEPRECATED. Compute the cost-basis economics of every position in a 13F filer's current book — same VWAP-of-quarterly-closes methodology, just exposed differently. New callers should use `GET /api/v1/form-13f/fund/{cik}?include_analytics=true` directly; this route now returns 302 Found with `Location: /api/v1/form-13f/fund/{cik}?include_analytics=true`. The field-by-field response shape below documents what the canonical route's decorated `holdings[]` rows look like when the flag is on. Long-equity-only by design — options are out of scope (use `/fund/{cik}?include_options=true` for the options book).

**Use case:** Powering the 'Holdings' tab on `/filer/<slug>-<cik>/` — the per-filer analytics page that lists every current position with sortable columns: avg buy price, P&L %, market value, holding period, sector, last transaction. Also drives the 'Latest Trades' sort mode (sorts holdings by `last_transaction_quarter DESC`) for spotting recent portfolio activity. Replaces what would otherwise be a sequence of 12+ DAILY price queries per CUSIP from a frontend.

**Parameters:**
- `cik` (path, required): Fund CIK in 10-char zero-padded form (e.g. `0001067983` for Berkshire Hathaway, `0001364742` for BlackRock, `0000884144` for Vanguard, `0001037389` for Renaissance Technologies). Server-side normalization handles 6/7/10-char input forms.
- `sort_by` (query, optional, default: market_value): Sort key for `holdings[]`. Allowed values: `market_value`, `unrealized_pnl_pct`, `holding_period_days`, `avg_buy_price`, `cost_basis`. Returns 400 INVALID_PARAM on any other value. Use `holding_period_days` for a 'longest-held positions' view; `unrealized_pnl_pct` for a 'biggest gainers/losers' view.
- `order` (query, optional, default: desc): Sort order: `desc` (default) or `asc`. Combined with `sort_by` — e.g. `sort_by=unrealized_pnl_pct&order=asc` surfaces the worst-performing positions first.

**Sample response:**
```json
{
  "cik": "0001067983",
  "holdings_count": 47,
  "summary": {
    "total_cost_basis": 130000000000,
    "total_market_value": 308000000000,
    "total_unrealized_pnl": 178000000000,
    "total_unrealized_pnl_pct": 136.92,
    "avg_holding_period_days": 1842
  },
  "holdings": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "name": "APPLE INC",
      "shares": 300000000,
      "avg_buy_price": 32.45,
      "current_price": 260.8,
      "cost_basis": 9735000000,
      "market_value": 78240000000,
      "unrealized_pnl": 68505000000,
      "unrealized_pnl_pct": 703.69,
      "holding_period_days": 3170,
      "holding_period_quarters": 35,
      "first_added": "2016-09-30",
      "sector": "Technology",
      "last_transaction_quarter": "2025-09-30",
      "last_share_delta": -10000000
    }
  ],
  "meta": {
    "sort_by": "market_value",
    "order": "desc",
    "disclaimer": "Average buy prices are estimated from quarterly 13F filings using VWAP of daily closing prices during the reported quarter. Not actual transaction prices."
  }
}
```

### GET /api/v1/form-13f/funds

Get all tracked funds (full list for autocomplete).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `funds` (array): Array of all tracked institutional funds — sorted by `filing_count DESC` (most-active filers first). Designed for client-side autocomplete preloading: pass `limit=10000` once on page-init, cache in IndexedDB / Redux, then run all autocomplete matches in-browser without per-keystroke server roundtrips. Each row is small (~80 bytes) so 10K funds fits in ~800KB transfer.
- `funds[].cik` (string): Filer CIK as a 10-character zero-padded string. The stable join key for this filer across the entire 13F surface (`/holdings`, `/cover-pages`, `/aggregation/by-ticker`, `/fund-performance`). Berkshire = `0001067983`; BlackRock = `0001364742`; Vanguard = `0000884144`.
- `funds[].name` (string): Registrant name AS FILED on the most recent 13F-HR (typically all-caps in EDGAR convention, e.g. `BERKSHIRE HATHAWAY INC`). Casing preserved verbatim. NOT alias-normalized — for the user-friendly alias (e.g. 'Warren Buffett') consult [GET /api/v1/form-13f/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers) which queries the curated `filer_aliases` table.
- `funds[].filing_count` (integer): Total cumulative 13F filings ingested for this filer (across all quarters and amendments). Active large managers (Berkshire, Vanguard, BlackRock) have 90-100+ filings going back to 2013 (FinRadar's coverage start); newer managers have lower counts. Use this to weight ranking in client-side fuzzy search (most-active filers should bubble up).
- `funds[].latest_period` (string (nullable)): ISO `YYYY-MM-DD` reporting period of the most recent 13F-HR for this filer. Null for filers registered but with no parsed filings yet. Use to detect inactive/dissolved filers — values older than ~7 months indicate the filer skipped the most recent quarterly deadline (45 days post-quarter-end).
- `count` (integer): Total number of funds returned (echoes back `funds.length`). The full 13F universe currently sits at ~9,600 unique CIKs — pass `limit=10000` to fetch them all in one round-trip.

**Utility:** Retrieve all 3,500+ tracked institutional funds in one request. Designed for client-side autocomplete preloading.

**Use case:** Loading the complete fund list on page init so the search dropdown works instantly without server roundtrips.

**Parameters:**
- `limit` (query, optional, default: 5000): Max results (up to 10,000)

**Sample response:**
```json
{
  "funds": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "filing_count": 92,
      "latest_period": "2025-12-31"
    },
    {
      "cik": "0001364742",
      "name": "BLACKROCK INC.",
      "filing_count": 78,
      "latest_period": "2025-12-31"
    },
    {
      "cik": "0000884144",
      "name": "VANGUARD GROUP INC",
      "filing_count": 88,
      "latest_period": "2025-12-31"
    },
    {
      "cik": "0001037389",
      "name": "RENAISSANCE TECHNOLOGIES LLC",
      "filing_count": 71,
      "latest_period": "2025-12-31"
    }
  ],
  "count": 4
}
```

### GET /api/v1/form-13f/aggregation/by-ticker

Get all tickers for a given quarter with full sorting, range filtering, and market data enrichment. Serves the 'Grouped Hedge Funds' page for both incomplete (current filing season) and complete (past) quarters. Enriches 13F summary data with close price, market cap, shares_outstanding, first traded date, and ETF flag from Sharadar and XBRL sources. Previous path /api/v1/form-13f/market/tickers is kept as a deprecated alias.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `success` on a 2xx response (deviation from the canonical `ApiResponse` envelope — this endpoint uses a custom shape because it pre-aggregates and emits `data.tickers[]` plus rich metadata blocks). Error responses use the standard `ApiResponse.error()` envelope with `status: 'error'`.
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end (03-31, 06-30, 09-30, 12-31). Echoed from the request; defaults to the latest available quarter when omitted.
- `data.tickers` (array): Per-CUSIP aggregation rows from `sec_13f_summary`, enriched with market data from Sharadar (close_price, sector, industry) + XBRL (shares_outstanding) + computed market_cap. Sorted per `sort_by` / `sort_order`. Page size controlled by `limit`; offset by `offset`.
- `data.tickers[].cusip` (string): 9-character CUSIP — natural primary key. NVIDIA's canonical CUSIP is `67066G104`; Apple's is `037833100`.
- `data.tickers[].ticker` (string (nullable)): Resolved ticker (canonical hyphen form for multi-class issuers — e.g. `BRK-A`, `BRK-B`, `GOOG`, `GOOGL`). Null when CUSIP is unmapped (~3% of rows in steady state — debt instruments, private placements, delisted issuers).
- `data.tickers[].name` (string): Issuer name from `cusip_security_catalog` (canonical, NOT as-filed). For the as-filed name see [POST /api/v1/form-13f/holdings](/docs/institutional-holdings/form-13f-api/post-form-13f-holdings).
- `data.tickers[].sector` (string (nullable)): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when CUSIP is unmapped or the security predates Sharadar's coverage.
- `data.tickers[].security_group` (string): Per #241 6-bucket classification: `Stocks`, `ETFs`, `Preferred`, `Warrants`, `Debt`, `Other`. Replaces the older binary `is_etf` flag — query via `?security_group=Stocks,ETFs` for multi-bucket filtering. Coverage restored from 7,968 to ~25,000 CUSIPs by removing the equity-only whitelist.
- `data.tickers[].is_etf` (boolean): Deprecated — use `security_group` instead. Kept for backwards compatibility with pre-#241 clients. True for `security_group === 'ETFs'`.
- `data.tickers[].close_price` (number (nullable)): Close price (USD) on the last trading day of the quarter, from `all_stocks_prices` (Sharadar). Used to compute `market_cap = close_price * shares_outstanding`. Null when price coverage is missing for the quarter.
- `data.tickers[].market_cap` (number (nullable)): Market cap in USD = `close_price * shares_outstanding`. NVIDIA Q4 2025 ≈ $3.62T; mid-cap stocks $2-10B; micro-caps <$300M. Null when either input is missing. Used for size-bucket filtering via `min_market_cap` / `max_market_cap`.
- `data.tickers[].shares_outstanding` (number (nullable)): Total shares outstanding (NOT free float — see legacy `float` alias in range filters). Sourced from XBRL `dei:EntityCommonStockSharesOutstanding`. Null when XBRL coverage is missing or the issuer is non-US.
- `data.tickers[].first_traded` (string (nullable)): ISO `YYYY-MM-DD` date of the security's first trade. Useful for filtering out recent IPOs (`min_first_traded=2020-01-01` to exclude 2020+ IPOs). Null for unmapped securities.
- `data.tickers[].fund_flow` (number): Net dollar flow this quarter — sum of (new_buys_value + increased_value) - (closed_value + decreased_value), in USD (post-Plan-51 thousands correction). Positive = net institutional buying; negative = net selling. The headline fund-rotation metric.
- `data.tickers[].fund_flow_mcap_pct` (number (nullable)): `fund_flow / market_cap * 100` — measures flow significance relative to the issuer's size. Useful for filtering out 'noise' from mega-caps where $1B flow is <0.05% of cap. Null when `market_cap` is missing.
- `data.tickers[].total_value` (number): Total institutional position value this quarter, in USD (post-Plan-51 thousands correction). Sum of `value_usd` across all funds holding this CUSIP. NOT a per-fund metric — for per-fund detail use [POST /api/v1/form-13f/holdings](/docs/institutional-holdings/form-13f-api/post-form-13f-holdings).
- `data.tickers[].fund_count` (integer): Number of distinct funds holding this CUSIP this quarter. NVIDIA Q4 2025 ≈ 3,200 funds; Apple ≈ 5,500 funds. Indicates institutional ownership breadth.
- `data.tickers[].fund_change` (integer): QoQ change in `fund_count` — positive = more funds added the position; negative = funds exited. Computed against the prior quarter's aggregate.
- `data.tickers[].share_change` (number): QoQ change in total shares held by all funds. NOT split-adjusted — for split-adjusted aggregations use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/ticker-research/get-tickers-ticker-fund-trends). Phase 52 split-adjustment work is shipped on the ticker-research surface.
- `data.tickers[].new_buys_count` (integer): Number of funds that opened a NEW position this quarter (no prior-quarter row). High new-buys count is a signal of conviction — multiple funds independently initiating positions.
- `data.tickers[].increased_count` (integer): Number of funds that ADDED to an existing position this quarter. Companion fields: `decreased_count`, `unchanged_count`, `closed_count`.
- `data.volume` (object): Quarter-wide buy/sell volume aggregates: `{ buy: <total dollars added>, sell: <total dollars removed> }`. The buy-vs-sell ratio is a macro-level institutional sentiment indicator.
- `data.quarter_metadata` (object): Filing-completeness state for the quarter: `{ quarter, filing_deadline, is_complete, days_until_deadline }`. `is_complete=false` during filing season (within 45 days of quarter-end) means data is still accumulating; gate downstream analytics until `is_complete=true`. Same shape as [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress).
- `data.available_quarters` (array): Sorted-newest-first array of ISO `YYYY-MM-DD` quarter ends with parsed 13F coverage. Use to populate quarter-selector dropdowns.
- `data.filter_ranges` (object (nullable)): Min/max values for each filterable column (e.g. `{ market_cap: { min, max }, fund_count: { min, max } }`). Present ONLY when `include_ranges=true` — request once on page-load to initialize range sliders, NOT on every paginate/sort. Enriched columns (market_cap, shares_outstanding, fund_flow_mcap_pct, first_traded) omitted for performance — only native summary columns included.
- `meta.pagination` (object): `{ total, limit, offset, has_more }`. `total` reflects the full filter-applied count (not just the page); `has_more` is convenience-flag for cursor-style UI.
- `meta.sort` (object): Echoes back applied sort: `{ column, order }`. Useful for stateful client-side rendering (e.g. arrow indicator on the active column header).
- `meta.filters_applied` (object): Echoes back the filter set used: `{ security_group, sector, industry, search, min_*, max_* }`. Null fields indicate an unfiltered dimension. Useful for rendering active-filter chips client-side.

**Utility:** Pre-aggregated per-CUSIP quarterly 13F data from sec_13f_summary, enriched with market data (close price from all_stocks_prices, shares outstanding from XBRL, market cap computed as close x shares_outstanding). Supports 30 sortable columns, 11 range filters (min/max), sector/industry/security group filters, and text search. Returns filter_ranges with actual min/max for each filterable column so frontends can initialize range sliders. Pagination via limit/offset with total count. Per #241: security_group filter (Stocks, ETFs, Preferred, Warrants, Debt, Other) replaces old security_type and is_etf/etf params. Coverage restored from 7,968 to ~25,000 CUSIPs by removing equity-only whitelist.

**Use case:** Building an institutional ownership screener: 'Show me all equity tickers held by hedge funds this quarter, sorted by fund flow, filtered to Technology sector with market cap > $10B.' Two sub-pages: incomplete quarter (filing season, is_complete=false) and complete quarter (historical, is_complete=true).

**Parameters:**
- `quarter` (query, optional, default: latest): Quarter-end date (YYYY-MM-DD). Defaults to latest available quarter.
- `sort_by` (query, optional, default: fund_flow): Column to sort by. Options: symbol, name_of_issuer, fund_count, fund_count_prev, fund_change, fund_change_pct, total_value, fund_flow, share_change, share_change_pct, total_shares_curr, total_shares_prev, new_buys_count, closed_count, increased_count, decreased_count, unchanged_count, new_buys_shares, increased_shares, decreased_shares, unchanged_shares, closed_shares, increased_delta_shares, decreased_delta_shares, increased_pct_shares, decreased_pct_shares, market_cap, close_price, shares_outstanding, first_traded, fund_flow_mcap_pct. Deprecated alias: 'sort'.
- `sort_order` (query, optional, default: desc): Sort direction: 'asc' or 'desc'. Deprecated alias: 'order'.
- `limit` (query, optional, default: 100): Page size (max 10000). Raised from 500 after enrichment materialization (#245).
- `offset` (query, optional, default: 0): Pagination offset.
- `security_group` (query, optional): Filter by security group: 'Stocks', 'ETFs', 'Preferred', 'Warrants', 'Debt', 'Other'. Comma-separated for multiple. Omit for all.
- `is_etf` (query, optional): (Deprecated -- use security_group instead) 'true' = ETFs only, 'false' = Stocks only.
- `sector` (query, optional): Exact sector name filter (e.g. 'Technology', 'Healthcare').
- `industry` (query, optional): Exact industry name filter (e.g. 'Semiconductors').
- `search` (query, optional): Case-insensitive substring search on ticker, company name, CUSIP, sector, or industry.
- `min_market_cap` (query, optional): Lower bound on market capitalization in USD.
- `max_market_cap` (query, optional): Upper bound on market capitalization in USD.
- `min_total_value` (query, optional): Lower bound on total 13F market value held in USD.
- `max_total_value` (query, optional): Upper bound on total 13F market value held in USD.
- `min_shares_outstanding` (query, optional): Lower bound on shares outstanding (canonical key; legacy alias `float`).
- `max_shares_outstanding` (query, optional): Upper bound on shares outstanding (canonical key; legacy alias `float`).
- `min_float` (query, optional): Legacy alias of `min_shares_outstanding`.
- `max_float` (query, optional): Legacy alias of `max_shares_outstanding`.
- `min_fund_flow` (query, optional): Lower bound on net fund flow in USD.
- `max_fund_flow` (query, optional): Upper bound on net fund flow in USD.
- `min_fund_flow_mcap_pct` (query, optional): Lower bound on fund flow as a fraction of market cap.
- `max_fund_flow_mcap_pct` (query, optional): Upper bound on fund flow as a fraction of market cap.
- `min_fund_count` (query, optional): Lower bound on number of funds holding the ticker.
- `max_fund_count` (query, optional): Upper bound on number of funds holding the ticker.
- `min_fund_change` (query, optional): Lower bound on quarter-over-quarter change in holder count.
- `max_fund_change` (query, optional): Upper bound on quarter-over-quarter change in holder count.
- `min_fund_change_pct` (query, optional): Lower bound on quarter-over-quarter holder-count change as a fraction.
- `max_fund_change_pct` (query, optional): Upper bound on quarter-over-quarter holder-count change as a fraction.
- `min_share_change` (query, optional): Lower bound on quarter-over-quarter change in shares held.
- `max_share_change` (query, optional): Upper bound on quarter-over-quarter change in shares held.
- `min_share_change_pct` (query, optional): Lower bound on quarter-over-quarter share change as a fraction.
- `max_share_change_pct` (query, optional): Upper bound on quarter-over-quarter share change as a fraction.
- `min_first_traded` (query, optional): Lower bound on first-traded date, compared lexicographically as YYYY-MM-DD.
- `max_first_traded` (query, optional): Upper bound on first-traded date, compared lexicographically as YYYY-MM-DD.
- `include_ranges` (query, optional, default: false): Set to 'true' to include filter_ranges in response (min/max for each filterable column). Request this once on page load, not on every paginate/sort. Enriched column ranges (market_cap, shares_outstanding, fund_flow_mcap_pct, first_traded) are omitted for performance -- only native summary column ranges are returned.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "tickers": [
      {
        "cusip": "67066G104",
        "ticker": "NVDA",
        "name": "NVIDIA CORP",
        "sector": "Technology",
        "industry": "Semiconductors",
        "security_group": "Stocks",
        "is_etf": false,
        "close_price": 148.5,
        "market_cap": 3620000000000,
        "shares_outstanding": 24380000000,
        "first_traded": "1999-01-22",
        "fund_flow": 28500000000,
        "fund_flow_mcap_pct": 0.79,
        "total_value": 145000000000,
        "fund_count": 3200,
        "fund_count_prev": 2830,
        "fund_change": 370,
        "fund_change_pct": 13.1,
        "share_change": 150000000,
        "share_change_pct": 12.5,
        "new_buys_count": 450,
        "increased_count": 1200,
        "decreased_count": 900,
        "unchanged_count": 570,
        "closed_count": 80
      }
    ],
    "volume": {
      "buy": 450000000000,
      "sell": 320000000000
    },
    "quarter_metadata": {
      "quarter": "2025-12-31",
      "filing_deadline": "2026-02-17",
      "is_complete": true,
      "days_until_deadline": null
    },
    "available_quarters": [
      "2025-12-31",
      "2025-09-30",
      "2025-06-30"
    ],
    "filter_ranges": {
      "market_cap": {
        "min": 449830,
        "max": 4440000000000
      },
      "total_value": {
        "min": 1,
        "max": 3070000000000
      },
      "fund_count": {
        "min": 1,
        "max": 5820
      }
    }
  },
  "meta": {
    "pagination": {
      "total": 8234,
      "limit": 100,
      "offset": 0,
      "has_more": true
    },
    "sort": {
      "column": "fund_flow",
      "order": "desc"
    },
    "filters_applied": {
      "security_group": null,
      "sector": null,
      "search": null
    }
  }
}
```

### GET /api/v1/form-13f/aggregation/by-sector

Get institutional fund flows aggregated by sector and industry with momentum labels, flow significance metrics, and top movers drill-down. Response includes quarter_metadata (quarter, filing_deadline, is_complete, days_until_deadline) indicating whether the quarter's data is complete or still accumulating.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `success` on a 2xx response. Custom envelope (not the standard `ApiResponse`) — carries `data` directly with `quarter`, `sector_count`, `sectors[]`, `quarter_metadata`.
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter (always a calendar quarter end). Echoed from the request; defaults to the latest available quarter.
- `data.sector_count` (integer): Total number of sectors with non-zero institutional flow this quarter. Typically 10-11 (the standard Sharadar sector taxonomy).
- `data.sectors` (array): Per-sector aggregation rows from `sec_13f_sector_summary`. Sorted by `sort` parameter (default: `fund_flow DESC`). Each sector carries top-N industries (per `industry_limit`) with their top-5 movers — drill-down structure suitable for a 3-level navigation UI (sector → industry → ticker).
- `data.sectors[].sector` (string): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`, `Energy`, `Utilities`, `Consumer Cyclical`, `Consumer Defensive`, `Industrials`, `Basic Materials`, `Communication Services`, `Real Estate`).
- `data.sectors[].fund_flow` (number): Net dollar flow into the sector this quarter, in USD (post-Plan-51 thousands correction). Positive = net institutional buying; negative = net selling. The headline sector-rotation metric.
- `data.sectors[].total_value` (number): Total institutional position value in this sector this quarter, in USD. Sum of `value_usd` across all positions held by tracked funds in this sector.
- `data.sectors[].fund_count` (integer): Number of distinct funds with at least one position in this sector. Sectors with high fund_count + high fund_flow indicate broad institutional consensus on the sector direction.
- `data.sectors[].etf_value` (number): Sub-aggregate of `total_value` that comes from ETF positions (`security_group=ETFs`). Useful for distinguishing active sector bets (high non-ETF value) from passive index exposure (high ETF value). Computed as `total_value - sum(non-etf positions)`.
- `data.sectors[].flow_significance_pct` (number): `fund_flow / total_value * 100` — measures flow significance relative to sector size. A 20% flow_significance_pct means institutions added 20% more value than they currently hold (very strong inflow). Used for the `momentum` classification.
- `data.sectors[].momentum` (string): 5-tier momentum label derived from `flow_significance_pct`: `Strong Buying` (≥10%), `Moderate Buying` (≥3%), `Neutral` (-3 to +3%), `Moderate Selling` (≤-3%), `Strong Selling` (≤-10%). The single most-used field for sector-rotation dashboards.
- `data.sectors[].confidence` (string): Data-quality confidence flag: `high` (sector has >100 funds + filing_progress >80%), `medium` (>30 funds OR >50% complete), `low` (sparse coverage). Use to gate downstream display ('Show only high-confidence signals').
- `data.sectors[].industries` (object): Industry-level breakdown: `{ inflows: [...], outflows: [...] }`. Each direction is sorted by `fund_flow` (inflows DESC, outflows ASC by absolute value). Page size capped by `industry_limit` (default 15, max 100, or `all` for full breakdown).
- `data.sectors[].industries.inflows[]` (object): Per-industry inflow row: `{ industry, fund_flow, total_value, fund_count, top_movers: [...] }`. `top_movers` is a top-5 list of CUSIPs by absolute fund_flow within the industry.
- `data.sectors[].industries.inflows[].top_movers[]` (object): Per-CUSIP mover row: `{ cusip, ticker, name, fund_flow, total_value }`. The 'NVDA, AMD, AVGO drove Semiconductor inflows' drill-down. Limited to 5 per industry to keep payload bounded.
- `data.sectors[].compare` (object (nullable)): QoQ comparison block — present ONLY when `?compare=prev`. Shape: `{ flow_change, momentum_shift, fund_count_change, value_change_pct }`. `momentum_shift` is a string like `'Strong Growth -> Moderate Value'` indicating cross-tier movement.
- `data.quarter_metadata` (object): Filing-completeness state for the quarter: `{ quarter, filing_deadline, is_complete, days_until_deadline }`. Same shape as [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress). `is_complete=false` during filing season — gate downstream sector-rotation analysis until the quarter has matured.

**Utility:** Pre-aggregated sector-level 13F analytics with nested industry breakdown. Each sector includes flow significance (fund_flow/total_value %), momentum classification (Strong Buying to Strong Selling), ETF value tracking, and confidence flags. Industries include top 5 movers per industry. Supports quarter-over-quarter comparison.

**Use case:** Building a sector rotation dashboard showing where institutional money is flowing. Drill from 'Technology is seeing Strong Buying' to 'Semiconductors is the driver' to 'NVDA, AMD, AVGO are the top movers'. Use ?compare=prev to highlight momentum shifts between quarters.

**Parameters:**
- `quarter` (query, optional): Report period YYYY-MM-DD (e.g. 2025-12-31). Defaults to latest available quarter.
- `compare` (query, optional): Set to 'prev' to include quarter-over-quarter deltas per sector: flow_change, momentum_shift, fund_count_change, value_change_pct.
- `industry_limit` (query, optional, default: 15): Max industries per direction (inflows + outflows) per sector. Use 'all' for full breakdown. Range: 1-100.
- `sort` (query, optional, default: fund_flow): 'fund_flow' (absolute $) or 'significance' (flow_significance_pct). Applies to both sector and industry ordering.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "sector_count": 11,
    "sectors": [
      {
        "sector": "Technology",
        "fund_flow": 85000000000,
        "total_value": 420000000000,
        "fund_count": 3800,
        "etf_value": 52000000000,
        "flow_significance_pct": 20.2,
        "momentum": "Strong Buying",
        "confidence": "high",
        "industries": {
          "inflows": [
            {
              "industry": "Semiconductors",
              "fund_flow": 42000000000,
              "total_value": 180000000000,
              "fund_count": 2100,
              "top_movers": [
                {
                  "cusip": "67066G104",
                  "ticker": "NVDA",
                  "name": "NVIDIA CORP",
                  "fund_flow": 28500000000,
                  "total_value": 145000000000
                }
              ]
            }
          ],
          "outflows": [
            {
              "industry": "Software - Application",
              "fund_flow": -3200000000,
              "total_value": 45000000000,
              "fund_count": 800,
              "top_movers": [
                {
                  "cusip": "79466L302",
                  "ticker": "CRM",
                  "name": "SALESFORCE INC",
                  "fund_flow": -1500000000,
                  "total_value": 12000000000
                }
              ]
            }
          ]
        }
      }
    ],
    "quarter_metadata": {
      "quarter": "2025-12-31",
      "filing_deadline": "2026-02-14",
      "is_complete": true,
      "days_until_deadline": null
    }
  }
}
```

### GET /api/v1/form-13f/aggregation/by-industry

Industry-first mirror of /aggregation/by-sector — returns a flat industries array with sector context nested per industry. Useful for cross-sector industry leaderboards (e.g. 'biggest inflow industries this quarter regardless of sector'). Same enrichment columns (fund_flow, total_value, unique_fund_count, flow_significance_pct, momentum_label, ETF value, position-change counts) and same top_movers semantics as the sector endpoint. Response includes quarter_metadata.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): `success` on a 2xx response, `error` otherwise. Standard `ApiResponse` envelope — `data` carries the payload.
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter end. Echoed from the request; defaults to the latest available quarter in `sec_13f_sector_summary`.
- `data.total_institutional_value` (number): Sum of `total_value` across ALL sectors this quarter (computed from the sector-level rows, NOT industry-level — same source as `/by-sector`). USD, post-Plan-51 thousands correction. Used to derive `coverage_pct`.
- `data.coverage_pct` (number): Percentage of `total_institutional_value` that resolves to a classified sector (i.e. NOT `Unclassified`). Identical math to `/by-sector` so the two endpoints report the same number for the same quarter. Use as a data-quality gate before surfacing industry signals.
- `data.total_industries` (integer): Number of industry rows returned BEFORE the inflow/outflow `limit` cap. When `sector` is set, counts industries within that sector only; otherwise counts the full industry universe for the quarter (typically ~150).
- `data.sector_filter` (string (nullable)): Echoes back the `sector` query param when set; `null` when no filter was applied. Use to render an active-filter chip client-side.
- `data.industries` (array): Flat industry array. When no `sector` filter: top-`limit` inflows followed by top-`limit` outflows (capped naturally by `total_industries`). When `sector` is set: industries within that sector sorted by `abs(sort_by metric)` descending, capped at `limit`. Each row carries its parent sector's context nested under `sector` for self-contained rendering.
- `data.industries[].industry` (string): Sharadar industry classification (e.g. `Semiconductors`, `Software - Application`, `Biotechnology`, `Banks - Diversified`). Use together with `sector.name` to disambiguate cross-sector industries (rare but possible in Sharadar's taxonomy).
- `data.industries[].sector` (object): Parent-sector context block: `{ name, fund_flow, total_value, unique_fund_count, flow_significance_pct, momentum_label, low_confidence }`. Values are the same the same sector would show on `/by-sector` — replicated here so industry leaderboard rows are self-contained without a second round-trip. Inner fields may be `null` if the sector row is missing (data-quality edge case).
- `data.industries[].fund_flow` (number): Net dollar flow into the industry this quarter, in USD (post-Plan-51 thousands correction). Positive = net institutional buying; negative = net selling. The headline industry-rotation metric.
- `data.industries[].total_value` (number): Total institutional position value in this industry this quarter, in USD. Sum of `value_usd` across all funds holding any CUSIP classified to this industry.
- `data.industries[].cusip_count` (integer): Number of distinct CUSIPs classified to this industry this quarter. Indicates the depth of the industry's investable universe (Semiconductors ~90; Tobacco ~5).
- `data.industries[].unique_fund_count` (integer): Number of distinct funds with at least one position in this industry. High `unique_fund_count` + high `fund_flow` = broad institutional consensus on the industry.
- `data.industries[].total_positions` (integer): Total position rows (fund × CUSIP combinations) in this industry this quarter. Always ≥ `unique_fund_count × 1`; typically ~10× higher in deep industries like Semiconductors.
- `data.industries[].flow_significance_pct` (number): `fund_flow / total_value × 100` — measures flow magnitude relative to industry size. Drives the `momentum_label` classification.
- `data.industries[].momentum_label` (string): 5-tier momentum label derived from `flow_significance_pct`: `Strong Buying` (≥10%), `Moderate Buying` (≥3%), `Neutral` (-3 to +3%), `Moderate Selling` (≤-3%), `Strong Selling` (≤-10%). Same taxonomy as `/by-sector.momentum`.
- `data.industries[].low_confidence` (boolean): `true` when industry coverage is sparse (low fund count or low CUSIP count) — surface in UI as a quality indicator and consider filtering out for actionable leaderboards.
- `data.industries[].etf_value` (number): Sub-aggregate of `total_value` that comes from ETF positions (`security_group=ETFs`). Useful for distinguishing active industry bets (high non-ETF value) from passive sector-tilt exposure.
- `data.industries[].new_buys_count` (integer): Number of (fund, CUSIP) pairs where the fund initiated a NEW position in this industry this quarter (no prior-quarter row). High new-buys count = multiple funds independently entering the industry — conviction signal.
- `data.industries[].closed_count` (integer): Number of (fund, CUSIP) pairs the fund fully EXITED in this industry this quarter. Companion to `new_buys_count` for net-flow attribution.
- `data.industries[].increased_count` (integer): Number of (fund, CUSIP) pairs where the fund ADDED to an existing position in this industry.
- `data.industries[].decreased_count` (integer): Number of (fund, CUSIP) pairs where the fund TRIMMED an existing position in this industry.
- `data.industries[].top_movers` (array): Top-5 CUSIPs by `abs(fund_flow)` within this industry — `[{ ticker, name, fund_flow, fund_count }, ...]`. Mirrors `/by-sector`'s per-industry top_movers list (same 2-level sector resolution chain: `cusip_mappings.sector` → `cusip_mappings.ticker → all_stocks_list`). CUSIPs resolved via fallback chains (≤5% of total holdings value) are not represented — by design, to keep the query fast.
- `data.industries[].compare` (object (nullable)): QoQ comparison block — present and populated only when `?compare=prev`. Shape: `{ prev_quarter, flow_change, prev_momentum_label, momentum_shift, fund_count_change, value_change_pct }`. `momentum_shift` is a string like `'Moderate Buying -> Strong Buying'` (or `null` when momentum didn't change tier). When the industry didn't exist in the prior quarter, scalar fields are `null` but `prev_quarter` echoes the resolved date.
- `data.quarter_metadata` (object): Filing-completeness state for the quarter: `{ quarter, filing_deadline, is_complete, days_until_deadline }`. Same shape as [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress). `is_complete=false` during the 45-day post-quarter window — gate downstream industry-rotation analysis until the quarter has matured.

**Utility:** Industry-first cut of the same sec_13f_sector_summary matview that powers /aggregation/by-sector — the row shape, top-movers query, and coverage_pct math are byte-identical to the sector endpoint. The difference is the top-level entity: instead of grouping industries under their parent sector (one nested array per sector), this endpoint flattens the full industry universe (~150 industries) into a single sorted list with sector context attached to each row. Sort by fund_flow or significance, split inflows/outflows by default, or pass ?sector= to drill into one sector's industries only.

**Use case:** Cross-sector industry leaderboards. Answers 'which industries had the biggest fund inflows this quarter regardless of sector?' in one call — no client-side flatten + re-rank of /by-sector's 11-sector × N-industry nested response. Combine with /aggregation/by-sector for full sector → industry → ticker drill-down hierarchies, and with /aggregation/by-ticker for per-name detail within a hot industry.

**Parameters:**
- `quarter` (query, optional): Report period as `YYYY-MM-DD` (any quarter-end date). Defaults to the latest quarter present in `sec_13f_sector_summary`.
- `compare` (query, optional): Set to `prev` to include per-industry quarter-over-quarter deltas: `flow_change`, `prev_momentum_label`, `momentum_shift`, `fund_count_change`, `value_change_pct`. Omitted/any-other-value → `compare` is `null` per row.
- `limit` (query, optional, default: 50): Top-N inflows AND Top-N outflows to return when no `sector` filter is set (so the response carries up to `2 × limit` industries). When `sector` is set, the inflow/outflow split is skipped and `limit` caps total industries returned. Integer (1-200) or the string `all` (returns the full industry universe — ~150 rows). Default 50.
- `sort_by` (query, optional, default: fund_flow): `fund_flow` (absolute USD net flow) or `significance` (`flow_significance_pct = fund_flow / total_value × 100`). Inflows sort descending; outflows sort ascending by signed value (most negative first). With `sector` filter, all industries sort by `abs(metric)` descending. Legacy alias `sort` is accepted for cross-endpoint consistency with `/by-sector`.
- `sector` (query, optional): Optional drill-down. When set, restricts the response to industries within this sector and skips the inflow/outflow split (returns a single ranked list). Sector name must match the canonical Sharadar label exactly (e.g. `Technology`, `Healthcare`, `Financial Services`).

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "total_institutional_value": 22500000000000,
    "coverage_pct": 99.5,
    "total_industries": 158,
    "sector_filter": null,
    "industries": [
      {
        "industry": "Semiconductors",
        "sector": {
          "name": "Technology",
          "fund_flow": 85000000000,
          "total_value": 420000000000,
          "unique_fund_count": 3800,
          "flow_significance_pct": 20.2,
          "momentum_label": "Strong Buying",
          "low_confidence": false
        },
        "fund_flow": 42000000000,
        "total_value": 180000000000,
        "cusip_count": 92,
        "unique_fund_count": 2100,
        "total_positions": 145000,
        "flow_significance_pct": 23.3,
        "momentum_label": "Strong Buying",
        "low_confidence": false,
        "etf_value": 18000000000,
        "new_buys_count": 320,
        "closed_count": 110,
        "increased_count": 1180,
        "decreased_count": 490,
        "top_movers": [
          {
            "ticker": "NVDA",
            "name": "NVIDIA CORP",
            "fund_flow": 28500000000,
            "fund_count": 2100
          },
          {
            "ticker": "AMD",
            "name": "ADVANCED MICRO DEVICES INC",
            "fund_flow": 6200000000,
            "fund_count": 1450
          }
        ],
        "compare": {
          "prev_quarter": "2025-09-30",
          "flow_change": 18000000000,
          "prev_momentum_label": "Moderate Buying",
          "momentum_shift": "Moderate Buying -> Strong Buying",
          "fund_count_change": 145,
          "value_change_pct": 22.4
        }
      }
    ],
    "quarter_metadata": {
      "quarter": "2025-12-31",
      "filing_deadline": "2026-02-14",
      "is_complete": true,
      "days_until_deadline": null
    }
  }
}
```

### GET /api/v1/form-13f/fund-performance

Returns a ranked leaderboard of institutional funds by estimated quarterly portfolio returns derived from VWAP-based position valuation. Supports leaderboard mode (ranked list of funds) and single-fund detail mode (position-level return attribution for a specific CIK). Response includes quarter_metadata (quarter, filing_deadline, is_complete, days_until_deadline) indicating whether the quarter's data is complete or still accumulating.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `success` on a 2xx response. Custom envelope (not the standard `ApiResponse`) — carries `data` directly with `quarter`, `total_funds`, `eligible_funds`, `leaderboard[]` (or single-fund detail object when `?cik=` is set).
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end. Echoed from the request; defaults to the latest available quarter.
- `data.total_funds` (integer): Total tracked funds with a 13F filing for this quarter. Typically ~4,800 in fully-reported quarters; lower during early filing season.
- `data.eligible_funds` (integer): Subset of `total_funds` that meets the eligibility thresholds (`min_holdings`, `min_aum`, `include_all=false`). Default thresholds (`min_holdings=10`, `min_aum=$100M`) yield ~3,200 eligible funds — the leaderboard is drawn from this pool.
- `data.leaderboard` (array (nullable)): Ranked leaderboard rows (when `?cik=` is omitted). Sorted per `sort` / `order` (default: `portfolio_return_pct DESC`). Each row carries the fund's portfolio return + position activity + top contributors/detractors. Null in single-fund detail mode (`?cik=` provided).
- `data.leaderboard[].rank` (integer): 1-based rank within the eligible-fund pool, AFTER eligibility filtering. Rank persists across pagination — page 2 starts at rank 26 when `limit=25`. Stable per `(sort, order)` tuple.
- `data.leaderboard[].cik` (string): Fund CIK (NOT zero-padded in this endpoint — historical artifact; pad client-side if joining against the rest of the 13F surface). Berkshire = `1067983`, BlackRock = `1364742`.
- `data.leaderboard[].company_name` (string): Registrant name AS FILED on the most recent 13F-HR (typically all-caps in EDGAR convention).
- `data.leaderboard[].portfolio_return_pct` (number): Estimated quarterly portfolio return (%) — weighted sum of individual position returns, computed from VWAP-based entry/exit price estimation. ESTIMATED ONLY — see `meta.disclaimer`. Long-equity-only (no shorts, no derivatives, no cash). Berkshire Q4 2025 example: 8.45% means VWAP-estimated portfolio appreciation.
- `data.leaderboard[].portfolio_value` (number): End-of-quarter portfolio AUM in USD (post-Plan-51 thousands correction). Used for the `min_aum` eligibility filter and as the denominator for contribution_pct calculations.
- `data.leaderboard[].holdings_count` (integer): Number of position rows in the filing's information table. Used for the `min_holdings` eligibility filter (default 10 — excludes very-concentrated single-position funds from the leaderboard, since their 'returns' are dominated by one ticker's swing).
- `data.leaderboard[].price_coverage_pct` (number): Percentage of position value with VWAP price coverage. Sub-100% indicates some positions have unmapped CUSIPs or missing Sharadar prices — contributes uncertainty to `portfolio_return_pct`. Default eligibility doesn't filter on this; surface in UI as a quality indicator.
- `data.leaderboard[].top_contributors` (array): Top-5 positions by positive return contribution: `[{ ticker, return_pct, contribution_pct }, ...]`. `contribution_pct` is `position_return * position_weight` — directly attributes portfolio return to individual tickers. Berkshire Q4 2025 example: AAPL contributed +4.2% to the portfolio.
- `data.leaderboard[].top_detractors` (array): Top-5 positions by NEGATIVE return contribution (sorted ascending: most negative first). Same shape as `top_contributors`. Berkshire Q4 2025 example: KHC detracted -0.3%.
- `data.leaderboard[].return_1y` (number (nullable)): Trailing-1Y portfolio return (%) computed by the multi-period rollup (Phase 62-01). Null when the fund's rollup hasn't landed (~75% coverage gap as of v3.26.0). Combine with `?has_returns=true` to drop nulls. Sortable.
- `data.leaderboard[].return_3y` (number (nullable)): Trailing-3Y portfolio return (%). Same nullability semantics as `return_1y`.
- `data.leaderboard[].return_5y` (number (nullable)): Trailing-5Y portfolio return (%).
- `data.leaderboard[].return_10y` (number (nullable)): Trailing-10Y portfolio return (%). Added in Phase 72-01.
- `data.leaderboard[].return_inception` (number (nullable)): Since-inception portfolio return (%) — earliest quarter we have a filing for this fund through the requested `quarter`.
- `data.leaderboard[].sp500_return_1y` (number (nullable)): S&P 500 (SPY) total return (%) over the same 1Y window as `return_1y` — the benchmark side of the alpha calculation. Same nullability as `return_1y`.
- `data.leaderboard[].sp500_return_3y` (number (nullable)): S&P 500 (SPY) 3Y total return (%).
- `data.leaderboard[].sp500_return_5y` (number (nullable)): S&P 500 (SPY) 5Y total return (%).
- `data.leaderboard[].sp500_return_10y` (number (nullable)): S&P 500 (SPY) 10Y total return (%). Added in Phase 72-01.
- `data.leaderboard[].alpha_1y` (number (nullable)): `return_1y - sp500_return_1y` (%) — excess return over the S&P 500 benchmark over the same 1Y window. Positive = beat the index; negative = trailed. Same nullability as `return_1y`.
- `data.leaderboard[].alpha_3y` (number (nullable)): 3Y alpha vs SPY (%).
- `data.leaderboard[].alpha_5y` (number (nullable)): 5Y alpha vs SPY (%).
- `data.leaderboard[].alpha_10y` (number (nullable)): 10Y alpha vs SPY (%). Added in Phase 72-01.
- `data.leaderboard[].portfolio_turnover` (number (nullable)): Portfolio turnover ratio for the quarter — `min(buy_value, sell_value) / portfolio_value`. Low values (≤ 0.05) = Berkshire-style buy-and-hold; high values (≥ 0.30) = quant / active management.
- `data.leaderboard[].buy_value` (number (nullable)): Dollar value of NEW or INCREASED positions this quarter (USD). Sum of (`shares_q - shares_q-1`) × position price for positions where the delta is positive.
- `data.leaderboard[].sell_value` (number (nullable)): Dollar value of CLOSED or DECREASED positions this quarter (USD). Sum of (`shares_q-1 - shares_q`) × position price for positions where the delta is negative. Combine with `buy_value` to derive turnover.
- `data.available_quarters` (array (nullable)): Distinct list of `quarter_date` values (ISO `YYYY-MM-DD`, newest-first) for which `sec_13f_fund_performance` rows exist. Present ONLY on `offset=0` responses — infinite-scroll continuations omit the key entirely. Use to populate a quarter-selector dropdown without a second round-trip to [GET /api/v1/form-13f/fund-performance/quarters](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-performance). Since v3.26.0 (PR #185).
- `meta.pagination` (object): `{ total, limit, offset, has_more }`. `total` reflects `eligible_funds` (the leaderboard pool size); `has_more` is convenience-flag for cursor-style UI.
- `meta.filters` (object): Echoes back the active filter set: `{ min_holdings, min_aum, include_all, has_returns, q }`. Useful for rendering active-filter chips client-side. `has_returns` + `q` added in v3.26.0 (PR #185).
- `meta.disclaimer` (string): Boilerplate disclaimer that ALWAYS appears: 'Returns are estimated from 13F long equity positions only using VWAP-based entry price estimation. Not actual fund returns.' Render this in the UI prominently — VWAP-estimated returns are NOT the same as audited fund returns. They omit shorts, derivatives, cash, and intra-quarter trading activity.

**Utility:** Pre-aggregated fund performance metrics computed from 13F position-level VWAP entry/exit price estimation. Each fund has portfolio_return_pct (weighted sum of individual position returns), position activity breakdown (new/closed/increased/decreased/unchanged), top 5 contributors and detractors with return attribution, sector concentration (HHI), and data quality metrics (price_coverage_pct). Eligibility filtering excludes small or low-coverage funds from the leaderboard by default.

**Use case:** Building a hedge fund leaderboard showing 'Which institutions had the best estimated returns this quarter?' Drill into a single fund via ?cik= to see position-level attribution: 'AAPL contributed +4.2% to the portfolio, KHC detracted -0.3%'. Use min_holdings and min_aum to filter for large, diversified funds. Toggle include_all=true to see small funds too.

**Parameters:**
- `quarter` (query, optional): Quarter end date (YYYY-MM-DD). Defaults to latest quarter with data. Use `data.available_quarters` (returned on `offset=0`) to populate a quarter-selector dropdown without a second round-trip.
- `cik` (query, optional): Single fund CIK for detail mode. Returns position-level attribution for this fund.
- `q` (query, optional): Free-text search across the 13F filer universe — matches the SAME pool as [GET /api/v1/form-13f/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers). Resolves against `company_name`, padded CIK, unpadded CIK, `signature_name`, and the `filer_aliases` famous-manager table (`buffett` → Berkshire, `ackman` → Pershing, `dalio` → Bridgewater). Empty matches return `data.leaderboard=[]` (NOT 404) so the frontend can keep `quarter_metadata` + `pagination` visible. Since v3.26.0 (PR #185).
- `has_returns` (query, optional, default: false): When `true`, restricts results to funds where `return_1y IS NOT NULL` — drops the ~75% rollup coverage gap (funds whose multi-period rollup hasn't landed yet). Default `false` keeps the full filer universe browsable. FinRadar's leaderboard UI toggles this on by default. Since v3.26.0 (PR #185).
- `sort_by` (query, optional, default: portfolio_return_pct): Sort column. Whitelist mirrors `_build_fund_perf_dict`'s emitted fields so anything the frontend renders is server-side-sortable. Allowed values: `portfolio_return_pct` (default), `portfolio_value`, `holdings_count`, `price_coverage_pct`, `return_1y`, `return_3y`, `return_5y`, `return_10y`, `return_inception`, `sp500_return_1y`, `sp500_return_3y`, `sp500_return_5y`, `sp500_return_10y`, `alpha_1y`, `alpha_3y`, `alpha_5y`, `alpha_10y`, `portfolio_turnover`, `buy_value`, `sell_value`, `company_name`. Anything else returns 400 INVALID_PARAM. Legacy alias `sort` is still accepted. Multi-period return / S&P benchmark / alpha / turnover / buy-value / sell-value / company-name added in v3.26.0 (PR #185).
- `sort_order` (query, optional, default: desc): Sort direction: `desc` (default) or `asc`. Legacy alias `order` is still accepted.
- `limit` (query, optional, default: 25): Results per page (max 100).
- `offset` (query, optional, default: 0): Pagination offset. `data.available_quarters` is returned ONLY on the first page (`offset=0`) — infinite-scroll continuations skip it to stay lean.
- `min_holdings` (query, optional, default: 10): Minimum holdings count for eligibility (default 10).
- `min_aum` (query, optional, default: 100000000): Minimum AUM in dollars for eligibility (default $100M).
- `include_all` (query, optional, default: false): If true, include funds below eligibility thresholds (default false).

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "total_funds": 4823,
    "eligible_funds": 3156,
    "leaderboard": [
      {
        "rank": 1,
        "cik": "1067983",
        "company_name": "BERKSHIRE HATHAWAY INC",
        "portfolio_return_pct": 8.45,
        "portfolio_value": 267000000000,
        "holdings_count": 42,
        "price_coverage_pct": 97.3,
        "top_contributors": [
          {
            "ticker": "AAPL",
            "return_pct": 12.3,
            "contribution_pct": 4.2
          }
        ],
        "top_detractors": [
          {
            "ticker": "KHC",
            "return_pct": -5.1,
            "contribution_pct": -0.3
          }
        ]
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 3156,
      "limit": 25,
      "offset": 0,
      "has_more": true
    },
    "filters": {
      "min_holdings": 10,
      "min_aum": 100000000
    },
    "disclaimer": "Returns are estimated from 13F long equity positions only using VWAP-based entry price estimation. Not actual fund returns."
  }
}
```

### GET /api/v1/form-13f/market-rotation

Detect institutional rotation between value/growth and cyclical/defensive sector buckets. Computes flow ratios from pre-aggregated sector-level 13F data and classifies rotation strength into 5 tiers (Strong/Moderate Value or Growth, Balanced). Supports quarter-over-quarter comparison to track rotation shifts. Response includes quarter_metadata (quarter, filing_deadline, is_complete, days_until_deadline) indicating whether the quarter's data is complete or still accumulating.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `success` on a 2xx response. Custom envelope (not the standard `ApiResponse`) — `data` carries the four headline ratios + four sector buckets directly.
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end. Echoed from the request; defaults to the latest available quarter.
- `data.value_growth_ratio` (number): Ratio = `value_bucket_total_flow / growth_bucket_total_flow`. Values >1 indicate rotation INTO value (institutions favoring Financials/Healthcare/Energy/Utilities); values <1 indicate rotation INTO growth (favoring Technology/Consumer Cyclical/Communication Services/Real Estate). 5-tier classification surfaced in `value_growth_signal`.
- `data.value_growth_signal` (string): 5-tier rotation classification derived from `value_growth_ratio`: `Strong Value Rotation` (ratio ≥2), `Moderate Value Rotation` (≥1.3), `Balanced` (0.77-1.3), `Moderate Growth Rotation` (≥0.5), `Strong Growth Rotation` (<0.5). The single most-used field for macro-rotation dashboards.
- `data.cyclical_defensive_ratio` (number): Ratio = `cyclical_bucket_total_flow / defensive_bucket_total_flow`. Cyclical bucket = Consumer Cyclical, Technology, Industrials, Basic Materials, Energy (sectors that benefit from economic expansion). Defensive bucket = Utilities, Healthcare, Consumer Defensive, Communication Services (sectors that hold up in downturns). Values >1 indicate rotation INTO cyclicals (risk-on); values <1 indicate rotation INTO defensives (risk-off / recession-positioning).
- `data.cyclical_defensive_signal` (string): 5-tier rotation classification derived from `cyclical_defensive_ratio`: `Strong Cyclical Rotation` (≥2), `Moderate Cyclical Rotation` (≥1.3), `Balanced` (0.77-1.3), `Moderate Defensive Rotation` (≥0.5), `Strong Defensive Rotation` (<0.5). Useful for macro-positioning context (risk-on vs risk-off institutional posture).
- `data.sector_buckets` (object): Per-bucket breakdown: `{ value: {total_flow, sectors[]}, growth: {...}, cyclical: {...}, defensive: {...} }`. Each bucket lists the constituent sectors with their individual `fund_flow` and `total_value` — useful for understanding which sectors are driving the rotation signal.
- `data.sector_buckets.value` (object): Value bucket: Financials, Healthcare, Energy, Utilities. Shape: `{ total_flow, sectors: [{ sector, fund_flow, total_value }, ...] }`. `total_flow` is the sum of constituent `fund_flow` values (USD, post-Plan-51 thousands correction).
- `data.sector_buckets.growth` (object): Growth bucket: Technology, Consumer Cyclical, Communication Services, Real Estate. Same shape as `value` bucket. Tech sector typically dominates this bucket's flow.
- `data.sector_buckets.cyclical` (object): Cyclical bucket: Consumer Cyclical, Technology, Industrials, Basic Materials, Energy. Note: Technology and Consumer Cyclical appear in BOTH growth and cyclical buckets — this is intentional (multi-classification per macro literature).
- `data.sector_buckets.defensive` (object): Defensive bucket: Utilities, Healthcare, Consumer Defensive, Communication Services. Same multi-classification overlap with growth bucket on Communication Services.
- `data.compare` (object (nullable)): QoQ comparison block — present ONLY when `?compare=prev`. Shape: `{ value_growth_shift: 'Moderate Growth -> Strong Value', cyclical_defensive_shift: 'Balanced -> Moderate Cyclical', value_growth_ratio_change: -0.18, cyclical_defensive_ratio_change: 0.42 }`. The string-encoded `*_shift` fields are designed for direct UI rendering ('Q3 was Strong Growth Rotation but Q4 shifted to Strong Value Rotation').
- `data.quarter_metadata` (object): Filing-completeness state for the quarter: `{ quarter, filing_deadline, is_complete, days_until_deadline }`. Same shape as [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress). `is_complete=false` during filing season — gate downstream rotation analysis until the quarter has matured (sparse early-season data can produce misleading rotation signals).

**Utility:** Read-time computation from sec_13f_sector_summary. Value bucket = Financials, Healthcare, Energy, Utilities. Growth = Technology, Consumer Cyclical, Communication Services, Real Estate. Cyclical = Consumer Cyclical, Technology, Industrials, Basic Materials, Energy. Defensive = Utilities, Healthcare, Consumer Defensive, Communication Services. Returns ratio, label, and per-sector fund_flow breakdown within each bucket.

**Use case:** Building a macro rotation dashboard: 'Is institutional money rotating from growth to value this quarter?' Use ?compare=prev to see the shift between quarters, e.g., 'Q3 was Strong Growth Rotation but Q4 shifted to Strong Value Rotation'. Combine with sector drill-down from /aggregation/by-sector for full picture.

**Parameters:**
- `quarter` (query, optional): Quarter end date YYYY-MM-DD (e.g. 2025-12-31). Defaults to latest available.
- `compare` (query, optional): Set to 'prev' to include QoQ comparison with previous quarter. Shows rotation shift (e.g., 'Strong Growth -> Moderate Value').

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "value_growth_ratio": 0.71,
    "value_growth_signal": "Moderate Growth Rotation",
    "cyclical_defensive_ratio": 2.14,
    "cyclical_defensive_signal": "Strong Cyclical Rotation",
    "sector_buckets": {
      "value": {
        "total_flow": 150000000,
        "sectors": [
          {
            "sector": "Financial Services",
            "fund_flow": 80000000,
            "total_value": 500000000
          }
        ]
      },
      "growth": {
        "total_flow": 210000000,
        "sectors": [
          {
            "sector": "Technology",
            "fund_flow": 150000000,
            "total_value": 900000000
          }
        ]
      }
    }
  }
}
```

### GET /api/v1/form-13f/cross-filing-signals

Identify smart money convergence: securities where both corporate insiders (Form 4 open-market purchases) and institutional funds (13F accumulation) are buying in overlapping time windows. Each signal includes insider buyer count, buy value, institutional fund flow, fund count, and an investment attractiveness score (0-100) computed from market data components. Response includes quarter_metadata (quarter, filing_deadline, is_complete, days_until_deadline) indicating whether the quarter's data is complete or still accumulating.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): Always `success` on a 2xx response. Custom envelope (not the standard `ApiResponse`) — `data` carries `quarter`, `time_window`, `signal_count`, `signals[]`, `coverage_note`.
- `data.quarter` (string): ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end. Echoed from the request; defaults to the latest available quarter.
- `data.time_window` (object): The exact insider-purchase window used for cross-filing convergence: `{ start, end, description }`. `start = quarter_start - window_before` (default 30 days); `end = quarter_end + window_after` (default 45 days). The 45-day default tail captures Form 4 filings that arrive AFTER the 13F quarter-end (insiders have 2 business days post-trade to file Form 4).
- `data.signal_count` (integer): Total number of convergence signals — securities with BOTH insider buying (Form 4 P-code purchases) AND institutional accumulation (positive 13F fund_flow) within `time_window`. Capped by `limit` (default 50).
- `data.signals` (array): Per-security convergence signals. Sorted by `fund_flow DESC` by default. Each signal carries the institutional-side aggregates from `sec_13f_summary` AND the insider-side aggregates from `insider.transactions_non_derivative` (P-code = open-market purchase) — the headline 'smart money convergence' rows.
- `data.signals[].cusip` (string): 9-character CUSIP — natural primary key for the convergence row.
- `data.signals[].symbol` (string (nullable)): Resolved ticker (canonical hyphen form for multi-class issuers). Null when CUSIP is unmapped.
- `data.signals[].name_of_issuer` (string): Issuer name from `cusip_security_catalog`. Casing preserved verbatim.
- `data.signals[].issuer_cik` (string (nullable)): Issuer CIK as a 10-character zero-padded string (the COMPANY's CIK, NOT the institutional filer's CIK). Null when the issuer-CIK enrichment is missing for this CUSIP.
- `data.signals[].fund_flow` (number): Net institutional dollar flow this quarter (USD, post-Plan-51 thousands correction). For convergence signals to be meaningful, this is always positive.
- `data.signals[].fund_count` (integer): Number of distinct institutional funds with a position in this CUSIP this quarter.
- `data.signals[].new_buys_count` (integer): Number of institutional funds that opened a NEW position this quarter (no prior-quarter row). Sub-aggregate of `fund_count`. High new_buys_count + insider buying = strong conviction signal.
- `data.signals[].total_value` (number): Total institutional position value this quarter, in USD. Sum of `value_usd` across all funds holding this CUSIP.
- `data.signals[].total_shares` (number): Total shares held across all institutional funds this quarter. NOT split-adjusted — for split-adjusted aggregations use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/ticker-research/get-tickers-ticker-fund-trends).
- `data.signals[].fund_flow_pct` (number): `fund_flow / total_value * 100` — flow significance relative to total institutional ownership. 100% means ALL institutional value is from this quarter's flow (i.e. brand-new institutional discovery).
- `data.signals[].insider_buyer_count` (integer): Distinct count of insiders who made open-market PURCHASES (Form 4 P-code) within `time_window`. Use `min_insider_buyers=2` to filter for multi-insider convergence (e.g. CEO AND CFO both buying — a much stronger signal than a single insider).
- `data.signals[].insider_buy_value` (number): Total dollar value of insider purchases (Form 4 P-code) within `time_window`, in USD. Computed as `sum(shares_traded * price_per_share)` across all P-code transactions for the issuer's CIK.
- `data.signals[].first_buy_date` (string): ISO `YYYY-MM-DD` date of the EARLIEST insider purchase within `time_window`. Useful for sequencing analysis ('insider bought first, then funds piled in').
- `data.signals[].last_buy_date` (string): ISO `YYYY-MM-DD` date of the LATEST insider purchase within `time_window`. `last_buy_date - first_buy_date = insider_buying_duration` — concentrated buying (small range) is a stronger signal than spread-out buying.
- `data.signals[].attractiveness_score` (number (nullable)): 0-100 investment attractiveness composite score — only computed for the TOP 20 signals by fund_flow (Yahoo Finance enrichment is rate-limited; results Redis-cached 24h). Combines 5 components: ownership ratio, fund stability, market cap, inverse volatility, and fund flow significance. Null for signals 21+ (out of enrichment budget).
- `data.signals[].attractiveness_components` (array (nullable)): Individual scoring component breakdown: `[{ name, score }, ...]`. Components are independently nullable — partial scores computed from available data (e.g. if Yahoo Finance volatility lookup fails, the volatility component is omitted but the others still surface). Null for signals beyond the top-20 enrichment cap.
- `data.coverage_note` (string): Human-readable note on enrichment coverage: e.g. `'4/4 signals enriched with attractiveness scores (top 20 by fund flow).'`. Render in UI to set expectations on which signals have full vs partial scoring.

**Utility:** Cross-schema SQL join between insider.transactions_non_derivative (Form 4 P-code purchases) and sec_13f_summary (13F quarterly aggregates) via ticker matching. Attractiveness score has 5 components: ownership ratio, fund stability, market cap, volatility (inverse), and fund flow significance. Components are independently nullable -- partial scores computed from available data. Top signals by fund flow are enriched with Yahoo Finance market data (Redis-cached 24h).

**Use case:** Screen for securities with institutional AND insider buying convergence -- a powerful signal because insiders have inside knowledge and institutions have research teams, so agreement suggests strong conviction. Use min_insider_buyers=2 to filter for multi-insider buying (CEO + CFO both buying). Adjust window_before/window_after to widen or narrow the insider purchase window around the 13F quarter.

**Parameters:**
- `quarter` (query, optional): Quarter end date YYYY-MM-DD (e.g. 2025-12-31). Defaults to latest available.
- `window_before` (query, optional, default: 30): Days before quarter start to look for insider purchases (0-90).
- `window_after` (query, optional, default: 45): Days after quarter end to look for insider purchases (0-90).
- `limit` (query, optional, default: 50): Max results (1-100).
- `min_insider_buyers` (query, optional, default: 1): Minimum distinct insider buyers to include in results.
- `min_fund_flow` (query, optional, default: 0): Minimum institutional fund flow ($) to include in results.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "quarter": "2025-12-31",
    "time_window": {
      "start": "2025-09-01",
      "end": "2026-02-14",
      "description": "Insider purchases from 2025-09-01 to 2026-02-14 overlapping 13F quarter 2025-12-31"
    },
    "signal_count": 4,
    "signals": [
      {
        "cusip": "92556V106",
        "symbol": "VTRS",
        "name_of_issuer": "VIATRIS INC",
        "issuer_cik": "0001792044",
        "fund_flow": 14467137,
        "fund_count": 3,
        "new_buys_count": 3,
        "total_value": 14467137,
        "total_shares": 1162019,
        "fund_flow_pct": 100,
        "insider_buyer_count": 1,
        "insider_buy_value": 2220.63,
        "first_buy_date": "2025-11-03",
        "last_buy_date": "2025-11-03",
        "attractiveness_score": 58.1,
        "attractiveness_components": [
          {
            "name": "stability",
            "score": 3.26
          },
          {
            "name": "fund_flow_significance",
            "score": 20
          }
        ]
      }
    ],
    "coverage_note": "4/4 signals enriched with attractiveness scores (top 20 by fund flow)."
  }
}
```

### GET /api/v1/form-13f/search

Search for tracked funds by name, symbol, or CIK.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `results` (array): Array of matching funds. Sorted by `filing_count DESC` (most-active filers ranked first). Empty array on no match. Pass back `cik` from this response as input to [GET /api/v1/form-13f/fund/{cik}](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-cik) or other 13F endpoints. For richer alias-aware autocomplete (e.g. `buffett` → Berkshire), prefer [GET /api/v1/form-13f/filers](/docs/institutional-holdings/form-13f-api/get-form-13f-filers).
- `results[].cik` (string): Filer CIK as a 10-character zero-padded string. Berkshire = `0001067983`; Bridgewater = `0001350694`; Renaissance = `0001037389`.
- `results[].name` (string): Registrant name AS FILED on the most recent 13F-HR (typically all-caps in EDGAR convention). Casing preserved verbatim.
- `results[].symbol` (string (nullable)): Fund's public ticker symbol when one exists (rare for institutional managers — most are LPs / partnerships without a public listing). Null for the vast majority of 13F filers. Searchable via the `q` parameter (e.g. `q=BRK` matches both Berkshire's name AND symbol).
- `results[].filing_count` (integer): Total cumulative 13F filings ingested for this filer. Used as the search-rank tiebreaker.
- `count` (integer): Total number of matches in `results[]` (echoes back `results.length`). For unbounded preloads (`q='' AND limit=5000`), this caps at the configured `limit`.

**Utility:** Find funds by name, symbol, or CIK number. When q is empty, returns all active funds (useful for preloading autocomplete). Query must be at least 2 characters when provided.

**Use case:** Autocomplete search bar for finding 'Tiger Global', 'Bridgewater', or CIK '1067983'. Use empty q with limit=5000 to preload all funds.

**Parameters:**
- `q` (query, optional): Search by fund name, symbol, or CIK. Empty returns all active funds. Min 2 chars.
- `limit` (query, optional, default: 10): Max results (up to 5000)

**Sample response:**
```json
{
  "results": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "symbol": "BRK-A",
      "filing_count": 92
    },
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "symbol": "BRK-B",
      "filing_count": 92
    }
  ],
  "count": 2
}
```

### GET /api/v1/form-13f/holdings/search

Find which funds hold a specific security by ticker or CUSIP.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `query` (string): Echoed-back search query — the literal `q` value as received. Useful for caching keys client-side.
- `resolved` (object): CUSIP-resolution metadata: `{ ticker, cusip, name_of_issuer, cusip_chain }`. The chain expansion handles corporate actions — for example a query for `GOOGL` automatically expands to BOTH the pre-2014-share-class-restructuring CUSIPs AND the post-restructuring CUSIPs, so the holders list correctly captures the fund's economic exposure across the corporate action.
- `resolved.cusip_chain` (array): Array of CUSIPs that resolve to the same security after corporate-action successor mapping. For Apple: `['037833100']` (single CUSIP, no successors). For Alphabet: includes both pre- and post-2014 GOOG/GOOGL CUSIPs. The reverse-lookup query expands across the full chain.
- `period` (string): ISO `YYYY-MM-DD` reporting quarter. Echoed from request; defaults to the latest available quarter.
- `holders` (array): Array of institutional funds holding the security in the requested period. Sorted by `value_usd DESC` (largest holder first). Page size capped by `limit` (default 20, max 100). Each row carries the fund's identity + position size — drill-down to the fund's full portfolio via [GET /api/v1/form-13f/fund/{cik}](/docs/institutional-holdings/form-13f-api/get-form-13f-fund-cik).
- `holders[].cik` (string): Fund CIK as a 10-character zero-padded string. Stable join key against the rest of the 13F surface.
- `holders[].name` (string): Fund's registrant name AS FILED on the 13F-HR (typically all-caps in EDGAR convention).
- `holders[].shares` (number): Share count held by this fund in the period. NOT split-adjusted (as-filed view) — for split-adjusted aggregations across history use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/ticker-research/get-tickers-ticker-fund-trends). For BRK-A specifically, share counts are tiny (Berkshire-A trades at $700K+/share so even mega-holdings are only thousands of shares).
- `holders[].value_usd` (number): Position value in USD (post-Plan-51 thousands correction). Sum of `shares * price` from the filed 13F-HR.
- `holders[].pct_of_portfolio` (number (nullable)): Position weight as a percentage of the fund's total portfolio value. Useful for finding the fund's HIGH-CONVICTION holders ('Apple is 38% of Berkshire's book' = much stronger conviction signal than 'Apple is 0.4% of Vanguard's book'). Null when the fund's `portfolio_value` aggregation is missing.
- `holders[].change_shares` (number): QoQ share-count delta (`current_shares - prior_shares`). Positive = fund added; negative = fund trimmed. Zero for unchanged positions. NOT split-adjusted.
- `holders[].status` (string): Position-status label: `New` (no prior position), `Increased`, `Decreased`, `Unchanged`, `Closed` (in prior quarter, gone now). The most signal-rich status for momentum analysis is `New` — multiple new-buy holders for the same security is a conviction signal.
- `count` (integer): Total holder count after pagination cap. NVIDIA Q4 2025: ~3,200 distinct holders (heavily covered by institutions); micro-cap stocks: 5-50 holders.

**Utility:** Reverse-lookup: given a ticker or CUSIP, find all tracked institutional funds that hold that security with their share counts and values. Automatically expands CUSIP successor chains for corporate actions.

**Use case:** Answer 'Which hedge funds hold Apple?' by searching for AAPL. Useful for building institutional holder screens similar to WhaleWisdom.

**Parameters:**
- `q` (query, required): Ticker symbol (e.g. AAPL) or CUSIP (e.g. 037833100). Min 2 chars.
- `limit` (query, optional, default: 20): Max fund results (up to 100)
- `period` (query, optional): Report period filter (YYYY-MM-DD). Defaults to latest.

**Sample response:**
```json
{
  "query": "AAPL",
  "resolved": {
    "ticker": "AAPL",
    "cusip": "037833100",
    "name_of_issuer": "APPLE INC",
    "cusip_chain": [
      "037833100"
    ]
  },
  "period": "2025-09-30",
  "holders": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "shares": 300000000,
      "value_usd": 78240000000,
      "pct_of_portfolio": 25.4,
      "change_shares": -10000000,
      "status": "Decreased"
    },
    {
      "cik": "0001364742",
      "name": "BLACKROCK INC.",
      "shares": 1100000000,
      "value_usd": 287000000000,
      "pct_of_portfolio": 5.8,
      "change_shares": 12000000,
      "status": "Increased"
    },
    {
      "cik": "0000884144",
      "name": "VANGUARD GROUP INC",
      "shares": 1380000000,
      "value_usd": 360000000000,
      "pct_of_portfolio": 6.2,
      "change_shares": 8000000,
      "status": "Increased"
    }
  ],
  "count": 3
}
```

### GET /api/v1/form-13f/filing-stats

Get 13F filing statistics and calendar timeline: funds filed, % reported, deadline status, AUM, and key dates for the 13F filing calendar.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `data.period` (string): ISO `YYYY-MM-DD` reporting quarter — always a calendar quarter end (03-31, 06-30, 09-30, 12-31). Echoed from request; defaults to the last completed quarter (between seasons) or the current filing period (during filing season).
- `data.deadline` (string): ISO `YYYY-MM-DD` SEC 45-day filing deadline for `period`. Computed as `period + 45 days`, rolled to the next business day if the deadline falls on a weekend / federal holiday. The 4 standard 13F deadlines fall around mid-Feb, mid-May, mid-Aug, mid-Nov.
- `data.deadlineStatus` (string): One of `upcoming` (deadline > today, filing season is ACTIVE), `today` (deadline == today, last-day rush), `past` (deadline < today, filing season COMPLETE for this quarter). Use to gate UI banners ('Filing season ends Feb 14, 22 days remaining' vs 'Q4 2025 filing complete').
- `data.totalFundsFiled` (integer): Number of distinct CIKs that have filed a 13F-HR (or 13F-NT) for `period`. Note this can EXCEED `previousQuarterFilers` (yielding `percentOfFundsReported > 100`) when net-new filers register or returning-from-hiatus filers report. Q4 2025 example: 8,381 funds filed against 8,010 prior-quarter baseline = 104.6%.
- `data.percentOfFundsReported` (number): `totalFundsFiled / previousQuarterFilers * 100`. Values ~100% during normal filing seasons; >100% when net-new registrants outpace dropouts; <100% during early filing season (still accumulating). The headline filing-progress metric.
- `data.previousQuarterFilers` (integer): Baseline count = number of distinct CIKs that filed a 13F-HR for the PRIOR quarter (`period - 3 months`). Used as the denominator for `percentOfFundsReported`. NOT the same as the recurring-filer baseline (CIK intersection of LAST TWO quarters) used by [GET /api/v1/form-13f/filing-progress](/docs/institutional-holdings/filing-progress-tracking/get-form-13f-filing-progress) — this endpoint uses the simpler single-quarter baseline.
- `data.totalFilings` (integer): Total number of 13F filings for the period — includes ORIGINAL 13F-HRs, AMENDMENTS (13F-HR/A), and 13F-NT (notice-of-no-information) filings. Slightly higher than `totalFundsFiled` because some funds amend their original filings within the same quarter.
- `data.totalAUM` (number): Aggregate AUM observed so far this quarter, in USD. Sum of `value_usd` across all parsed 13F-HR filings for the period (post-Plan-51 thousands correction). Q4 2025 example: $46.0T total — this is roughly the entire US institutional equity market.
- `data.lateNoticeFilers` (integer): Number of CIKs that filed a 13F-NT (notice that no information table is forthcoming, typically because all positions are reported on another related 13F). Late-notice filers are usually subadvisors / parent-fund relationships — not 'late' in a regulatory sense.
- `data.previousPeriod` (string): ISO `YYYY-MM-DD` end-date of the prior quarter (`period - 3 months`). Always a calendar quarter end. Useful for QoQ comparison UI (rendering 'Q3 2025 vs Q4 2025' header).
- `data.previousDeadline` (string): ISO `YYYY-MM-DD` SEC deadline for the previous quarter. Same 45-day-rolling-to-business-day computation as `deadline`.
- `data.lastCompleteQuarterEnd` (string): ISO `YYYY-MM-DD` end-date of the most recent COMPLETED quarter — i.e. the most recent quarter where the SEC filing deadline has passed. Use for 'show me the last fully-reported quarter' selectors.
- `data.beforeLastCompleteQuarterEnd` (string): ISO `YYYY-MM-DD` end-date of the quarter before `lastCompleteQuarterEnd` — useful as the comparison baseline for 'this quarter vs prior quarter' charts that need to sidestep an in-progress filing season.
- `data.nextReportingPeriodStart` (string): ISO `YYYY-MM-DD` start-date of the next reporting period — i.e. the day AFTER the current quarter ends. Useful for forward-looking calendar UI ('Next 13F filing period starts Apr 1').
- `data.nextDeadline` (string): ISO `YYYY-MM-DD` SEC deadline for the next reporting period. The next time institutional managers will collectively flood EDGAR with filings.
- `data.daysUntilNextDeadline` (integer): `nextDeadline - today` in days. Render as a countdown ('86 days until Q1 2026 13F deadline'). Counts business days when within 2 weeks of the deadline; calendar days otherwise — see source for the exact computation rule.

**Utility:** Returns filing progress metrics plus the full 13F calendar context: previous deadline, last complete quarter, next reporting period, next deadline with days remaining. Defaults to the last completed quarter (when between filing seasons) or the current filing period (during filing season). Uses previous quarter's recurring filer count as baseline for percentage calculation.

**Use case:** Building a Key Metrics dashboard showing the 13F filing calendar (deadlines, quarter dates, days remaining) alongside filing progress stats (8,381 funds filed, 100% reported). Similar to WhaleWisdom's filing tracker with added calendar context.

**Parameters:**
- `period` (query, optional): Quarter-end date (YYYY-MM-DD), e.g. 2025-12-31 for Q4 2025. Defaults to the last completed quarter when between filing seasons, or the current filing period during active filing season.

**Sample response:**
```json
{
  "data": {
    "period": "2025-12-31",
    "deadline": "2026-02-17",
    "deadlineStatus": "past",
    "totalFundsFiled": 8381,
    "percentOfFundsReported": 104.6,
    "previousQuarterFilers": 8010,
    "totalFilings": 8460,
    "totalAUM": 46015643574871,
    "lateNoticeFilers": 105,
    "previousPeriod": "2025-09-30",
    "previousDeadline": "2026-02-17",
    "lastCompleteQuarterEnd": "2025-12-31",
    "beforeLastCompleteQuarterEnd": "2025-09-30",
    "nextReportingPeriodStart": "2026-04-01",
    "nextDeadline": "2026-05-15",
    "daysUntilNextDeadline": 86
  }
}
```

### GET /api/v1/form-13f/latest

Get the most recently parsed 13F filings across all funds, sorted by filing date descending.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `data` (array): Array of the N most-recently parsed 13F filings, sorted by `parsed_at DESC` (most-recently ingested first — NOT filed-at-DESC, since SEC EDGAR sometimes accepts filings out of order). Page size capped by `limit` (default 20, max 100). The 'live activity feed' shape.
- `data[].accession_no` (string): SEC accession number in canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0001012975-25-000452`). Pass to `POST /api/v1/form-13f/holdings` (via `accessionNo:...` query) or [GET /api/v1/sec/filings/{accession_number}](/docs/sec-filings/sec-filings-api/get-sec-filings-accession-number) for the raw filing artifact.
- `data[].fund_name` (string): Registrant name AS FILED on the 13F-HR cover page. Casing preserved verbatim (sometimes Title Case, sometimes ALL CAPS depending on the filer's submission style).
- `data[].cik` (string): Filer CIK as a 10-character zero-padded string. Stable join key against the rest of the 13F surface.
- `data[].period_of_report` (string): ISO `YYYY-MM-DD` reporting quarter end (always a calendar quarter end: 03-31, 06-30, 09-30, 12-31). 13F-HR is filed within 45 days of this date.
- `data[].filed_at` (string): ISO `YYYY-MM-DD` filing acceptance date — the date the SEC stamped the filing as accepted. Use for filing-cadence analysis (which managers file early vs late).
- `data[].table_value_total` (number): Total reported portfolio value across all positions in the filing, in USD (post-Plan-51 thousands-vs-actual-dollars normalization). NOTE: pre-Plan-51 the field was in SEC thousands (multiply by 1000 for actual dollars); the older `utility` text on this endpoint reflects that legacy semantics. Current values are USD direct — Knighthead Capital's $2.05B portfolio is `2053758064` USD, NOT `2.05M × 1000`.
- `data[].holdings_count` (integer): Number of position rows in the filing's information table. Knighthead-shaped boutique funds: 5-50; mid-tier hedge funds: 50-500; index-fund books (Vanguard, BlackRock): 3000-9000+. 13F-NT filings have 0 holdings (and are skipped by the parser, so they don't surface here).
- `data[].form_type` (string): SEC form type — `13F-HR` (original) or `13F-HR/A` (amendment). 13F-NT (notice-of-no-information) filings are skipped by the parser. Reference [SEC EDGAR form types](https://www.sec.gov/forms).
- `data[].is_amendment` (boolean): True when `form_type` ends with `/A`. Amendments often arrive months after the original — useful for surfacing 'late corrections' in the activity feed (e.g. a fund discovered they had under-reported a position).
- `data[].analysis` (object): QoQ position-change counts (raw): `{ new, closed, increased, decreased, unchanged }`. Computed against the prior-quarter `(cik, period - 3M)` baseline. All zero when no prior-quarter row exists (initial filing). Preserved for backwards compatibility — prefer `statistics` for new code.
- `data[].statistics` (object): QoQ position-change counts (frontend-friendly names): `{ new_positions, increased, decreased, closed, unchanged, prior_quarter_available }`. Same data as `analysis` with renamed fields PLUS the `prior_quarter_available` flag (false → all counts are zero, render the row as 'Initial filing'). Schema matches the WebSocket `new_13f_filing` event so frontends can render REST + WS payloads identically.
- `data[].parsed_at` (string): ISO-8601 UTC timestamp of when FinRadar's parser ingested the filing. May be 5min-2hours after `filed_at` depending on parser queue depth. Use as the sort key for 'most-recently ingested' feeds (not `filed_at`, which can be backdated by SEC EDGAR).
- `meta.total` (integer): Total number of filings returned (echoes back `data.length`). Capped by `limit`.

**Utility:** Returns the N latest completed 13F filings with fund metadata, portfolio value, holdings count, and quarter-over-quarter position change counts. Both `analysis` (raw counts) and `statistics` (frontend-friendly names) are included for compatibility. Values are in SEC thousands (multiply by 1000 for actual dollars).

**Use case:** Building a live-updating '13F Activity Feed' showing the most recent institutional filings as they are parsed. Each entry includes statistics counts so you can immediately see portfolio changes without fetching the full fund report. The `statistics` field uses the same schema as WebSocket 13f_summary events for consistent frontend rendering.

**Parameters:**
- `limit` (query, optional, default: 20): Number of filings to return (max 100)

**Sample response:**
```json
{
  "data": [
    {
      "accession_no": "0001012975-25-000452",
      "fund_name": "Knighthead Capital Management, LLC",
      "cik": "0001512397",
      "period_of_report": "2025-06-30",
      "filed_at": "2025-08-14",
      "table_value_total": 2053758064,
      "holdings_count": 7,
      "form_type": "13F-HR",
      "is_amendment": false,
      "analysis": {
        "new": 3,
        "closed": 4,
        "increased": 0,
        "decreased": 1,
        "unchanged": 3
      },
      "statistics": {
        "new_positions": 3,
        "increased": 0,
        "decreased": 1,
        "closed": 4,
        "unchanged": 3,
        "prior_quarter_available": true
      },
      "parsed_at": "2026-02-16T08:14:23.797279"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

### GET /api/v1/form-13f/filers

Search or list all 13F filers by fund name, CIK, manager name, or well-known alias, with filing counts, last-filed dates, and authorized signer.

**Token cost:** 10 tokens per call

**Response fields:**
- `filers` (array): Array of matching 13F filers, sorted by `filing_count DESC` (most-active filers first) — alias matches are boosted to the top. Empty array on no match. Use `cik` from this response as input to `POST /api/v1/form-13f/holdings` and `POST /api/v1/form-13f/cover-pages`.
- `filers[].cik` (string): Filer CIK as a 10-character zero-padded string. The stable join key for this filer across the entire 13F surface (`/holdings`, `/cover-pages`, `/aggregation/by-ticker`, `/fund-performance`). Berkshire Hathaway is `0001067983`; Bridgewater is `0001350694`.
- `filers[].name` (string): Registrant name AS FILED on the most recent 13F (typically all-caps in EDGAR convention, e.g. `BERKSHIRE HATHAWAY INC`). NOT alias-normalized — for the user-friendly alias (e.g. 'Warren Buffett') consult the `filer_aliases` admin table. Casing preserved verbatim.
- `filers[].latest_filed_at` (string (nullable)): ISO-8601 UTC timestamp of the filer's most recent 13F filing. Null when the filer has registered but never filed. Use to detect inactive/dissolved filers — values older than ~7 months indicate the filer skipped the most recent quarterly deadline (45 days post-quarter-end).
- `filers[].filing_count` (integer): Total cumulative 13F filings ingested for this filer (across all quarters and amendments). Active large managers (Berkshire, Vanguard, BlackRock) have 90-100+ filings going back to 2013 (FinRadar's coverage start); newer managers have lower counts.
- `filers[].latest_aum_usd` (number (nullable)): Latest reported assets-under-management in USD, derived from the most recent 13F's aggregate position value (sum of `value` column post-thousands-correction). Null when the filer's holdings have not yet been re-aggregated by the `sec_13f_summary` matview (~6h refresh cadence post-filing). Berkshire AUM is typically $300-400B; mid-tier hedge funds $1-10B; family offices $50M-1B.
- `meta` (object): Result metadata block: `{ total: integer, limit: integer }`. `total` reflects the full match count (not just the page); `limit` echoes the effective limit after server-side capping at 10000.

**Since:** v1.0.0

**Utility:** Find any institutional filer across the full 13F universe (8,500+ filers). Searchable by fund name, CIK, manager/signer name (signature_name), AND a curated filer_aliases database table that maps well-known fund managers to their fund CIKs. For example, searching 'buffett' finds Berkshire Hathaway, 'ackman' finds Pershing Square, 'dalio' finds Bridgewater, etc. Returns filing counts, last filed date, reporting period, and authorized signer name. Supports limit up to 10,000 for client-side preloading. Aliases can be managed via the admin API at /api/v1/admin/filer-aliases.

**Use case:** Building an autocomplete search box like StockCircle where typing 'Warren Buffett' or just 'buffett' finds Berkshire Hathaway via the filer_aliases table, or typing 'Bridgewater' finds the fund by company name. Use limit=10000 to preload all filers for instant client-side search.

**Parameters:**
- `q` (query, optional): Free-text search across (1) fund/registrant name, (2) CIK (exact-match), (3) signature_name (the authorized signer on the most recent 13F filing — useful for finding 'who manages this fund'), AND (4) the curated `filer_aliases` table that maps well-known fund managers to their fund CIKs (e.g. `buffett` → Berkshire Hathaway, `ackman` → Pershing Square, `dalio` → Bridgewater, `burry` → Scion Asset Management). Case-insensitive. Omit `q` to list top filers by `filing_count` (descending).
- `limit` (query, optional, default: 20): Maximum filers returned (up to 10,000). The 10K cap supports client-side preloading the full filer universe for instant in-browser autocomplete (StockCircle-style UX). For typical query-driven autocomplete, 20-50 is plenty; for full-list preload use 10000.

**Sample response:**
```json
{
  "filers": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "latest_filed_at": "2026-02-14T15:32:11.000Z",
      "filing_count": 92,
      "latest_aum_usd": 308000000000
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### POST /api/v1/form-13f/holdings

Search raw 13F holdings grouped by filing using Lucene-like query syntax.

**Token cost:** 10 tokens per call

**Response fields:**
- `cik` (string): Filer CIK as a 10-character zero-padded string. Echoed back from the request — useful for asserting your client passed the CIK you intended after the server's CIK-padding normalization (handles 6/7/10-char input forms).
- `period` (string): ISO `YYYY-MM-DD` reporting period end (always a calendar quarter end: 03-31, 06-30, 09-30, 12-31). The 13F is filed within 45 days of this date — for delivery tracking against the 45-day deadline, see `/api/v1/form-13f/filing-progress`.
- `holdings` (array): Array of position rows in the filing — one row per CUSIP. Amendments collapse to the latest filing per `(cik, period)` (so a 13F-HR/A overrides the original 13F-HR). Sorted by `value_usd DESC` by default. Empty array on legitimate empty filings (rare but valid for 13F-HR/A amendments that zero out a previously-reported holding).
- `holdings[].cusip` (string): 9-character CUSIP as filed. The natural primary key for the position. Note: filers occasionally report 8-char CUSIPs (missing check digit) — these are zero-padded server-side. For chain-aware queries (CUSIP successor mappings across mergers), use the `holdings.cusip:` query syntax which auto-expands the chain.
- `holdings[].ticker` (string (nullable)): Resolved ticker from CUSIP→ticker mapping via `cusip_security_catalog`. Null when (a) the security has no ticker (debt instruments, private placements), (b) the CUSIP is unmapped (~3% of rows in steady state), or (c) the issuer was delisted before our enrichment ran. Multi-class issuers preserve the actual filed class (e.g. `BRK-A` vs `BRK-B`).
- `holdings[].issuer_name` (string): Issuer name AS FILED on the 13F (typically all-caps in EDGAR convention, e.g. `APPLE INC`). NOT enriched from Sharadar — for the canonical name use the `cusip_security_catalog` lookup. Multi-class issuers may surface different name variants depending on which share class the filer reported.
- `holdings[].shares` (number): Share count as reported on the 13F. NOT split-adjusted server-side (preserves the as-filed view) — for split-adjusted aggregations use `/api/v1/tickers/{ticker}/fund-trends`. For securities reported as principal value (debt) the value semantics differ; check the `holdings_quality` side-table flag for outliers.
- `holdings[].value_usd` (number): Total position USD value AS FILED. Pre-Q3 2022 SEC instruction was 'value reported in thousands'; post-Q3 2022 instruction is 'value reported in actual dollars' — FinRadar's parser auto-detects and normalizes via the `holdings_quality` side-table. The `valueCorrected` / `correctionMethod` / `originalValueTotal` metadata fields surface when correction was applied (see Plan 51 holdings-quality layer for full doc).
- `holdings[].putCall` (string (nullable)): Derivative position type: `"Put"`, `"Call"`, or null for common stock. Options positions are a small minority of 13F filings (most managers report only equity); when present, treat them as a separate signal class — option holdings can dwarf the common-stock book in notional value.
- `holdings[].changeShares` (number (nullable)): Quarter-over-quarter share-count delta (`current_shares - prior_shares`) — present ONLY when `includeChanges=true`. Positive means the fund added shares; negative means it sold. Null when no prior-quarter row exists (i.e. the position is `New`).
- `holdings[].changePercent` (number (nullable)): Quarter-over-quarter percentage change in share count, computed as `(current - prior) / prior` (NOT value-based). Present ONLY when `includeChanges=true`. Null for `New` positions (no prior baseline). For `Closed` positions (in previous quarter, gone this quarter) value is `-1.0`.
- `holdings[].status` (string (nullable)): Position-status label — one of `New` (no prior position), `Increased`, `Decreased`, `Unchanged` (share count exact match), `Closed` (prior position fully sold; appears in `closedPositions` array, NOT in `holdings`). Present ONLY when `includeChanges=true`. The most signal-rich status for momentum analysis is `New` (initial conviction).
- `closedPositions` (array (nullable)): Positions that existed in the prior quarter's filing but are absent from this quarter's — i.e. fully-exited positions. Present ONLY when `includeChanges=true`. Same row shape as `holdings[]`; `status='Closed'` and `changeShares = -prior_shares`. Critical for tracking fund exits — fund flows often surface here as 'big position closed' before the price impact is observable.
- `previousPeriod` (string (nullable)): ISO `YYYY-MM-DD` end-date of the comparison quarter used for QoQ deltas. Present ONLY when `includeChanges=true`. Typically `period - 3 months`, but funds with skipped quarters compare against the most recent prior filing (NOT a stale baseline).

**Since:** v1.0.0

**Utility:** The headline analytics endpoint of FinRadar's institutional-holdings module — query any combination of CIK, date range, ticker, or CUSIP across 8M+ raw 13F holdings rows. Returns per-filing position rows (NOT pre-aggregated) with full voting authority, investment discretion, and put/call data preserved as filed. The bread-and-butter workflow for hedge-fund whale-watching: pass `cik:1067983 AND periodOfReport:2025-12-31` to get Berkshire Hathaway's Q4 2025 book exactly as filed. Pass `includeChanges=true` to also receive QoQ deltas (`changeShares`, `changePercent`, `status`, `previousPeriod`, `closedPositions`) — critical for momentum-detection workflows. Ticker/CUSIP queries auto-expand through CUSIP successor chains so a query for `holdings.ticker:GOOGL` will correctly capture the position even after Alphabet's 2014 share-class restructuring. Value-correction metadata (`valueCorrected`, `correctionMethod`, `originalValueTotal`) is included on every row to flag the 13F thousands-vs-actual-dollars reporting issue (Plan 51 holdings-quality layer). For lighter cover-page-only queries use `POST /api/v1/form-13f/cover-pages`.

**Use case:** Retrieve Berkshire Hathaway's exact holdings as filed for Q3 2024, including share counts, voting authority, and CUSIP-level detail. Useful for regulatory analysis, filing-level audits, and replicating sec-api.io queries.

**Parameters:**
- `query` (body, required): Lucene-like query string. Field-scoped: `cik:1067983` (filer CIK, with or without zero-padding), `periodOfReport:2024-09-30` (exact quarter end), `periodOfReport:[2024-01-01 TO 2024-12-31]` (range), `filedAt:[A TO B]` (filing date range), `formType:"13F-HR"`, `holdings.ticker:AAPL` (chain-aware), `holdings.cusip:037833100` (chain-aware), `accessionNo:0001067983-24-000123`. Combine with `AND`/`OR`/`NOT`. Bare-word queries are matched against issuer name.
- `from` (body, optional, default: 0): Zero-based pagination offset (NUMBER of filings to skip — NOT a date despite the name). Increment by `size` to walk pages: `from=0` → page 1, `from=50` → page 2 (when `size=50`). Capped at 10000 server-side; for deeper backfills use date-range chunking via `periodOfReport:[A TO B]`.
- `size` (body, optional, default: 50): Number of filings (NOT individual holdings rows) to return per page, capped at 50 server-side. Each filing can carry 1-3000+ holdings rows so total payload size scales with `size × avg_holdings_per_filing`. For Berkshire-shaped books expect ~50 holdings per filing; for index-fund books (Vanguard, BlackRock) expect ~3000+.
- `sort` (body, optional): Sort specification array (sec-api.io shape). Each element is `{ <field>: { order: 'asc' | 'desc' } }`. Common: `[{"filedAt": {"order": "desc"}}]` (most recent first), `[{"periodOfReport": {"order": "asc"}}]` (chronological for time-series). Defaults to `filedAt DESC` when omitted.
- `includeChanges` (body, optional, default: false): When `true` AND `holdings.ticker` is set in the query, adds QoQ change fields to each ticker-matching holding: `changeShares` (int), `changePercent` (float), `status` (`New`/`Increased`/`Decreased`/`Unchanged`/`Closed`). Also returns `closedPositions` array (positions present in prior quarter but absent now) and `previousPeriod` (quarter used for comparison). Uses canonical CUSIP matching via `cusip_normalized` so cross-quarter corporate actions (mergers, ticker changes, share-class collapses) are correctly tracked. ~30-50% latency overhead per call.

**Query filters:**
- `cik:1067983` — Fund CIK (exact match)
- `periodOfReport:2024-09-30` — Exact quarter end date
- `periodOfReport:[2024-01-01 TO 2024-12-31]` — Period date range
- `filedAt:[2024-01-01 TO 2024-12-31]` — Filing date range
- `formType:"13F-HR"` — Form type filter
- `holdings.ticker:AAPL` — Filter by ticker (via CUSIP mapping, chain-aware)
- `holdings.cusip:037833100` — Filter by CUSIP (chain-aware)
- `accessionNo:0001067983-24-000123` — Specific filing accession number

**Sample response:**
```json
{
  "cik": "0001067983",
  "period": "2025-12-31",
  "holdings": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "issuer_name": "APPLE INC",
      "shares": 905560000,
      "value_usd": 174032404400,
      "putCall": null,
      "changeShares": -10000000,
      "changePercent": -1.09,
      "status": "Decreased"
    }
  ],
  "previousPeriod": "2025-09-30"
}
```

### POST /api/v1/form-13f/cover-pages

Search 13F filing cover pages (metadata only, no holdings).

**Token cost:** 10 tokens per call

**Response fields:**
- `filings` (array): Array of cover-page rows, sorted per the `sort` parameter (default: `filedAt DESC`). Each row is one 13F filing's metadata — original and amendment filings appear as separate rows (NOT collapsed). Empty array on no match.
- `filings[].cik` (string): Filer CIK as a 10-character zero-padded string. Stable join key against the rest of the 13F surface.
- `filings[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `POST /api/v1/form-13f/holdings` (via `accessionNo:...` query) to drill into this filing's position rows.
- `filings[].period_of_report` (string): ISO `YYYY-MM-DD` reporting period end (always a calendar quarter end). Together with `cik` forms the natural key for QoQ comparisons.
- `filings[].filed_date` (string): ISO `YYYY-MM-DD` filing acceptance date (typically 30-45 days after `period_of_report`, bumping up against the 45-day SEC deadline). Use for filing-cadence analysis (which managers file early vs late).
- `filings[].filer_name` (string): Registrant name AS FILED on the cover page (typically all-caps in EDGAR convention). Casing preserved verbatim. NOT alias-normalized — for the user-friendly alias use the `filer_aliases` admin table.
- `filings[].address` (string (nullable)): Filer business address as filed on the cover page (street + city + state + ZIP, single string, comma-delimited). Null for pre-2018 filings (pre-XBRL cover-page parsing) and amendments that omit the address. Useful for compliance / KYC / geographic-concentration audits.
- `filings[].signing_officer` (string (nullable)): Name of the officer who signed the 13F cover page. Null for some amendment filings. Useful for tracking 'who manages this fund' — signing officer changes are a leading indicator of management transitions.
- `filings[].total_value_usd` (number (nullable)): Total reported portfolio value across all positions in the filing, in USD. Post-Plan 51 holdings-quality correction (handles the thousands-vs-actual-dollars reporting issue). Null for filings whose holdings have not yet been re-aggregated by the `sec_13f_summary` matview (~6h refresh cadence post-filing).
- `filings[].holdings_count` (integer (nullable)): Number of position rows in the filing's information table. Null for 13F-NT filings (notice-of-no-information-table — these always have 0 holdings and are skipped by our parser). Berkshire-shaped books: ~50; mid-tier hedge funds: 50-500; index-fund books (Vanguard, BlackRock): 3000-9000+.

**Since:** v1.0.0

**Utility:** Lightweight filing-history listing — returns just the cover-page metadata for 13F filings (manager name + address, signature info, amendment status, total filing value, holdings count). NO holdings JOIN, so this is 10-50× faster than `/holdings` when you only need 'show me which quarters this fund has filed'. The right endpoint for: fund-detail-page filing-history tabs, amendment-vs-original sleuthing, regulatory due-diligence on signing officers, and bulk-list workflows where you'd otherwise drown in holdings rows. After you've identified the right `(cik, period)` from this endpoint, drill into `POST /api/v1/form-13f/holdings` for the position-level detail.

**Use case:** List all filings for a fund, check which quarters are available, identify amendments vs originals, and access filing manager address and signature data.

**Parameters:**
- `query` (body, required): Lucene-like query. Same field-scoped syntax as `/holdings` but WITHOUT the holdings-row filters (`holdings.ticker`, `holdings.cusip` not supported here — use `/holdings` for those). Common: `cik:1067983` (single fund), `formType:"13F-HR/A"` (amendments only), `filedAt:[2025-01-01 TO 2025-12-31]` (year range), `accessionNo:0001067983-24-000123` (one specific filing). Combine with `AND`/`OR`/`NOT`.
- `from` (body, optional, default: 0): Zero-based pagination offset (NUMBER of filings to skip). Increment by `size` to walk pages. Capped at 10000 server-side.
- `size` (body, optional, default: 50): Number of filings to return per page, capped at 50 server-side. Each row is small (cover-page metadata only) so payload size stays bounded — listing 50 filings here is ~10KB; the same 50 in `/holdings` could be 5-50MB.
- `sort` (body, optional): Sort specification array (sec-api.io shape). Each element is `{ <field>: { order: 'asc' | 'desc' } }`. Common: `[{"filedAt": {"order": "desc"}}]` (most recent first; default), `[{"periodOfReport": {"order": "asc"}}]` (chronological for filing-history tabs).

**Query filters:**
- `cik:1067983` — Fund CIK (exact match)
- `periodOfReport:2024-09-30` — Exact quarter end date
- `periodOfReport:[2024-01-01 TO 2024-12-31]` — Period date range
- `filedAt:[2024-01-01 TO 2024-12-31]` — Filing date range
- `formType:"13F-HR"` — Form type filter
- `accessionNo:0001067983-24-000123` — Specific filing accession number

**Sample response:**
```json
{
  "filings": [
    {
      "cik": "0001067983",
      "accession_number": "0000950123-26-001234",
      "period_of_report": "2025-12-31",
      "filed_date": "2026-02-14",
      "filer_name": "BERKSHIRE HATHAWAY INC",
      "address": "3555 FARNAM STREET, OMAHA, NE 68131",
      "signing_officer": "WARREN E BUFFETT",
      "total_value_usd": 308000000000,
      "holdings_count": 47
    }
  ]
}
```

---

## Filing Progress Tracking

Track 13F filing completeness by quarter. Returns filer coverage as a percentage of expected recurring filers, deadline countdown, AUM, and quarter metadata. Useful for understanding whether a quarter's institutional data is still accumulating or fully reported.

### GET /api/v1/form-13f/filing-progress

Returns the current quarter's 13F filing completeness as a percentage of expected recurring filers, plus deadline information and timeline metadata. The recurring-filer baseline uses double-quarter CIK intersection: filers present in BOTH the previous AND two-quarters-ago periods.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `quarter` (string): Quarter label in `YYYY-Q[1-4]` format (e.g. `2025-Q4`). Use for chart headers and dashboard titles.
- `period_end` (string): ISO `YYYY-MM-DD` quarter-end date (always 03-31 / 06-30 / 09-30 / 12-31). Echoed back from the request when `quarter` parameter was passed; otherwise reflects the auto-resolved most-relevant quarter.
- `filing_deadline` (string): ISO `YYYY-MM-DD` SEC filing deadline — always exactly 45 days after `period_end`. Late-filers face SEC enforcement risk; recurring-filer baseline uses the last completed quarter's deadline behavior to weight late filings.
- `days_until_deadline` (integer): Whole days remaining until `filing_deadline`. Positive during active filing season; zero on deadline day; negative for past deadlines (the quarter is structurally complete then). Use to drive countdown UIs.
- `expected_count` (integer): Recurring-filer baseline — count of CIKs that filed in BOTH of the last two completed quarters. The denominator for `completion_pct`. Typical values: 4000-4500 funds (the recurring-filer universe). Smaller than the full 9,600+ 13F filer universe because not every fund files every quarter.
- `filed_count` (integer): Distinct CIK count of recurring-filer baseline funds that have filed for THIS quarter so far. Always ≤ `expected_count`. Increments throughout the 45-day filing window as more funds file.
- `completion_pct` (number): Completion percentage `(filed_count / expected_count) × 100`, rounded to 1 decimal place (range 0.0-100.0). At end of filing window typically reaches 95-99% (a few baseline funds skip filing each quarter — mostly funds that fell below the $100M AUM threshold). Use as the canonical 'is this quarter complete?' signal.
- `aum_observed_usd` (number): Aggregate reported AUM across filings ingested so far for this quarter, in USD (post-thousands-correction via the holdings-quality layer). Useful for filing-season AUM tracking — for the most-recent active quarter, this number grows day-by-day as more funds file.
- `as_of` (string): ISO-8601 UTC timestamp the progress snapshot was generated. Computed live (no cache) — always reflects the latest filings ingested. Use to detect data freshness; values older than ~5 minutes during active filing season suggest stale-cache contention.

**Since:** v1.9.0

**Utility:** Quarter-completeness tracker for 13F filings — answers 'is the current quarter complete?' without hard-coding the SEC's 45-day deadline. Computes the recurring-filer baseline as the CIK intersection of the LAST TWO COMPLETED quarters (filers who filed in both Q-1 AND Q-2), then reports `filed_count / expected_count / completion_pct` against this baseline. Includes deadline countdown, late-notice (13F-NT) tracking, and aggregate AUM observed so far. The right endpoint for filing-season dashboards: render `completion_pct` as a progress bar, surface `days_until_deadline` for the timeline UI, and combine with the QoQ-completeness signals from `/aggregation/by-ticker` to gate downstream analytics until the quarter has matured. EXEMPT (`cost: 0`) — operational metadata, polling-friendly. Lightweight `quarter_metadata` block is also injected into 5 other endpoints (`/market/summary`, `/by-sector`, `/fund-performance`, `/market-rotation`, `/cross-filing-signals`) so consumers don't need a separate round-trip for completeness state.

**Use case:** Building a filing season tracker dashboard: 'Q4 2025 filing season: 85% of expected filers have reported, 22 days until deadline'. Display pct_reported as a progress bar. Use deadline_status to show 'Filing season active' vs 'Quarter complete'. Combine with /filing-stats for backward-compatible metrics.

**Parameters:**
- `quarter` (query, optional): Quarter-end date as ISO `YYYY-MM-DD` (must be a calendar-quarter end: 03-31, 06-30, 09-30, 12-31). Defaults to the most relevant quarter based on current date: the active filing period during filing season (within 45 days post-quarter-end), or the last completed quarter otherwise. Returns 400 for non-quarter-end dates and dates outside FinRadar's 13F coverage.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "period": "2025-12-31",
    "filers": 3542,
    "pct_reported": 85.3,
    "baseline_filers": 4152,
    "baseline_period": "2025-09-30",
    "total_filings": 3890,
    "total_aum": 42150000000,
    "late_notice_filers": 18,
    "deadline": "2026-02-17",
    "deadline_status": "before",
    "is_complete": false,
    "days_until_deadline": 22,
    "previous_deadline": "2025-11-14",
    "next_deadline": "2026-05-15",
    "days_until_next_deadline": 109,
    "next_reporting_period_start": "2026-04-01",
    "quarter_metadata": {
      "quarter": "2025-12-31",
      "filing_deadline": "2026-02-17",
      "is_complete": false,
      "days_until_deadline": 22
    }
  }
}
```

---

## Billing & Subscription

Manage subscriptions, view plans, purchase API quota, and upgrade plans via Stripe.

### GET /api/v1/billing/subscription

Get the authenticated user's subscription info and request-based API usage. EXEMPT (`cost: 0`). Returns plan name, request-based usage vs limit, subscription status, renewal date.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
- `request_id` (string (nullable)): Per-request correlation ID.
- `timestamp` (string): ISO-8601 UTC timestamp.
- `data` (object): Subscription state payload.
- `data.reach_limit_api` (integer): Number of REQUESTS (NOT tokens) consumed by the user this billing cycle. Increments by 1 on every billed call regardless of cost tier — distinct from the token ledger which weights by cost tier (1/5/10/25). On accounts with no `user_plan` row (legacy), defaults to 0.
- `data.total_limit_api` (integer): Total REQUESTS allowed this billing cycle (e.g. 100 for free, higher for paid plans). Increased by [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota) when the user buys additional quota with their USD `credit_balance` wallet at 100 requests per $1. NOT in tokens — this is the legacy per-request meter.
- `data.plan_name` (string): Plan tier — `free` (default for new signups), `weekly`, `monthly`, `pro`, `yearly`. Drives UI tier badges. Set on Stripe `checkout.session.completed` via `_handle_checkout_completed` after a successful upgrade.
- `data.status` (string): Stripe subscription status — `active` (paying), `past_due` (failed payment, in 7-day grace), `canceled`, `trialing`, `unpaid`. For free-tier accounts always `active`. Use to dispatch UI banners ('Update payment method' on `past_due`).
- `data.current_period_end` (string (nullable)): ISO-8601 UTC timestamp the current billing period ends (= next renewal). Null for free-tier accounts (no renewal cycle). For paid accounts coincides with the Stripe subscription's `current_period_end`.

**Since:** v1.0.0

**Utility:** Authenticated subscription-state probe. EXEMPT (`cost: 0`). Returns the legacy request-based quota model (`reach_limit_api` / `total_limit_api`, in REQUESTS not tokens) plus plan name and Stripe subscription status. NOTE the unit distinction: this is the LEGACY per-request quota model used pre-Phase-56; the canonical token-based model is at [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) (in TOKENS, with cost-tier weighting). Both meters run side-by-side: a billed call decrements both `reach_limit_api` (+1 request) and the token ledger (-N tokens depending on cost tier). For plan upgrades use [POST /api/v1/payment/create-checkout-session](/docs/account/billing-and-subscription/post-payment-create-checkout-session); to buy additional request quota with the USD wallet use [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota).

**Use case:** Dashboard 'Subscription' card: render plan name + a request-quota progress bar (`reach_limit_api / total_limit_api`) + renewal-date chip. For the token-quota progress bar (the canonical Phase 56+ surface), use /api/v1/account/balance instead.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ3",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": {
    "reach_limit_api": 12,
    "total_limit_api": 100,
    "plan_name": "free",
    "status": "active",
    "current_period_end": null
  }
}
```

### GET /api/v1/plans/

List all active subscription plans with pricing, features, and Stripe price IDs. PUBLIC — NO authentication required. EXEMPT (`cost: 0`).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200.
- `request_id` (string (nullable)): Per-request correlation ID.
- `timestamp` (string): ISO-8601 UTC timestamp.
- `data` (array): Array of active plans, sorted by `price ASC` (cheapest first). Empty array only if all plans are inactive (operational issue — plans are seeded at deployment).
- `data[].id` (integer): Plan database ID. Pass to [POST /api/v1/payment/create-checkout-session](/docs/account/billing-and-subscription/post-payment-create-checkout-session) via `?plan_id=N` to initiate the Stripe-hosted upgrade flow.
- `data[].name` (string): Plan display name (e.g. `Free`, `Paid`, `Pro`). Casing follows brand guidelines — use verbatim in pricing-card UIs rather than lowercasing client-side.
- `data[].stripe_price_id` (string (nullable)): Stripe Price object ID in `price_XXXXX` format. Null for the Free plan (no Stripe price — checkout for Free is rejected at create-checkout-session). Used server-side to construct the Stripe Checkout `line_items[].price`.
- `data[].price` (integer): Plan price in CENTS (integer). E.g. `2900` = $29.00/month. 0 for the Free plan. Divide by 100 for USD display: `(price / 100).toFixed(2)`.
- `data[].currency` (string): ISO-4217 currency code. Defaults to `USD` server-side. Use to render currency symbol ($ / € / £).
- `data[].interval` (string): Billing interval — `month` (default), `week`, `year`. Drives '/month' vs '/year' suffix on pricing cards.
- `data[].features` (array): JSON array of feature-bullet strings for the pricing-card UI (`features: ["2,000 tokens/month", "Community support", ...]`). Empty array on plans that haven't been content-populated yet (operational gap).
- `data[].is_active` (boolean): Always true in the response (the query filter is `is_active=True`). Inactive plans are hidden from the public catalog by default. Inactive plans still service existing subscribers — they're just not offered to new signups.

**Since:** v1.0.0

**Utility:** Public catalogue of active subscription plans — drives the marketing pricing page and the in-app upgrade modal. PUBLIC (no auth required) and EXEMPT (`cost: 0`). Filters to `is_active=true` and orders by `price ASC`. Each row carries `stripe_price_id` (the Stripe Price object ID) which the frontend passes to [POST /api/v1/payment/create-checkout-session](/docs/account/billing-and-subscription/post-payment-create-checkout-session) via `?plan_id=N` to initiate a Stripe-hosted upgrade flow. Prices are in CENTS (integer) — divide by 100 for USD display. Currency defaults to `USD`. The `features` JSON column is plan-specific (e.g. an array of feature bullets for the pricing card UI).

**Use case:** Marketing pricing page renders this once on page load → maps each row to a pricing card → 'Upgrade' button on each card POSTs to /api/v1/payment/create-checkout-session with the plan's `id`.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ4",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": [
    {
      "id": 1,
      "name": "Free",
      "stripe_price_id": null,
      "price": 0,
      "currency": "USD",
      "interval": "month",
      "features": [
        "2,000 tokens / month",
        "Community support",
        "Basic API access"
      ],
      "is_active": true
    },
    {
      "id": 2,
      "name": "Paid",
      "stripe_price_id": "price_1QPzWaKG43KrBnru0AbCdEfG",
      "price": 2900,
      "currency": "USD",
      "interval": "month",
      "features": [
        "200,000 tokens / month",
        "Priority email support",
        "Full API access",
        "Sniper alerts",
        "Webhooks"
      ],
      "is_active": true
    }
  ]
}
```

### POST /api/v1/billing/quota

Purchase additional REQUEST quota by debiting the USD `credit_balance` wallet at 100 requests per $1. EXEMPT (`cost: 0`). Logs a SPEND `Transaction`. Returns 400 with `INSUFFICIENT_BALANCE` when the wallet does not cover the requested amount.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
- `request_id` (string (nullable)): Per-request correlation ID.
- `timestamp` (string): ISO-8601 UTC timestamp.
- `data` (object): Post-purchase result payload.
- `data.message` (string): Human-readable confirmation (e.g. `Successfully purchased 1000 additional API requests.`). Use for the UI success toast.
- `data.new_total_limit` (integer): Post-purchase value of `user_plans.total_limit_api` (in REQUESTS, not tokens). Mirrors the legacy per-request quota; the new bonus quota is added on top of the plan's base allocation. Use to update the 'Total requests' progress-bar denominator client-side without a separate /api/v1/billing/subscription call.
- `data.new_balance` (number): Post-purchase USD wallet balance (`users.credit_balance`). NOT in cents — server returns `float(credit_balance)`. Use to update the 'Wallet balance' chip client-side.

**Since:** v1.0.0

**Utility:** Customer-initiated request-quota top-up — debits the USD `credit_balance` wallet (in DOLLARS), adds REQUESTS (NOT tokens) to `user_plans.total_limit_api` at the fixed exchange rate of 100 requests per $1. EXEMPT (`cost: 0`). Atomic single-transaction: balance debit + quota credit + SPEND `Transaction` row are committed together. Returns 400 with `INSUFFICIENT_BALANCE` if `credit_balance < amount_dollars`. NB: this affects the LEGACY per-request meter (see [GET /api/v1/billing/subscription](/docs/account/billing-and-subscription/get-billing-subscription)) — NOT the canonical Phase 56 token meter (which has its own monthly-cycle refill and does NOT support manual top-up). To top up the USD wallet first, use [POST /api/v1/payments/create-intent](/docs/account/payments-module/post-payments-create-intent).

**Use case:** Dashboard 'Buy more requests' modal: user enters $10 → POST here with `amount_dollars: 10` → backend debits wallet by $10, adds 1,000 requests to `total_limit_api`, returns success → UI updates the request-quota progress bar.

**Parameters:**
- `amount_dollars` (body, required): USD amount to spend (NOT cents). Positive number; integer or float (e.g. 10, 20, 12.50). Validated server-side: rejected with 400 `BAD_REQUEST` on missing/non-numeric/zero/negative; rejected with 400 `INSUFFICIENT_BALANCE` if `users.credit_balance < amount_dollars`. Each $1 buys 100 REQUESTS.

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ5",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": {
    "message": "Successfully purchased 1000 additional API requests.",
    "new_total_limit": 1100,
    "new_balance": 2.5
  }
}
```

### POST /api/v1/payment/create-checkout-session

Create a Stripe-hosted Checkout session for a subscription upgrade. EXEMPT (`cost: 0`). Returns the Stripe URL — frontend MUST redirect via `window.location.href`.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
- `request_id` (string (nullable)): Per-request correlation ID.
- `timestamp` (string): ISO-8601 UTC timestamp.
- `data` (object): Checkout-session payload.
- `data.url` (string): Stripe Checkout-hosted page URL in `https://checkout.stripe.com/c/pay/cs_XXXXXXX#YYYYY` format. REDIRECT the browser via `window.location.href = response.data.url` — do NOT iframe-embed (Stripe blocks framing of checkout pages). On success, Stripe redirects back to `${FRONTEND_URL}/account/subscription?session_id={CHECKOUT_SESSION_ID}`; on cancel, to `${FRONTEND_URL}/account/subscription?cancelled=true`. The Checkout session embeds metadata (`user_uuid`, `plan_id`, `plan_name`) so the `checkout.session.completed` webhook handler can activate the right subscription on the right user.

**Since:** v1.0.0

**Utility:** Server-side wrapper for `stripe.checkout.Session.create` (mode=subscription) — returns a Stripe-hosted checkout URL where the user enters card details and confirms the upgrade. EXEMPT (`cost: 0`). The frontend MUST redirect (not iframe-embed). On successful payment, Stripe webhooks `checkout.session.completed` → `_handle_checkout_completed` activates the subscription on `user_plans` (sets `plan`, `stripe_subscription_id`, `current_period_end`). On cancellation / failure the user is redirected back to `/account/subscription?cancelled=true`. Free plan (no `stripe_price_id`) cannot be checked out — returns 400 `BAD_REQUEST` if `plan.stripe_price_id` is null.

**Use case:** Pricing-page 'Upgrade to Paid' button: get plan id from /api/v1/plans/ → POST here with `?plan_id=2` → redirect browser to the returned URL → Stripe-hosted checkout → on success Stripe redirects back to `/account/subscription?session_id=...` → SPA polls /api/v1/billing/subscription for the activated state.

**Parameters:**
- `plan_id` (query, required): Plan database ID (NOT name) — the integer `id` from [GET /api/v1/plans/](/docs/account/billing-and-subscription/get-plans). Returns 400 `BAD_REQUEST` if missing or non-numeric, 404 `NOT_FOUND` if the plan does not exist or is inactive, 400 `BAD_REQUEST` if the plan has no `stripe_price_id` (Free plan).

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ6",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": {
    "url": "https://checkout.stripe.com/c/pay/cs_test_b1Yq8nL7aP2kT6sB1mDfHj9vC3xRtKzE5wQ8jN4uM2pX7yI6oA9hT0gU1vF#fidkdWxOYHwnPyd1blpxYHZxWjA0SF9MUFc2dVZxYG1QSXNqcGhJQDR9aGhNNXxPSk09Q1xLTHN1MnxwfFBIYDU8YzVtXX1HSUtAaD1KaHM3RkB"
  }
}
```

### GET /api/v1/billing/history

Get billing transaction history for the authenticated user.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `transactions` (array): Array of wallet transaction rows, sorted by `created_at DESC` (most recent first). Empty array on accounts with no billing history (free tier accounts that have never upgraded). Includes both Stripe-tied charges and admin-grant credits.
- `transactions[].id` (string): Internal wallet-transaction ID in `wtx_XXXXXX` format (e.g. `wtx_abc123`). Stable across re-runs. Use as deduplication key when caching transaction history client-side.
- `transactions[].created_at` (string): ISO-8601 UTC timestamp the transaction was recorded. For Stripe-tied transactions this is the Stripe webhook arrival time (typically within seconds of the actual charge). Use for chronological display.
- `transactions[].type` (string): Transaction type — one of `subscription_refill` (monthly Stripe charge → 200K-token grant), `one_time_grant` (free-tier signup grant or promotional credit), `manual_adjustment` (admin-applied credit/debit), `refund` (Stripe refund). Use to dispatch UI badges and reconciliation logic.
- `transactions[].amount_usd` (number (nullable)): USD amount charged or refunded via Stripe (positive for charges, negative for refunds). Null for non-Stripe events like `one_time_grant` and `manual_adjustment` (these are tokens-only, no money movement).
- `transactions[].tokens_credited` (integer (nullable)): Tokens added to (or subtracted from) the balance as a result of this transaction. Null when the transaction was admin-recorded but did not move tokens (rare). For paid-plan refills typically 200000; for free-plan signup grants 2000.
- `transactions[].stripe_invoice_id` (string (nullable)): Linked Stripe invoice ID in `in_XXXXX` format. Present for `subscription_refill` and `refund` transactions; null for `one_time_grant` and `manual_adjustment`. Pass to Stripe Customer Portal for receipt download.
- `transactions[].description` (string): Human-readable description for UI display (e.g. `"Monthly paid plan refill"`, `"Free-tier signup grant"`, `"Admin credit — support ticket #4521"`). Casing follows brand guidelines.

**Since:** v1.2.1

**Utility:** Wallet transaction history for the authenticated user — every credit (subscription refill, one-time grant, manual adjustment, refund) related to billing events, ordered by `created_at DESC` (most recent first). NOT to be confused with the per-call token-debit ledger (that's `/api/v1/account/transactions`); this endpoint is specifically for billing-related credit events. Returns Stripe-shaped records (`amount_usd`, `stripe_invoice_id`) when the transaction was tied to a charge. The right endpoint for the customer-dashboard 'Billing History' table and for support workflows ('was the customer's $29 charge applied?'). EXEMPT (`cost: 0`) — account self-serve.

**Use case:** Displaying a transaction history table in the user's wallet page.

**Parameters:**
- `limit` (query, optional, default: 20): Maximum transactions to return per page (capped at 100 server-side). Most callers want 20-50 for typical 'last N transactions' display; for full-history exports use cursor pagination via `offset`.
- `offset` (query, optional, default: 0): Zero-based pagination offset (NUMBER of transactions to skip from the top). Increment by `limit` to walk pages: `offset=0` page 1, `offset=20` page 2 (when `limit=20`).

**Sample response:**
```json
{
  "transactions": [
    {
      "id": "wtx_abc123",
      "created_at": "2026-04-26T08:39:00.000Z",
      "type": "subscription_refill",
      "amount_usd": 29,
      "tokens_credited": 200000,
      "stripe_invoice_id": "in_1Pz...",
      "description": "Monthly paid plan refill"
    }
  ]
}
```

### GET /api/v1/billing/invoices

Fetch Stripe invoices for the authenticated user (PDF download links + amounts + status). EXEMPT (`cost: 0`). Returns an empty array for users without a `stripe_customer_id` (free-tier users who never upgraded).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `status` (string): ApiResponse envelope status — `success` on 200.
- `request_id` (string (nullable)): Per-request correlation ID.
- `timestamp` (string): ISO-8601 UTC timestamp.
- `data` (array): Array of Stripe invoice rows, sorted by Stripe (newest first by default). Empty array on free-tier users without `stripe_customer_id` AND on Stripe API errors (server logs the error and returns empty rather than 5xx — graceful degradation). Cap at the requested `limit` (default 10, max 100 enforced by Stripe).
- `data[].id` (string): Stripe invoice ID in `in_XXXXXX` format. Stable for the lifetime of the invoice. Use as deduplication key when caching client-side.
- `data[].amount_due` (integer): Amount still owed on the invoice in CENTS (Stripe-native unit). 0 for paid invoices; positive for `open` / `past_due` invoices. Divide by 100 for USD display.
- `data[].amount_paid` (integer): Amount already paid on the invoice in CENTS. For monthly subscriptions on the Paid plan: 2900 (= $29.00). Sum across all paid invoices = lifetime customer revenue.
- `data[].status` (string): Stripe invoice status — `paid` (most common), `open` (awaiting payment), `void` (admin-cancelled), `uncollectible` (Stripe gave up after retries), `draft` (rare, mostly admin-created). Drives UI badges.
- `data[].invoice_pdf` (string (nullable)): Short-lived Stripe-hosted PDF URL for the invoice receipt. Passes through Stripe's auth — no server-side auth needed; just `<a href={invoice_pdf} target="_blank">Download</a>`. Null for invoices in `draft` or `void` status.
- `data[].created` (integer): Unix epoch timestamp (seconds) the invoice was created in Stripe. Multiply by 1000 for JS Date constructor: `new Date(invoice.created * 1000)`. Use for chronological display.
- `data[].currency` (string): ISO-4217 currency code (lowercase per Stripe convention — e.g. `usd`, `eur`). Use to render currency symbol.

**Since:** v1.0.0

**Utility:** Live Stripe invoice list for the authenticated user — calls `stripe.Invoice.list(customer=...)` server-side and returns the relevant fields. EXEMPT (`cost: 0`). Returns empty array (NOT 400) for users without `stripe_customer_id` so the dashboard 'Invoices' table can render the empty state without special-casing free-tier users. Amounts are in CENTS (Stripe's native unit) — divide by 100 for USD display. The `invoice_pdf` URL is a short-lived Stripe-hosted PDF download — passes through Stripe's auth on click, no need to authenticate the request server-side.

**Use case:** Dashboard 'Wallet → Invoices' table: GET this on page load → render rows of `created` (date) / `amount_paid` / `status` / 'Download PDF' link. For an inline transaction history (charges + grants + refunds) use [GET /api/v1/billing/history](/docs/account/billing-and-subscription/get-billing-history); for the Stripe Customer Portal where the user can download invoices and update billing info use [POST /api/v1/account/billing-portal](/docs/account/token-pricing/post-account-billing-portal).

**Parameters:**
- `limit` (query, optional, default: 10): Max invoices to return per page. Default 10. Stripe enforces an upper bound of 100 server-side — values above are silently truncated by Stripe. For a user's full invoice history, paginate via Stripe's `starting_after` cursor (NOT exposed by this endpoint — use POST /api/v1/account/billing-portal for full history).

**Sample response:**
```json
{
  "status": "success",
  "request_id": "req_3OqK2jK9L8pQ4xZ7",
  "timestamp": "2026-05-02T15:51:00.000Z",
  "data": [
    {
      "id": "in_1QPzWaKG43KrBnru0xYzAbCd",
      "amount_due": 0,
      "amount_paid": 2900,
      "status": "paid",
      "invoice_pdf": "https://pay.stripe.com/invoice/acct_1QPzWaKG43KrBnru/test_YWNjdF8xUVB6V2FLRzQzS3JCbnJ1LF9PcUsyaks5TDhwUTR4WjE/pdf?s=ap",
      "created": 1745625540,
      "currency": "usd"
    },
    {
      "id": "in_1QPzVXKG43KrBnruZyXwCdEf",
      "amount_due": 0,
      "amount_paid": 2900,
      "status": "paid",
      "invoice_pdf": "https://pay.stripe.com/invoice/acct_1QPzWaKG43KrBnru/test_YWNjdF8xUVB6V2FLRzQzS3JCbnJ1LF9PcUsyaks5TDhwUTR4WjI/pdf?s=ap",
      "created": 1742947140,
      "currency": "usd"
    }
  ]
}
```

---

## Market Status

Real-time NYSE market session state. Public endpoint -- no authentication required.

### GET /api/market/status

Get current NYSE market session state with countdown to next session change.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `is_open` (boolean): True ONLY during regular trading session (9:30 AM-4:00 PM ET on non-holiday weekdays). False during pre-market, after-hours, weekends, and holidays. Use as the canonical 'should I display real-time price ticks?' gate.
- `phase` (string): Current session phase — one of `pre_market` (4:00-9:30 AM ET), `regular` (9:30 AM-4:00 PM ET), `after_hours` (4:00-8:00 PM ET), `closed` (8:00 PM ET-4:00 AM ET on weekdays + all weekend), `holiday` (NYSE holiday — see `holiday_name`). Use for color-coded session badges (green=regular, amber=pre/post, grey=closed/holiday).
- `next_event` (string): Next phase transition label — `pre_market_open`, `regular_open`, `regular_close`, `after_hours_close`, or `next_trading_day_open`. Useful for countdown UIs ('Regular session in 1h 30m').
- `next_event_at` (string): ISO-8601 UTC timestamp of the next phase transition. Use to render absolute-time countdowns; pair with `seconds_until_next_event` for relative displays. Holiday-aware — skips weekends and NYSE holidays in the next-event computation.
- `seconds_until_next_event` (integer): Countdown in whole seconds until `next_event_at`. Always positive. Use for client-side countdown timers ('Market opens in 5,400 seconds = 1h 30m').
- `is_holiday` (boolean): True when today is a NYSE-observed holiday (federal holidays + Good Friday — NYSE-specific). Holiday rules: Saturday holidays observed on prior Friday; Sunday holidays observed on following Monday. False on regular weekdays AND on weekends-without-observed-holiday.
- `holiday_name` (string (nullable)): Holiday name when `is_holiday=true` (e.g. `Memorial Day`, `Independence Day`, `Thanksgiving`, `Christmas Day`, `Good Friday`). Null on non-holiday days. Use for tooltip display ('Market closed — Memorial Day').
- `as_of` (string): ISO-8601 UTC timestamp the snapshot was generated server-side. NOT cached — always reflects request time, since stale market-status display would be confusing during active trading.

**Since:** v1.3.0

**Utility:** Real-time NYSE market session probe — returns whether the market is currently in pre-market (4:00-9:30 AM ET), regular session (9:30 AM-4:00 PM ET), after-hours (4:00-8:00 PM ET), or closed. Includes countdown to next session transition and full holiday awareness (MLK, Presidents', Memorial, Good Friday, Juneteenth, Independence Day, Labor Day, Thanksgiving, Christmas) with the canonical Saturday→Friday / Sunday→Monday observed-on-weekday rules. Public endpoint — no authentication required and free (`cost: 0`) so dashboards can poll aggressively without quota concerns. The right endpoint for market-hours-gated UIs (price-action displays, real-time order entry), session-aware notification systems, and rate-aware polling clients that want to back off during closed sessions.

**Use case:** Displaying a market status indicator on a dashboard. Color-code UI elements by session state (green=open, amber=pre/post, grey=closed). Show countdown to next session transition.

**Sample response:**
```json
{
  "data": {
    "session": "open",
    "label": "Market Open",
    "current_time_et": "2:30 PM ET",
    "countdown": "1h 30m",
    "next_event": "After-Hours at 4:00 PM ET",
    "is_trading_day": true
  }
}
```

---

## Ticker Research

Per-ticker endpoints for company overview, institutional ownership, and historical fund trends.

### GET /api/v1/tickers/{ticker}/overview

Company overview and financial data for a ticker. Includes sector, industry, market cap, income statement (TTM), balance sheet, cash flow, margins, and per-share data. Data sourced from Yahoo Finance via yahooquery and cached 24h.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Issuer ticker (canonical hyphen form, echoed back).
- `data.name` (string): Company name from Yahoo Finance (typically Title Case — `Apple Inc.`).
- `data.sector` (string (nullable)): Yahoo Finance sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null for unmapped tickers (recent IPOs, foreign issuers).
- `data.industry` (string (nullable)): Yahoo Finance industry classification (more specific than sector). Null for unmapped tickers.
- `data.market_cap` (number (nullable)): Market capitalization (USD). Computed as `last_close × shares_outstanding`. Use for size-based universe filters. Updates daily via Yahoo Finance refresh + 24h cache.
- `data.enterprise_value` (number (nullable)): Enterprise value (USD). `market_cap + total_debt - total_cash`. Combine with EBITDA from this surface for EV/EBITDA multiple.
- `data.float_shares` (number (nullable)): Public float (shares freely tradable). Useful for liquidity-aware position sizing — small-caps with float < 50M shares typically have wide bid-ask spreads.
- `data.shares_outstanding` (number (nullable)): Total shares outstanding (point-in-time). Differs from `/financials/metrics` weighted-average value when issuer is actively buying back / issuing.
- `data.first_trade_date` (string (nullable)): Human-readable first-trade date (e.g. `Dec 12, 1980`). Useful for filtering recent IPOs (within last 1 year). Null for very old tickers without recorded IPO date.
- `data.short_pct_float` (number (nullable)): Short interest as fraction of float (decimal — `0.0072` = 0.72%). Updated bi-monthly per NYSE/NASDAQ publication cadence; may lag 2-3 weeks. Above 0.20 flags potential-squeeze names.
- `data.short_ratio` (number (nullable)): Days-to-cover ratio: `short_interest / avg_daily_volume`. Above 5 days flags squeeze risk.
- `data.revenue` (number (nullable)): TTM revenue (USD). Sourced from Yahoo Finance — typically agrees with [/financials/metrics](/docs/company-data/company-financials-xbrl/get-financials-metrics) TTM revenue within ±2% (Yahoo derives from same SEC XBRL filings + applies its own normalization). For audit-grade XBRL-direct numbers prefer `/financials/snapshot`.
- `data.gross_profit` (number (nullable)): TTM gross profit (USD). Null for non-COGS business models (banks, insurers — interpret as 'not applicable to issuer's structure').
- `data.operating_income` (number (nullable)): TTM operating income / EBIT (USD). Negative for operating-loss companies.
- `data.net_income` (number (nullable)): TTM net income attributable to common stockholders (USD). Negative for loss-makers.
- `data.total_cash` (number (nullable)): Cash and short-term investments (USD). Point-in-time at most-recent fiscal-period end.
- `data.total_debt` (number (nullable)): Total debt (short + long term) (USD). Combine with `total_cash` for net-debt computation.
- `data.profit_margin` (number (nullable)): TTM net margin (decimal — `0.270` = 27.0%). `net_income / revenue`. Negative for loss-makers.
- `data.gross_margin` (number (nullable)): TTM gross margin (decimal). `gross_profit / revenue`.
- `data.operating_margin` (number (nullable)): TTM operating margin (decimal). `operating_income / revenue`.
- `data.ebitda_margin` (number (nullable)): TTM EBITDA margin (decimal). `ebitda / revenue`. Useful for capital-intensity / scale-quality screens.
- `data.eps_diluted_ttm` (number (nullable)): TTM diluted EPS (USD per share). NOT split-adjusted server-side — reflects as-filed EPS for the trailing 4 quarters; for split-adjusted historical view use external market-data sources.
- `data.book_value_per_share` (number (nullable)): Book value per share (USD). `total_equity / shares_outstanding`. Negative for issuers with negative book equity (MMM, MCD, SBUX, etc. with aggressive buybacks).
- `data.free_cash_flow_per_share` (number (nullable)): TTM Free Cash Flow per share (USD). `(operating_cash_flow + capex) / shares_outstanding`. Negative for FCF-burning companies.
- `data.dividend_yield` (number (nullable)): Forward dividend yield (decimal — `0.0038` = 0.38%). Computed as `last_4q_dividends_per_share / last_close`. Null for non-dividend-paying issuers (most growth tech, biotech, recent IPOs).

**Since:** v1.0.0

**Parameters:**
- `ticker` (path, required): Ticker symbol (canonical hyphen form). Server normalizes `BRK.A`/`BRK/A`/`BRKA` → `BRK-A`. Multi-class issuers (GOOGL vs GOOG) preserve the requested class. Returns 404 on tickers with no Yahoo Finance coverage; cached 24h server-side.

**Sample response:**
```json
{
  "data": {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "market_cap": 3984500000000,
    "enterprise_value": 4058044000000,
    "float_shares": 14820000000,
    "shares_outstanding": 14840000000,
    "first_trade_date": "Dec 12, 1980",
    "short_pct_float": 0.0072,
    "short_ratio": 1.38,
    "revenue": 401450000000,
    "gross_profit": 189890000000,
    "operating_income": 128190000000,
    "net_income": 105320000000,
    "total_cash": 28160000000,
    "total_debt": 101700000000,
    "profit_margin": 0.27,
    "gross_margin": 0.473,
    "operating_margin": 0.319,
    "ebitda_margin": 0.345,
    "eps_diluted_ttm": 7.1,
    "book_value_per_share": 3.84,
    "free_cash_flow_per_share": 7.13,
    "dividend_yield": 0.0038
  }
}
```

### GET /api/v1/tickers/{ticker}/holders

Top institutional holders across ALL 9,600+ 13F filers with quarter-over-quarter change. Queries form_13f_holdings directly (not just tracked funds). CUSIP successor chain expansion and amendment deduplication included. Returns status (New/Increased/Decreased/Unchanged/Closed) and change % vs previous quarter.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Ticker echoed back in canonical hyphen form.
- `data.period` (string): ISO `YYYY-MM-DD` quarter-end date for the snapshot. Always 03-31 / 06-30 / 09-30 / 12-31. The 13F filing for this period was due 45 days later. Most-recent quarter may be partially populated during the 45-day filing window — see `/form-13f/filing-progress` for completeness gauge.
- `data.prev_period` (string (nullable)): ISO `YYYY-MM-DD` quarter-end of the prior quarter (used as the baseline for QoQ `chg_*` and `status` fields). Null when `period` is the earliest covered quarter.
- `data.holders[]` (array): Array of holder rows, sorted by `value DESC` (largest position first). Up to `limit` rows; total set has `total_count` rows. Empty array for tickers no fund has ever held (most pre-IPO and very-thinly-held names).
- `data.holders[].cik` (string): Filer CIK in 10-char zero-padded form (e.g. `0001067983` for Berkshire Hathaway, `0001364742` for BlackRock, `0000884144` for Vanguard, `0001037389` for Renaissance Technologies). Use as join key against `/api/v1/form-13f/fund/{cik}` for the per-fund detail view.
- `data.holders[].name` (string): Filer name as registered with SEC EDGAR (typically all-caps EDGAR convention). Use for human-readable holder labels.
- `data.holders[].shares` (number): Share count for the position as of `period`. NOT split-adjusted server-side (preserves the as-filed view) — for split-adjusted historical aggregations use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/company-data/ticker-research/get-tickers-ticker-fund-trends).
- `data.holders[].value` (number): Position value (USD) at the period-end mark-to-market price. Post-Plan-51 holdings-quality value normalization (handles the pre-Q3-2022 thousands-vs-actual-dollars SEC reporting issue) — for historical filings the parser auto-detected and corrected the unit on a per-filing basis. Always presented in actual USD here.
- `data.holders[].pct_of_portfolio` (number (nullable)): Position weight in the holder's total portfolio (decimal — `0.255` = 25.5%). Useful for ranking holders by conviction (a fund with 25% portfolio weight has higher relative conviction than one with 0.5%). Null for filers without a complete portfolio for the quarter (rare).
- `data.holders[].chg_shares` (number (nullable)): QoQ share-count change vs `prev_period` (signed integer). Positive = added; negative = trimmed. Null when prior-quarter baseline is missing (new positions show null, not zero — disambiguates 'new buy' from 'held flat at zero').
- `data.holders[].chg_pct` (number (nullable)): QoQ percent change in shares (decimal — `-0.250` = -25%). Null for new positions (no prior baseline to divide by). For mass-comparison use `status` instead — handles the null-case cleanly.
- `data.holders[].status` (string): QoQ status classification: `New` (no position in `prev_period`), `Increased` (added shares), `Decreased` (trimmed shares), `Unchanged` (held flat), `Closed` (had position in `prev_period`, zero in `period`). Use for status-filtered holder tables and smart-money-momentum dashboards.
- `data.holders[].accession_number` (string (nullable)): SEC accession number for the 13F filing this row was extracted from (18-char dashed format like `0000950123-25-009876`). Useful for audit-trail UIs and EDGAR-link generation. Null for amendment-superseded rows where only the amendment's accession is preserved.
- `data.holders[].filed_at` (string): ISO `YYYY-MM-DD` date the 13F was filed with SEC EDGAR. Always within 45 days of `period`.
- `data.total_shares` (number): Aggregate institutional share count across ALL holders (not just the paginated subset). NOT split-adjusted — for split-adjusted historical totals use `/tickers/{ticker}/fund-trends`.
- `data.total_value` (number): Aggregate institutional position USD value across all holders. Post-Plan-51 normalized.
- `data.total_holders` (integer): Distinct holder CIK count for the ticker in `period`. Mega-caps (AAPL, MSFT) typically 4000-5000; small-caps 50-300; micro-caps 1-30.
- `data.total_count` (integer): Total holder rows matching the `status` filter (= `total_holders` when `status=all`). Use for pagination math.
- `data.offset` (integer): Echoed-back pagination offset.
- `data.limit` (integer): Echoed-back page-size limit.

**Since:** v1.0.0

**Parameters:**
- `ticker` (path, required): Ticker symbol (canonical hyphen form). Server normalizes case + dot/slash variants. Multi-class issuers preserve the requested class. CUSIP successor chain is automatically expanded — for Alphabet (`GOOGL` / `GOOG`) returns positions across pre/post-2014-share-class-restructuring CUSIPs.
- `limit` (query, optional, default: 100): Max funds per page (default 100, max 500). For typical UI tables 20-50; for full-list export 500 + paginated walks.
- `offset` (query, optional, default: 0): Skip first N results for pagination (default 0). Use with `limit` to page through all holders. For tickers with 4000+ holders (mega-caps), 80+ paginated calls would be needed for full enumeration; use `POST /api/v1/form-13f/holdings` for bulk-export workflows.
- `status` (query, optional, default: all): Filter by QoQ status: `all` (default), `new` (just-opened positions), `increased` (added shares), `decreased` (trimmed shares), `unchanged` (held flat), `closed` (just-exited positions). For smart-money-momentum dashboards use `new` + `increased`; for distribution dashboards use `decreased` + `closed`.
- `period` (query, optional): Specific report period (ISO `YYYY-MM-DD` quarter-end format like `2025-09-30`). Defaults to latest available period (typically the quarter ending 45-90 days ago given the SEC 45-day filing deadline + ETL lag).
- `quarters` (query, optional, default: 1): Number of quarters to return (default 1, max 20). When `>1`, response includes a `quarters[]` array with per-quarter holders and QoQ changes — useful for trend charts. When `1`, response is the flat single-period view shown in the sample.

**Sample response:**
```json
{
  "data": {
    "ticker": "AAPL",
    "period": "2025-09-30",
    "prev_period": "2025-06-30",
    "holders": [
      {
        "cik": "0001067983",
        "name": "BERKSHIRE HATHAWAY INC",
        "shares": 300000000,
        "value": 78240000000,
        "pct_of_portfolio": 0.255,
        "chg_shares": -100000000,
        "chg_pct": -0.25,
        "status": "Decreased",
        "accession_number": "0000950123-25-009876",
        "filed_at": "2025-11-13"
      },
      {
        "cik": "0001364742",
        "name": "BLACKROCK INC",
        "shares": 1100000000,
        "value": 286900000000,
        "pct_of_portfolio": 0.061,
        "chg_shares": 12000000,
        "chg_pct": 0.011,
        "status": "Increased",
        "accession_number": "0001086364-25-014321",
        "filed_at": "2025-11-12"
      },
      {
        "cik": "0000884144",
        "name": "VANGUARD GROUP INC",
        "shares": 1380000000,
        "value": 359980000000,
        "pct_of_portfolio": 0.058,
        "chg_shares": 8500000,
        "chg_pct": 0.006,
        "status": "Increased",
        "accession_number": "0000884144-25-006543",
        "filed_at": "2025-11-14"
      }
    ],
    "total_shares": 8920000000,
    "total_value": 2326200000000,
    "total_holders": 4775,
    "total_count": 4775,
    "offset": 0,
    "limit": 100
  }
}
```

### GET /api/v1/tickers/{ticker}/fund-trends

Historical quarterly fund ownership trends aggregated from ALL 9,600+ 13F filers (form_13f_holdings). CUSIP successor chain expansion and amendment deduplication included. Split-adjusted share counts. Returns per-quarter totals for shares, value, fund count, and computed deltas (fund flow, share change %).

**Token cost:** 10 tokens per call

**Response fields:**
- `ticker` (string): Ticker echoed back in canonical hyphen form (e.g. `BRK-A`). Useful for asserting your client passed the ticker you intended after server-side normalization.
- `trends` (array): Array of quarterly aggregate rows, sorted by `period ASC` (oldest first — chart-friendly ordering). One row per quarter where ANY 13F filer held the ticker. Empty array for tickers no fund has ever held (most pre-IPO and very-thinly-held names).
- `trends[].period` (string): ISO `YYYY-MM-DD` quarter-end date (always 03-31 / 06-30 / 09-30 / 12-31). The 13F filing for this period was due 45 days later. Most-recent quarter may be partially populated during the 45-day filing window — see `/form-13f/filing-progress` for completeness gauge.
- `trends[].fund_count` (integer): Number of distinct 13F filers holding the ticker as of `period`. Counts unique CIKs (one per fund family) — Fidelity, Vanguard, BlackRock are 1 each despite running thousands of underlying funds. Mega-cap names typically have 3000-5000 filers; small-caps 50-300; micro-caps 1-30.
- `trends[].total_shares` (number): Aggregate share count across all funds holding the ticker, SPLIT-ADJUSTED to most recent split via Sharadar's split-adjustment factor. So a pre-2020 4-for-1 AAPL split is normalized to current-shares basis, making cross-quarter trends visually clean. For as-filed (un-adjusted) shares use `POST /api/v1/form-13f/holdings`.
- `trends[].total_value_usd` (number): Aggregate position USD value across all funds, post-Plan 51 holdings-quality correction (handles the thousands-vs-actual-dollars reporting issue). NOT mark-to-most-recent-price — uses the value as filed for that quarter (which is mark-to-quarter-end-price). For the price-adjusted view across quarters, multiply `total_shares` by your reference price.
- `trends[].fund_change_pct` (number (nullable)): Quarter-over-quarter percent change in `fund_count`, using FAIR-COMPARISON logic (post-v3.9.0 fix): `fund_count_prev` only counts funds that filed in BOTH quarters, so the metric correctly captures incremental adoption rather than being polluted by funds that simply skipped a quarterly filing. Null on the first row (no prior baseline).
- `trends[].shares_change_pct` (number (nullable)): Quarter-over-quarter percent change in `total_shares`, computed on split-adjusted shares so corporate actions don't manufacture artificial spikes. Positive = aggregate fund flow IN; negative = aggregate fund flow OUT. Null on the first row (no prior baseline).

**Since:** v1.3.3

**Utility:** Quarterly time-series of institutional fund ownership for a ticker — drives the 'Fund Ownership' chart on every company-overview page. Aggregates ALL 9,600+ 13F filers (post-v3.3.0 rewrite — the legacy implementation was limited to 668 tracked funds). Includes CUSIP successor-chain expansion so M&A continuity is preserved across corporate actions (e.g. PFE/Wyeth merger, T/Time Warner spinoff, GOOGL share-class restructuring). Split-adjusted share counts so cross-quarter trends remain visually clean across 2-for-1 / 4-for-1 splits. The canonical answer to 'are funds buying or selling this name?' — pair with `/tickers/{ticker}/holders` for the current-quarter holder list at the same completeness level. Post-v3.7.1 fix uses fair-comparison QoQ (`fund_count_prev` only counts funds that filed in BOTH quarters), so AAPL Q4 2025 fund_change_pct now shows +11% instead of the misleading -98% the old logic produced.

**Parameters:**
- `ticker` (path, required): Stock ticker (case-insensitive). Server normalizes to canonical hyphen form (`BRK.A`/`BRK/A`/`BRKA` → `BRK-A`). Multi-class issuers preserve the requested class — `GOOGL` and `GOOG` return distinct trends. Returns 404 if the ticker has been delisted with no successor in our chain table; for canonical resolution see `/api/v1/cusip-successors`.
- `limit` (query, optional, default: 20): Maximum quarters to return (oldest-first ordering; FinRadar coverage starts 2013-Q1). Defaults to 20 (~5 years of history). Capped at 40 (~10 years). For full history beyond 10 years use `POST /api/v1/form-13f/holdings` with date-range chunking.

**Sample response:**
```json
{
  "data": {
    "ticker": "AAPL",
    "security_name": "APPLE INC",
    "quarters": [
      {
        "date": "2024-09-30",
        "total_shares": 1150000000,
        "total_value": 220000000000,
        "fund_count": 4400,
        "share_change": -20000000,
        "share_change_pct": -1.7,
        "fund_flow": -5000000000,
        "fund_count_change": -15
      }
    ]
  }
}
```

### GET /api/v1/tickers/autocomplete

Full ticker list for client-side typeahead search. Returns all tickers with company names, ordered alphabetically. Designed for preloading into client-side autocomplete widgets.

**Token cost:** 1 token per call

**Response fields:**
- `tickers[]` (array): Array of matching ticker rows, sorted by `score DESC` (highest-conviction match first) when `q` is provided, alphabetically when `q` is empty. Empty array on no match.
- `tickers[].symbol` (string): Canonical ticker (hyphen form for multi-class — `BRK-A` not `BRK.A`/`BRK/A`/`BRKA`). Multi-class issuers preserve their share-class suffix. Foreign-listing variants carry exchange suffixes (`.MX`, `.TO`, `.L`, etc.).
- `tickers[].name` (string): Company name (Title Case). For multi-class issuers, parenthetical suffix disambiguates (`Berkshire Hathaway Inc. (Class A)` vs `Berkshire Hathaway Inc. (Class B)`). For foreign listings, the exchange is noted parenthetically.
- `tickers[].exchange` (string (nullable)): Primary listing exchange code: `NYSE`, `NASDAQ`, `AMEX`, `OTC`, `BMV` (Mexico), `TSX` (Toronto), `LSE` (London), etc. Null for issuers without a clean primary-exchange mapping (rare; mostly OTC pink-sheet names).
- `tickers[].score` (number): FinRadar ticker-scoring signal (range `[0, 100]`). Higher = more-prominent listing (high-volume primary, well-known issuer name, frequent news coverage). For multi-class issuers, the more-traded class scores higher (BRK-B > BRK-A on volume; AAPL primary > AAPL.MX foreign listing). Use for ranking ties in autocomplete dropdowns. Phase 47-era ticker_scoring service — re-computed nightly from volume + market_cap + cross-section signal density.
- `tickers[].rank` (integer): 1-indexed rank within the response set. `rank=1` is the top match. Useful for UI rendering (showing 'Top match' badge on rank=1).
- `meta.total` (integer): Total tickers returned in this response. May equal full-corpus match count if smaller than `limit`; otherwise capped at `limit`.
- `meta.query` (string (nullable)): Echoed-back `q` parameter (or null when empty).

**Since:** v1.0.0

**Utility:** Preload all tickers for instant client-side search.

**Use case:** Building a ticker search bar that provides instant autocomplete without server round-trips on each keystroke.

**Parameters:**
- `q` (query, optional): Optional query prefix for server-side filtering. When provided, returns up to 50 tickers ranked by FinRadar's ticker-scoring signal (Phase 47-related — high-volume primary listings rank ahead of low-volume secondary listings; multi-class issuers like BRK-A vs BRK-B disambiguated by liquidity score). When omitted, returns the full enumeration for client-side preload.
- `limit` (query, optional, default: 50): Max tickers returned when `q` is provided (capped at 50 server-side). Ignored when `q` is empty (full preload mode).

**Sample response:**
```json
{
  "tickers": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "exchange": "NASDAQ",
      "score": 100,
      "rank": 1
    },
    {
      "symbol": "AAPL.MX",
      "name": "Apple Inc. (Mexico Listing)",
      "exchange": "BMV",
      "score": 12,
      "rank": 2
    },
    {
      "symbol": "APLE",
      "name": "Apple Hospitality REIT, Inc.",
      "exchange": "NYSE",
      "score": 38,
      "rank": 3
    }
  ],
  "meta": {
    "total": 3,
    "query": "appl"
  }
}
```

### GET /api/v1/tickers/logos/domain/{symbol}

Get the website domain for a stock ticker. Returns a Google S2 favicon URL (128px) derived from the company website. Useful for displaying company logos without maintaining a logo database.

**Token cost:** 1 token per call

**Response fields:**
- `symbol` (string): Ticker echoed back in canonical hyphen form.
- `domain` (string (nullable)): Company website domain (e.g. `apple.com`, `microsoft.com`, `nvidia.com`). Sourced from FinRadar's curated ticker→domain mapping (~7,500 entries) — primary mapping is hand-curated for the top-3000 tickers; fallback uses Yahoo Finance company-website field. Null for issuers without a discoverable corporate website (rare; mostly small-cap shell companies or pre-IPO ADRs).
- `logo` (string (nullable)): Google S2 favicon URL at 128×128 resolution (`https://www.google.com/s2/favicons?domain={domain}&sz=128`). Free unauthenticated CDN; no rate limits for client-side `<img>` rendering. Null when `domain` is null. For higher-resolution / brand-asset logos use external services (Clearbit, etc.) — Google S2 caps at 128px.
- `cached` (boolean): Boolean: `true` when the response came from FinRadar's 24h server-side cache (most calls), `false` on the rare cache-miss path (refresh ~5-10ms slower).

**Since:** v1.0.0

**Utility:** Get company logo/favicon by ticker symbol.

**Use case:** Displaying company logos next to ticker symbols in a portfolio view or search results.

**Parameters:**
- `symbol` (path, required): Stock ticker (canonical hyphen form). Server normalizes case + dot/slash variants. Multi-class issuers preserve their share-class suffix (`BRK-A` and `BRK-B` both map to `berkshirehathaway.com`). Returns 404 for unknown symbols.

**Sample response:**
```json
{
  "symbol": "AAPL",
  "domain": "apple.com",
  "logo": "https://www.google.com/s2/favicons?domain=apple.com&sz=128",
  "cached": true
}
```

### GET /api/v1/tickers/logos/domains

Batch lookup of website domains and logo URLs for multiple tickers. Returns a map of symbol → {domain, logo} for all found tickers.

**Token cost:** 5 tokens per call

**Response fields:**
- `domains` (object): Map of `symbol` → `{ symbol, domain, logo }`. Empty object when no requested tickers are found. Order of keys matches the input `symbols` parameter (preserved server-side via ordered iteration). Missing tickers are NOT included in this map — see `meta.missing` for the explicit unfound list.
- `domains.{symbol}` (object): Per-ticker logo entry. Always 3 sub-fields: `symbol` (canonical hyphen form), `domain` (company website e.g. `apple.com`), `logo` (Google S2 favicon URL at 128×128). For multi-class issuers, both BRK-A and BRK-B map to the same `berkshirehathaway.com` domain.
- `domains.{symbol}.symbol` (string): Ticker in canonical hyphen form (echoed back per-row).
- `domains.{symbol}.domain` (string (nullable)): Company website domain. May be a sibling domain (`abc.xyz` for GOOGL/Alphabet) when the parent corporate site differs from the consumer-facing brand. Null only for issuers in the curated map without a discoverable domain (rare).
- `domains.{symbol}.logo` (string (nullable)): Google S2 favicon URL at 128×128 resolution. Null when `domain` is null.
- `meta` (object): Response metadata: `{ requested: integer, found: integer, missing: array<string> }`. Useful for batch-completeness gauges and client-side fallback rendering for unmapped tickers.
- `meta.requested` (integer): Count of tickers in the input `symbols` parameter (after server-side normalization + dedup).
- `meta.found` (integer): Count of tickers that returned a domain. `found ≤ requested`; the difference is in `missing[]`.
- `meta.missing` (array): Array of canonical-form tickers that had no domain mapping (unknown tickers OR known tickers without curated domain). Use for client-side fallback rendering (e.g. show generic placeholder icon).

**Since:** v1.0.0

**Utility:** Batch company logo lookup for portfolio or list views.

**Use case:** Loading logos for all tickers in a watchlist or portfolio table in a single request instead of N individual calls.

**Parameters:**
- `symbols` (query, required): Comma-separated ticker symbols (canonical hyphen form). Server normalizes each. Max 200 per call. For larger universes (full-watchlist >200) chunk client-side. Unknown tickers are silently dropped from the response (NOT 404'd) so a single bad ticker doesn't fail the batch.

**Sample response:**
```json
{
  "domains": {
    "AAPL": {
      "symbol": "AAPL",
      "domain": "apple.com",
      "logo": "https://www.google.com/s2/favicons?domain=apple.com&sz=128"
    },
    "MSFT": {
      "symbol": "MSFT",
      "domain": "microsoft.com",
      "logo": "https://www.google.com/s2/favicons?domain=microsoft.com&sz=128"
    },
    "NVDA": {
      "symbol": "NVDA",
      "domain": "nvidia.com",
      "logo": "https://www.google.com/s2/favicons?domain=nvidia.com&sz=128"
    },
    "GOOGL": {
      "symbol": "GOOGL",
      "domain": "abc.xyz",
      "logo": "https://www.google.com/s2/favicons?domain=abc.xyz&sz=128"
    }
  },
  "meta": {
    "requested": 4,
    "found": 4,
    "missing": []
  }
}
```

---

## System Status

Public service health and uptime monitoring. No authentication required.

### GET /api/v1/status

Current health status of all monitored services with 30-day and 90-day uptime percentages.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `overall` (string): Aggregate platform-wide status — `operational` (all services healthy), `degraded` (one or more services show elevated latency but functional), `partial_outage` (one or more services down but most operational), `major_outage` (multiple services down). Use as the canonical 'is FinRadar healthy?' single-field signal. Color-code dashboards accordingly (green/amber/orange/red).
- `services` (array): Array of per-service status entries. Covers ~10-15 monitored services: `main_api`, `insider_module`, `13f_worker`, `postgres_db`, `redis`, `sec_gateway`, `sec_watchdog`, etc. Each row carries response time, uptime stats, and last-check timestamp.
- `services[].name` (string): Canonical service identifier (e.g. `main_api`, `insider_module`, `13f_worker`, `postgres_db`, `redis`, `sec_gateway`). Stable across versions — safe for use as join key in monitoring integrations.
- `services[].status` (string): Per-service status — `operational` (healthy), `degraded` (elevated latency but functional, typically > p95 latency threshold), `down` (failing health check). Watchdog runs the check every 60 seconds; values reflect the most-recent successful check.
- `services[].uptime_30d_pct` (number): Rolling 30-day uptime percentage (0.0-100.0, computed as `healthy_checks / total_checks * 100`). Internal SLO target is 99.9% on customer-facing services. Values below 99.5% should trigger reliability investigation.
- `services[].last_check_at` (string): ISO-8601 UTC timestamp of the most recent watchdog health check. Should always be within the last 60 seconds — values older than 5 minutes indicate the watchdog itself is degraded (a meta-failure that bypasses normal alerting).
- `data_freshness` (object): Data-freshness metrics complementing service-uptime: `{ last_filing_at, queue_depth, last_13f_batch_at, last_xbrl_run_at, last_news_at }`. Use to detect ingestion staleness even when services are technically 'up'. A `last_filing_at` more than 10 minutes stale during ET market hours is the canonical ingestion-pipeline alert.
- `as_of` (string): ISO-8601 UTC timestamp the status snapshot was generated server-side. Cached for 30 seconds at the gateway — polling more aggressively than 1 Hz returns stale-but-cheap data.

**Since:** v2.1.0

**Utility:** Public service-health probe — current operational status of every FinRadar service (main_api, insider_module, 13f_worker, postgres_db, redis, etc.) with rolling 30-day and 90-day uptime percentages. Also includes data-freshness metrics (last filing accepted, queue depth, last 13F batch parsed) so customers can verify ingestion is current BEFORE making decisions on the underlying data — a green status with `last_filing_at` 12 hours stale is misleading without this layer. No authentication required, free (`cost: 0`). The right endpoint for: status pages, monitoring dashboards, operational alerting integrations, and pre-flight checks on automation pipelines. Pair with `/api/v1/status/history` for time-bucketed historical uptime charts.

**Use case:** Building a status page or monitoring dashboard that shows service health at a glance.

**Sample response:**
```json
{
  "status": "operational",
  "services": {
    "main_api": {
      "status": "healthy",
      "response_time_ms": 45,
      "uptime_30d": 99.95,
      "uptime_90d": 99.87,
      "checked_at": "2026-03-14T12:00:00Z"
    },
    "postgres_db": {
      "status": "healthy",
      "response_time_ms": 12,
      "uptime_30d": 100,
      "uptime_90d": 99.99,
      "checked_at": "2026-03-14T12:00:00Z"
    },
    "redis": {
      "status": "healthy",
      "response_time_ms": 3,
      "uptime_30d": 100,
      "uptime_90d": 100,
      "checked_at": "2026-03-14T12:00:00Z"
    }
  },
  "checked_at": "2026-03-14T12:00:00Z"
}
```

### GET /api/v1/status/history

Time-bucketed uptime history for building charts. Supports per-service filtering and hourly/daily resolution.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `days` (integer): Echoed history window in days.
- `resolution` (string): Echoed bucket size — `hourly` or `daily` (after server-side clamp if applicable).
- `history` (object): Map of `service_name -> [bucket]` arrays. When `?service=...` is filtered, only that service's array is present; otherwise all services are included. Each service's array is in CHRONOLOGICAL order (oldest bucket first, newest last) — natural for left-to-right chart rendering.
- `history.{service}[].timestamp` (string): ISO 8601 UTC timestamp of the BUCKET START. For hourly buckets: `2026-05-02T18:00:00Z` (top of the hour). For daily buckets: `2026-05-02T00:00:00Z` (UTC midnight).
- `history.{service}[].total_checks` (integer): Total number of health-checks performed in the bucket. The watchdog runs every 60s by default — so an hourly bucket has ~60 checks and a daily bucket has ~1,440. Useful as the denominator for any custom uptime calculation.
- `history.{service}[].healthy` (integer): Count of `healthy` (200 + < 1s response) checks in the bucket.
- `history.{service}[].degraded` (integer): Count of `degraded` (200 but slow >1s, or 5xx but auto-recovered) checks in the bucket. Degraded counts indicate intermittent issues — surfaced as a yellow bar on status-page UIs.
- `history.{service}[].down` (integer): Count of `down` (connection-refused, timeout, sustained 5xx) checks in the bucket. Surfaced as a red bar on status-page UIs.
- `history.{service}[].uptime_pct` (number): Convenience field — `round(healthy / total_checks * 100, 2)`. Display-ready for status-page bar tooltips (e.g. 'May 2: 99.86% uptime').
- `history.{service}[].avg_response_ms` (integer): Bucket-mean response time in milliseconds. Useful for surfacing latency-spike events on a separate chart line.
- `meta` (object): Query echo + warnings: `{ generated_at: string, services_included: string[], warning: string|null }`. The `warning` field surfaces messages like `"resolution clamped from hourly to daily — bucket count would exceed 200"` when the (resolution, days) combination produces too many buckets.

**Since:** v2.1.0

**Utility:** Time-bucketed uptime history for charting — Phase 39+ system-status work product. Returns per-service health buckets (total_checks / healthy / degraded / down counts + uptime_pct + avg_response_ms) at hourly or daily resolution. EXEMPT (`cost: 0`) — safe for public-facing status-page polling. Pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for the current-state snapshot (this endpoint is for historical trend visualization only).

**Use case:** Rendering a 90-day uptime bar chart on a public status page (the standard `https://status.example.com/` style). Also useful for SLA reporting to enterprise customers ('we maintained 99.95% uptime over the last 30 days') and for incident retrospectives ('show me the response-time spike around the 2026-04-22 throttle event').

**Parameters:**
- `service` (query, optional): Filter by service name. Valid values: `main_api`, `insider_api`, `postgres_db`, `redis`, `sec_worker`, `sec_13f_worker`, `news_daemon`, `sec_gateway`, `frontend`. Omit for ALL services (returns multi-service rollup). Internal service names match the docker-compose container names so they're stable across deploys.
- `days` (query, optional, default: 30): History window in days (max 90). Server caps at 90 — values > 90 silently clamp.
- `resolution` (query, optional, default: daily): Bucket size: `hourly` (good for 1-7 day windows; up to 168 buckets) or `daily` (good for 30-90 day windows; up to 90 buckets). The endpoint warns via the `meta.warning` field if the (resolution, days) combination would produce > 200 buckets (e.g. `hourly + days=30` = 720 buckets is auto-clamped to daily server-side).

**Sample response:**
```json
{
  "days": 30,
  "resolution": "daily",
  "history": {
    "main_api": [
      {
        "timestamp": "2026-04-03T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1438,
        "degraded": 2,
        "down": 0,
        "uptime_pct": 99.86,
        "avg_response_ms": 52
      },
      {
        "timestamp": "2026-04-04T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1440,
        "degraded": 0,
        "down": 0,
        "uptime_pct": 100,
        "avg_response_ms": 48
      },
      {
        "timestamp": "2026-04-22T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1278,
        "degraded": 132,
        "down": 30,
        "uptime_pct": 88.75,
        "avg_response_ms": 287
      }
    ]
  },
  "meta": {
    "generated_at": "2026-05-02T20:15:00Z",
    "services_included": [
      "main_api"
    ],
    "warning": null
  }
}
```

---

## Form 13D/13G

Query parsed Schedule 13D and 13G beneficial ownership filings. 13D filings are required when a person or group acquires more than 5% of a company's shares with an activist intent; 13G filings are the passive-investor equivalent.

### POST /api/v1/form-13d

Search and filter parsed 13D/13G ownership filings. Supports filtering by ticker, issuer CIK, filer CIK, filer name, minimum ownership percentage, and form type.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Retrieve structured beneficial ownership data including percent of class, shares owned, voting power, and stated purpose of transaction.

**Use case:** Track activist investors building positions (>5% ownership), monitor large institutional ownership changes, identify takeover or proxy-fight filings, screen for high-conviction positions by ownership threshold.

**Parameters:**
- `query.ticker` (body, optional): Issuer trading symbol (e.g. 'TWTR'). Case-insensitive.
- `query.issuerCik` (body, optional): Issuer CIK number. Leading zeros are stripped automatically.
- `query.filerCik` (body, optional): Filer (reporting person) CIK. Leading zeros are stripped automatically.
- `query.filerName` (body, optional): Partial match on filer name (case-insensitive). E.g. 'Elon Musk'.
- `query.minOwnership` (body, optional): Minimum percent of class owned. E.g. 5.0 for >= 5%.
- `query.formType` (body, optional): Filter by form type: 'SC 13D', 'SC 13D/A', 'SC 13G', 'SC 13G/A'. Both SC and SCHEDULE variants accepted.
- `query.dateRange.from` (body, optional): Start date filter (ISO format, e.g. '2025-01-01').
- `query.dateRange.to` (body, optional): End date filter (ISO format, e.g. '2026-03-14').
- `from` (body, optional, default: 0): Pagination offset.
- `size` (body, optional, default: 50): Page size (max 50).
- `sort` (body, optional, default: [{"filedAt":{"order":"desc"}}]): Sort specification. Supported fields: filedAt, percentOfClass, sharesOwned.

**Sample response:**
```json
{
  "status": "success",
  "data": [
    {
      "accessionNo": "0001193125-22-104916",
      "formType": "SC 13D",
      "filedAt": "2022-04-14T00:00:00Z",
      "issuer": {
        "name": "Twitter Inc",
        "cik": "1418091",
        "ticker": "TWTR"
      },
      "filer": {
        "name": "Elon Musk",
        "cik": "1494730"
      },
      "ownership": {
        "percentOfClass": 9.2,
        "sharesOwned": 73486938,
        "soleVotingPower": 73486938,
        "sharedVotingPower": 0
      },
      "purpose": "Investment purposes and to engage in discussions with the Board...",
      "cusip": "90184L102",
      "dateOfEvent": "2022-03-14",
      "isAmendment": false
    }
  ],
  "meta": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "from": 0,
    "size": 50
  }
}
```

---

## Beneficial Ownership (13D/13G) — New

Comprehensive beneficial ownership API with normalized multi-table data model. Supports multi-filer group filings, purpose classification, amendment tracking with threshold crossing detection, and unified holder identity linking across Form 4, 13F, and 13D/G. Response fields include: cusip (array), nameOfIssuer, titleOfSecurities, eventDate, secFilingUrl, entities (array from SGML index with name/cik/irsNo/sic), groupMembers (array for group filings), signatures, applicableRule (13G), footnotes. Filer objects include: entityType (entity/individual), citizenship, principalOccupation, employerName, legalProceedingsDisclosureRequired (boolean), per-filer footnotes. Position objects include: sourceOfFunds (array), typeOfReportingPerson (array), amountOfFunds, amountExcludesCertainShares, indirectOwnershipExplanation, sharesAcquirable60Days.

### GET /api/v1/ownership/beneficial-ownership/filings

List and filter beneficial ownership filings with full structured data.

**Token cost:** 10 tokens per call

**Response fields:**
- `filings` (array): Array of filing rows — one row per `(accession_number, filer_cik)` pair (so a 13D filed jointly by 3 group members produces 3 rows). Sorted per the `sort` + `order` parameters. Empty array on no match.
- `filings[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/ownership/beneficial-ownership/filings/{accession}` to retrieve the full structured payload (all filers + positions + exhibits + amendment chain).
- `filings[].formType` (string): Schedule 13D/13G form type — one of `13D` (active intent — 10-day filing window after crossing 5%), `13G` (passive intent — annual filing), `13D/A` (13D amendment), `13G/A` (13G amendment). The `/A` suffix is preserved verbatim. 13D filings carry materially higher signal than 13G — they require disclosing INTENT, not just OWNERSHIP.
- `filings[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. Distinct from `eventDate` (the date that triggered the filing obligation — typically the date the position crossed 5%). For activist surveillance, the `filedAt` lag from `eventDate` is itself a signal (close-to-deadline filings indicate compliance-heavy intent vs proactive disclosure).
- `filings[].issuerCik` (string): Issuer CIK (the company being reported on, NOT the filer). 10-character zero-padded string. The natural join key against `/api/v1/sec/filings`, `/financials/metrics`, and `/insider-module/api/insiders/transactions/by-ticker/{ticker}`.
- `filings[].issuerTicker` (string (nullable)): Issuer ticker resolved from the issuer CIK via `ticker_norm_aliases`. Null when the issuer has no public-equity ticker (private-company 13D filings against pending mergers, foreign issuers without ADRs). Multi-class issuers return the canonical class (typically the most-traded one).
- `filings[].nameOfIssuer` (string): Issuer name AS FILED on the cover page (typically all-caps in EDGAR convention). Casing preserved verbatim — for canonical company name use the Sharadar SF1 lookup via the issuer CIK.
- `filings[].filerCik` (string): Filer CIK (the entity DOING the reporting — fund, family office, individual, or activist). 10-character zero-padded string. Join key for filer-portfolio queries via `/ownership/beneficial-ownership/filers/{cik}/portfolio`.
- `filings[].filerName` (string): Filer name AS FILED (typically all-caps EDGAR convention). For activists this often surfaces multi-entity structures (e.g. `ICAHN CARL C`, `ICAHN ENTERPRISES LP`, `ICAHN PARTNERS LP` — all Carl Icahn affiliates). Use `filerCik` as the stable identifier.
- `filings[].percentOfClass` (number (nullable)): Aggregate beneficial-ownership percent of the issuer's voting class, as reported by the filer (Item 13 on the cover page). Above 5.00 is the regulatory trigger threshold. Null only when the filing was malformed or the cover page omitted the field (rare; mostly pre-2010 archival filings).
- `filings[].sharesOwned` (number (nullable)): Aggregate shares beneficially owned across all positions in the filing. Includes shared voting + dispositive power. Always positive. Null only on malformed legacy filings. NOT split-adjusted — preserves the as-filed view.
- `filings[].priorPercent` (number (nullable)): Ownership percent from the prior filing by the same `(filer, issuer)` pair (auto-linked via amendment-chain detection — added v3.3.2). Null on the original filing (no prior). Useful for amendment-chain analysis without separate round-trips.
- `filings[].percentChange` (number (nullable)): Delta in `percentOfClass` vs the prior filing (current - prior). Positive = position increased; negative = position decreased. Null on the original filing. Useful for surfacing material amendments — e.g. amendments that move a 13G holder above the 10% activist trigger.
- `filings[].sharesChange` (number (nullable)): Delta in `sharesOwned` vs the prior filing (current - prior). Positive = additional accumulation; negative = position trim. Null on the original filing. Combine with `daysSincePriorFiling` to compute accumulation rate.
- `filings[].purpose` (string (nullable)): Classified filer intent — one of `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, `block-trade`, `unspecified`, etc. Derived from rule-based NLP classification of the filing's Item 4 (Purpose of Transaction). Null on legacy pre-classification filings. The single most-watched signal for activist-detection workflows.
- `meta` (object): Pagination + filter echo block: `{ total: integer, page: integer, size: integer, applied_filters: object }`. `total` is the cap-aware match count (full-corpus when below 10000).

**Since:** v3.0.0

**Utility:** The screening workhorse for Schedule 13D/13G beneficial-ownership filings — the SEC disclosure regime that requires anyone owning >5% of a public company's voting class to file within 10 days (13D) or annually (13G). Filter by issuer (ticker/CIK), filer (name/CIK), form type (`SC_13D` for active intent, `SC_13G` for passive), minimum ownership %, date range, amendment-only, and 13G→13D conversion-only. The right entry point for activist-investor surveillance ('every 13D filed against a healthcare name this quarter'), passive-fund tracking, and ownership-threshold crossings. Each row carries QoQ change deltas (`priorPercent`, `priorShares`, `percentChange`, `sharesChange`, `daysSincePriorFiling` — added v3.3.2) so amendment chains are first-class. Pair with `/ownership/beneficial-ownership/filings/{accession}` to drill into a single filing's structured payload.

**Use case:** Screen for activist positions, track ownership changes over time, find all 13D filings for a specific issuer, filter by purpose category.

**Parameters:**
- `issuerCik` (query, optional): Filter by issuer CIK (the company being reported on). Leading zeros stripped server-side — `0000320193`, `320193`, and `00320193` all match Apple. Combine with `formType` for issuer-specific scans (e.g. all `SC_13D`s filed against AAPL).
- `issuerTicker` (query, optional): Filter by issuer ticker (case-insensitive). Server normalizes to canonical hyphen form (`BRK.A` → `BRK-A`). Multi-class issuers preserve the share class actually filed.
- `filerCik` (query, optional): Filter by filer CIK (the entity DOING the reporting — typically a fund or family office). Leading zeros stripped. Use to track one filer's activity across all issuers.
- `filerName` (query, optional): Partial-match search on filer name (case-insensitive `ILIKE '%name%'`). Less precise than `filerCik` but useful when you don't yet know the CIK. Example: `filerName=ICAHN` finds all Carl-Icahn-affiliated filings (Icahn Enterprises LP, Icahn Partners, etc.).
- `formType` (query, optional): Form type filter — exactly one of `SC_13D` (active intent — 10-day filing window after crossing 5%), `SC_13D_A` (13D amendment), `SC_13G` (passive intent — annual), `SC_13G_A` (13G amendment). Note: SEC's published form names use slashes (`SC 13D/A`); FinRadar normalizes to underscores for URL safety.
- `minOwnership` (query, optional): Minimum aggregate `percent_of_class` threshold. Default behaviour returns ALL filings (including <5% amendments that filed for cessation of beneficial ownership). Set to `5.0` to filter to >5% positions only; set to `10.0` for the 'real material activist' subset; set to `0.01` to also surface near-zero amendments documenting position exits.
- `dateFrom` (query, optional): Inclusive lower bound on `filedAt` (acceptance date — not the trade date). Format ISO `YYYY-MM-DD`. Useful for incremental-pull workflows: query `dateFrom = last_run_timestamp` to catch only new filings.
- `dateTo` (query, optional): Inclusive upper bound on `filedAt`. Format ISO `YYYY-MM-DD`. Combine with `dateFrom` for closed ranges (e.g. one quarter).
- `isAmendment` (query, optional): When `true`, filter to amendment filings only (`SC_13D_A` + `SC_13G_A`). When `false`, filter to original filings only. Omit for both. Most-frequent amendments document position-size changes and ownership-purpose updates.
- `isConversion` (query, optional): When `true`, filter to 13G→13D conversions only — i.e. filings where a passive holder upgraded to active intent (often a leading indicator of activist campaigns or going-hostile-on-board signals). When `false`, exclude conversions. Omit for both. Conversions are a small minority of filings (<5%).
- `sort` (query, optional, default: filedAt): Sort field — one of `filedAt` (default; chronological), `aggregatePercent` (largest position first), `aggregateShares` (largest share count). Combine with `order=desc/asc`.
- `order` (query, optional, default: desc): Sort direction — `asc` (oldest/smallest first) or `desc` (newest/largest first; default).
- `page` (query, optional, default: 1): 1-based page number for pagination. `page=1` returns the first page; `page=2` returns the next, etc. Combined with `size` to compute offset (`offset = (page - 1) * size`).
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Larger pages reduce round-trips for bulk-export workflows but increase per-request latency. For full corpus enumeration use date-range chunking + `size=200`.

**Sample response:**
```json
{
  "filings": [
    {
      "accessionNumber": "0001193125-26-001234",
      "formType": "13D",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "nameOfIssuer": "APPLE INC",
      "filerCik": "0001067983",
      "filerName": "BERKSHIRE HATHAWAY INC",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000,
      "priorPercent": 5.92,
      "percentChange": -0.08,
      "sharesChange": -10000000,
      "purpose": "passive"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/filings/{accession}

Get full detail for a single beneficial ownership filing.

**Token cost:** 10 tokens per call

**Response fields:**
- `accessionNumber` (string): SEC accession echoed back in canonical dashed form regardless of input casing.
- `formType` (string): Schedule form type — one of `13D`, `13G`, `13D/A`, `13G/A`. The `/A` suffix preserved verbatim. 13D filings carry materially higher signal than 13G — they require disclosing INTENT, not just OWNERSHIP.
- `filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. The 10-day filing-window deadline (for 13Ds) is computed from the trigger event date in the filing body, NOT from this `filedAt`.
- `issuer` (object): Issuer block: `{ cik: string (10-char zero-padded), ticker: string|null, name: string }`. The company being reported on. `ticker` may be null for private-issuer filings (M&A targets) or foreign-issuer filings without ADRs.
- `filers` (array): Array of all reporting persons on this filing — one entry per filer. Joint filings (Schedule 13D groups, family-office layered structures) have 2-9+ entries. Each entry: `{ cik, name, percentOfClass, sharesOwned, isOfficer, isDirector, signatureRole, address }`. Use `cik` as the stable join key against `/ownership/beneficial-ownership/filers/{cik}/portfolio`.
- `positions` (array): Array of position rows — typically one per filer (so length matches `filers[]`). Each entry exposes the SEC-mandated voting + dispositive-power decomposition: `{ filerCik, percentOfClass, sharesOwned, soleVotingPower, sharedVotingPower, soleDispositivePower, sharedDispositivePower, votingPower, dispositivePower }`. Critical for compliance — `sharedVotingPower` indicates a different control regime than `soleVotingPower`.
- `purpose` (object (nullable)): Classified purpose-of-transaction (Item 4) extracted via rule-based NLP. Shape: `{ primary: string, flags: { intends_to_acquire, opposes_management, seeks_board_seats, intends_proxy_fight, intends_tender_offer, intends_going_private, intends_recapitalization, ... } }`. `primary` enumerated as `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, `block-trade`, `unspecified`. Null on legacy pre-classification filings.
- `groupMembers` (array (nullable)): Array of co-filer entities when this filing is part of a Schedule 13D group (an explicit cooperation pact for accumulating > 5%). Each entry: `{ cik, name, isLeadFiler }`. Null when not a group filing (most are single-filer).
- `exhibits` (array (nullable)): Exhibits attached to the filing — array of `{ type, url, description }` (e.g. shareholder agreements, joint-filing agreements, settlement deeds, demand letters). Activist filings often have multi-page exhibits (Carl Icahn's letters to boards routinely run 5-10 pages). Null when filing has no exhibits.
- `footnotes` (array (nullable)): Per-filer footnotes parsed from the filing's notes section — array of `{ filerCik, footnote }`. Footnotes typically clarify the nature of indirect ownership (trust, LP, family office vehicle) or split-credit attribution. Null when filing has no footnotes.

**Since:** v3.0.0

**Utility:** Drill into the full structured payload of a single Schedule 13D/13G filing once you've identified the accession via `/ownership/beneficial-ownership/filings`. Returns the complete amendment-chain context: all filers (joint filings can have 2-9+ entities), per-filer position rows with separated voting/dispositive power, classified purpose with NLP-extracted intent flags (`intends_to_acquire`, `opposes_management`, `seeks_board_seats`, `intends_proxy_fight`), Schedule 13D group memberships, parsed exhibits with URLs, and per-filer footnotes. The right endpoint for activist-thesis research, M&A-related ownership disclosure analysis, and compliance / KYC due-diligence on filers.

**Use case:** Deep-dive into a specific 13D/13G filing to understand ownership structure, intent, and exhibits.

**Parameters:**
- `accession` (path, required): SEC accession number — accepts both canonical dashed form (`0001193125-22-104916`) and undashed form (`000119312522104916`). Server normalizes both. Returns 404 when the accession is not a 13D/13G/13D-A/13G-A filing in our parser cache (other form types return Form 4 / 13F detail via their respective endpoints).

**Sample response:**
```json
{
  "accessionNumber": "0001193125-26-001234",
  "formType": "13D",
  "filedAt": "2026-04-15T20:14:32.000Z",
  "issuer": {
    "cik": "0000320193",
    "ticker": "AAPL",
    "name": "APPLE INC"
  },
  "filers": [
    {
      "cik": "0001067983",
      "name": "BERKSHIRE HATHAWAY INC",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000
    }
  ],
  "positions": [
    {
      "filerCik": "0001067983",
      "percentOfClass": 5.84,
      "sharesOwned": 905560000,
      "votingPower": 905560000
    }
  ],
  "purpose": {
    "primary": "passive",
    "flags": {
      "intends_to_acquire": false,
      "opposes_management": false
    }
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/issuers/{cik}/summary

Ownership summary for an issuer — all beneficial owners with latest positions.

**Token cost:** 10 tokens per call

**Response fields:**
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker (private-company M&A targets, foreign issuers without ADRs, dissolved entities).
- `nameOfIssuer` (string): Issuer name from the most recent filing's cover page (typically all-caps EDGAR convention). Multiple historical filings may have used variant names (rare; e.g. post-rebrand) — most-recent name wins.
- `asOf` (string): ISO-8601 UTC timestamp of the most-recent 13D/13G filing across all filers on this issuer. Use to gauge data freshness — values older than 12 months on a heavily-held name (where 13G's are mandatory annually) indicate either ingest staleness or a true ownership-stability period.
- `beneficialOwners` (array): Array of current beneficial owners — one row per `(filerCik, latest_filing)`. Sorted by `latestPercent DESC` (largest holder first). Excludes filers whose most-recent filing reported < 0.01% (cessation-of-ownership amendments). Empty array when the issuer has had filings but ALL have been cessations.
- `beneficialOwners[].filerCik` (string): Filer CIK in 10-char zero-padded form. The stable identifier — pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` for this filer's full beneficial-ownership book.
- `beneficialOwners[].filerName` (string): Filer name from the most recent filing (typically all-caps EDGAR convention). Casing preserved verbatim.
- `beneficialOwners[].latestPercent` (number (nullable)): Most recent reported `percent_of_class` for this filer. Above 5.00 by definition (filing trigger). Null only on legacy filings that omitted the field.
- `beneficialOwners[].latestShares` (number (nullable)): Most recent reported aggregate share count. Includes shared voting + dispositive power. NOT split-adjusted.
- `beneficialOwners[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent filing by this filer. Useful for sorting by recency vs by size — a 5.5% holder who just filed is more actionable than a 25% holder whose last filing was 3 years ago.
- `beneficialOwners[].purpose` (string (nullable)): Classified intent from the most recent filing — `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, etc. Null on legacy pre-classification filings. The signal-density metric for the holder list.

**Since:** v3.0.0

**Utility:** Per-issuer roll-up of all 13D/13G beneficial owners — the >5%-of-class shareholder list as of the most recent filing per `(filer, issuer)` pair (amendments collapsed to the latest). Drives the 'Beneficial Owners' panel on every issuer-overview page. The right answer to 'who controls this company outside of mutual-fund passive ownership?' — surfacing activists (Carl Icahn at AAPL, Bill Ackman at QSR), strategic holders (Berkshire's preferred-stock-and-warrants in BAC), and 13G-passive concentrated holders (Vanguard, BlackRock, State Street). For per-FILER portfolio across multiple issuers use `/ownership/beneficial-ownership/filers/{cik}/portfolio`.

**Use case:** Build an ownership breakdown chart, identify top shareholders, detect activist positions.

**Parameters:**
- `cik` (path, required): Issuer CIK (the company being looked up — NOT the filer). Accepts both 10-char zero-padded form (`0000320193`) and unpadded (`320193`). Returns 404 when no 13D/13G filings have ever been filed against this issuer (e.g. very-thinly-held private companies or pre-IPO names).

**Sample response:**
```json
{
  "issuerCik": "0000320193",
  "issuerTicker": "AAPL",
  "nameOfIssuer": "APPLE INC",
  "asOf": "2026-05-01T20:55:12.000Z",
  "beneficialOwners": [
    {
      "filerCik": "0001067983",
      "filerName": "BERKSHIRE HATHAWAY INC",
      "latestPercent": 5.84,
      "latestShares": 905560000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z",
      "purpose": "passive"
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/filers/{cik}/portfolio

Portfolio view for a filer — all issuers they have beneficial ownership of.

**Token cost:** 10 tokens per call

**Response fields:**
- `filerCik` (string): Filer CIK echoed back in 10-char zero-padded form regardless of input.
- `filerName` (string): Filer name from the most recent filing (typically all-caps EDGAR convention). For activists this often surfaces multi-entity structures — the most-recently-filed legal name wins.
- `positions` (array): Array of current beneficial-ownership positions — one row per issuer where this filer has a non-cessation 13D/13G position. Sorted by `latestPercent DESC` (largest position first). Excludes issuers whose most-recent filing was a cessation amendment (< 0.01%).
- `positions[].issuerCik` (string): Issuer CIK in 10-char zero-padded form. Stable join key for issuer-side queries.
- `positions[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker (private companies, foreign issuers without ADRs).
- `positions[].nameOfIssuer` (string): Issuer name from the most recent filing's cover page (typically all-caps EDGAR convention).
- `positions[].latestPercent` (number (nullable)): Latest reported `percent_of_class` for this filer at this issuer. Above 5.00 by definition (filing trigger). Null on legacy filings that omitted the field.
- `positions[].latestShares` (number (nullable)): Latest reported aggregate share count. Includes shared voting + dispositive power. NOT split-adjusted.
- `positions[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent filing. Use to detect stale positions — values older than 12 months on a 13G holder may indicate ingest staleness or an annual-filing window not yet reached.
- `positions[].purpose` (string (nullable)): Classified intent at the latest filing — `passive`, `activist`, `m&a`, `going-private`, `proxy-fight`, `recapitalization`, etc. Null on legacy pre-classification filings. Look for `passive` → `activist` purpose transitions across time as the strongest activist-conversion signal.
- `meta` (object): Pagination + filter echo block: `{ total: integer, limit: integer }`. `total` is the full position count; pagination not currently exposed via this endpoint (positions list is bounded since most filers hold < 100 positions).

**Since:** v3.0.0

**Utility:** Per-filer beneficial-ownership portfolio: every issuer where this filer has filed a 13D/13G with a current >5% (or >0.01% non-cessation) position. The inverse of `/issuers/{cik}/summary` — drill into one specific activist or fund (Carl Icahn, Bill Ackman, Berkshire Hathaway, Engine No. 1) and get the full list of companies they hold significant beneficial ownership in. Drives activist-portfolio tracker dashboards, copycat-investor research, and 'who else does Carl Icahn target?' workflows. Pair with `/ownership/holders/{uuid}/filing-history` for the time-ordered filing chain across both 13D/G and 13F sources.

**Use case:** Track an activist investor's portfolio of positions across multiple companies.

**Parameters:**
- `cik` (path, required): Filer CIK (the entity DOING the reporting — fund, family office, individual). Accepts both 10-char zero-padded form (`0001067983`) and unpadded (`1067983`). Common activist CIKs: `0001412082` (Carl Icahn), `0001336528` (Pershing Square — Bill Ackman), `0001067983` (Berkshire Hathaway). Returns 404 when the CIK has never filed a 13D/13G.

**Sample response:**
```json
{
  "filerCik": "0001067983",
  "filerName": "BERKSHIRE HATHAWAY INC",
  "positions": [
    {
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "nameOfIssuer": "APPLE INC",
      "latestPercent": 5.84,
      "latestShares": 905560000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z",
      "purpose": "passive"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### GET /api/v1/ownership/beneficial-ownership/activists

Activist tracker — recent 13D filings with NLP purpose classification.

**Token cost:** 10 tokens per call

**Response fields:**
- `activists` (array): Array of activist-classified filing rows, sorted by `filedAt DESC` (most recent first). Empty array when no filings match the filters in the date window. Pre-filtered upstream — every row has `purpose='activist'` (or one of the activist-aligned purpose categories).
- `activists[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `/ownership/beneficial-ownership/filings/{accession}` for full filing detail (all filers, exhibits, footnotes).
- `activists[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. Compare against issuer's stock-price action — activist 13D filings often trigger 5-15% next-day price moves.
- `activists[].issuerCik` (string): Issuer CIK in 10-char zero-padded form. The company being targeted by the activist campaign.
- `activists[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null for private-company targets (M&A activist filings on pending deals occasionally surface against unlisted entities).
- `activists[].filerCik` (string): Filer CIK in 10-char zero-padded form (the activist entity). Pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` for the activist's full position book.
- `activists[].filerName` (string): Activist filer name (typically all-caps EDGAR convention). Common high-signal names: `ICAHN CARL C`, `PERSHING SQUARE CAPITAL MANAGEMENT LP`, `TRIAN FUND MANAGEMENT LP`, `ELLIOTT ASSOCIATES LP`, `STARBOARD VALUE LP`, `ENGINE NO 1 LP`.
- `activists[].percentOfClass` (number (nullable)): Reported aggregate `percent_of_class`. Above 5.00 by definition (filing trigger). Activist positions typically fall in 5-12% range — much higher than that and the filer crosses additional regulatory thresholds (e.g. 10% for short-swing profit rules).
- `activists[].purpose` (string): Always one of the activist-aligned purpose categories (the endpoint pre-filters out `passive`). Values: `activist`, `m&a`, `proxy-fight`, `going-private`, `recapitalization`, `restructuring`. Use the more granular `purposeCategory` filter to drill further.
- `activists[].intentFlags` (object (nullable)): Granular boolean flags from rule-based NLP extraction of Item 4 text. Schema: `{ opposes_management: bool, board_seat_demand: bool, m&a_pressure: bool, intends_proxy_fight: bool, intends_tender_offer: bool, ... }`. The signal-density layer ABOVE the single `purpose` field — a `purpose='activist'` filing with `board_seat_demand=true AND opposes_management=true` is a near-certain proxy fight.
- `meta` (object): Pagination + filter echo block: `{ total: integer, page: integer, size: integer, applied_filters: object }`. `total` is full-corpus match count for the filter set.

**Since:** v3.0.0

**Utility:** The activist-investor watchlist endpoint — pre-filtered to filings classified as `activist` intent by FinRadar's rule-based NLP purpose classifier (running across the Item 4 'Purpose of Transaction' text on every 13D). Drives the canonical 'who's launching activist campaigns this week?' dashboard. Filterable by issuer ticker, filer name (e.g. all Trian Fund Management filings), minimum ownership %, date range, and 13-category purpose taxonomy (BOARD_REPRESENTATION, PROXY_CONTEST, MERGER_ACQUISITION, TENDER_OFFER, etc.). Each row carries `intentFlags` — granular boolean signals (`opposes_management`, `board_seat_demand`, `m&a_pressure`) that go beyond the single `purpose` category. The right entry point for hostile-takeover surveillance, proxy-fight tracking, and copycat-investor research. For all-purposes (passive + activist) ownership data use `/ownership/beneficial-ownership/filings`.

**Use case:** Monitor activist campaigns, screen for board fights, merger pressure, restructuring demands. Filter by ticker, filer name, or minimum ownership.

**Parameters:**
- `issuerTicker` (query, optional): Issuer ticker filter, case-insensitive (server normalizes to canonical hyphen form). Returns only activist filings against this specific issuer. Useful for company-overview pages: 'is anyone running an activist campaign against this name right now?'
- `filerName` (query, optional): Partial-match search on filer name (case-insensitive `ILIKE '%name%'`). Useful for tracking known activists across all their targets — `filerName=ICAHN` finds all Carl-Icahn-affiliated filings, `filerName=PERSHING` finds all Bill-Ackman-affiliated filings. Less precise than `filerCik`-based portfolio queries; use this for exploration.
- `minOwnership` (query, optional): Minimum aggregate `percent_of_class` threshold (added v3.7.3). Default returns all activist filings; setting `5.0` surfaces material >5% activist positions; setting `10.0` returns only large-block activists. Useful for filtering out de minimis filings that don't carry real campaign weight.
- `dateFrom` (query, optional): Inclusive lower bound on `filedAt`. Format ISO `YYYY-MM-DD`. For incremental polling, set to `last_run_timestamp` to pick up only newly-filed activist campaigns.
- `dateTo` (query, optional): Inclusive upper bound on `filedAt`. Format ISO `YYYY-MM-DD`. Combine with `dateFrom` for closed ranges.
- `purposeCategory` (query, optional): Filter to one of 13 purpose categories: `PASSIVE_INVESTMENT`, `ACTIVE_INVESTMENT`, `BOARD_REPRESENTATION` (board-seat demands), `MERGER_ACQUISITION` (M&A intent), `TENDER_OFFER`, `PROXY_CONTEST` (proxy fights), `CHANGE_MANAGEMENT` (CEO-replacement campaigns), `RESTRUCTURING`, `CAPITAL_RETURN` (buyback/dividend pressure), `GOVERNANCE_CHANGE`, `STRATEGIC_ALTERNATIVES` (sale-of-company demand), `SPIN_OFF`, `OTHER`. Each filing maps to exactly one primary category.
- `page` (query, optional, default: 1): 1-based page number. `page=1` returns the first page (most-recent activist filings); increment to walk back chronologically.
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Activist filings are a small minority of 13D/13G corpus (~5-10%) so even broad date ranges stay below the deep-pagination cap.

**Sample response:**
```json
{
  "activists": [
    {
      "accessionNumber": "0001193125-26-001999",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "filerCik": "0001637207",
      "filerName": "TRIAN FUND MANAGEMENT LP",
      "percentOfClass": 6.2,
      "purpose": "activist",
      "intentFlags": {
        "opposes_management": true,
        "board_seat_demand": true
      }
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/conversions

List 13G-to-13D and 13D-to-13G filing type conversions.

**Token cost:** 10 tokens per call

**Response fields:**
- `conversions` (array): Array of conversion rows, sorted by `convertedAt DESC` (most recent first). Each row pairs the prior + current filings so the conversion direction and the gap-since-prior are observable in one go. Empty array when no conversions in the date window.
- `conversions[].filerCik` (string): Filer CIK in 10-char zero-padded form (the entity that converted). Pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` to see the filer's full position book.
- `conversions[].filerName` (string): Filer name from the current filing (typically all-caps EDGAR convention). For activist conversions, common high-signal names: `TRIAN FUND MANAGEMENT LP`, `STARBOARD VALUE LP`, `ELLIOTT INVESTMENT MANAGEMENT LP`.
- `conversions[].issuerCik` (string): Issuer CIK in 10-char zero-padded form (the company being targeted). Pass to `/ownership/beneficial-ownership/issuers/{cik}/summary` for the full beneficial-owner roll-up.
- `conversions[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null only for private-issuer conversions (rare; most M&A target conversions resolve).
- `conversions[].priorFormType` (string): Form type of the PRIOR filing — `13G` (passive) or `13D` (active). Together with `currentFormType` defines the conversion direction.
- `conversions[].currentFormType` (string): Form type of the CURRENT filing that triggered the conversion. The interesting cases: `priorFormType=13G AND currentFormType=13D` (passive going active — typical activist campaign launch), `priorFormType=13D AND currentFormType=13G` (active winding down).
- `conversions[].direction` (string): Conversion direction — literal `"passive_to_active"` (13G→13D, activist campaign launching) or `"active_to_passive"` (13D→13G, campaign winding down). The single most important field on this endpoint — filter on `direction` for direction-specific surveillance.
- `conversions[].priorAccession` (string): SEC accession of the PRIOR filing. Pass to `/ownership/beneficial-ownership/filings/{accession}` to retrieve the prior filing's full structured payload (purpose, intent flags, exhibits).
- `conversions[].currentAccession` (string): SEC accession of the CURRENT (conversion-triggering) filing. Pass to `/ownership/beneficial-ownership/filings/{accession}` for the new filing's full payload — typically more interesting than the prior filing since it carries the new declared intent.
- `conversions[].convertedAt` (string): ISO-8601 UTC timestamp of the CURRENT filing (the moment the conversion was disclosed). The `convertedAt - priorFiledAt` gap is itself a signal — fast conversions (within weeks) suggest a planned escalation; slow conversions (months) suggest opportunistic shifts.

**Since:** v3.0.0

**Utility:** Surfaces filings where a beneficial owner CONVERTED between 13G (passive) and 13D (active) reporting status — a rare but extremely high-signal event because the conversion is the regulatory moment a filer's PUBLICLY-DECLARED INTENT changed. The 13G→13D direction (`passive_to_active`) is the canonical 'activist campaign launching' indicator: a fund that was reporting passively suddenly switches to active disclosure because they intend to influence management. The reverse direction (`active_to_passive`) often signals the campaign winding down — settlement reached, board seats won, position taking back to passive holding. Each row pairs the prior + current accession so the conversion is observable in one round-trip. The most actionable single endpoint in the 13D/G surface for proxy-fight surveillance.

**Use case:** Early detection of passive holders turning activist, or activist campaigns winding down.

**Parameters:**
- `dateFrom` (query, optional): Inclusive lower bound on `convertedAt` (the date of the conversion-triggering current filing). Format ISO `YYYY-MM-DD`. Use to incrementally poll only new conversions: `dateFrom = last_run_timestamp`.
- `page` (query, optional, default: 1): 1-based page number. Conversions are a small minority of 13D/G corpus (<2%); even broad date ranges typically fit on a single page.
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. Practical cap matters less here than on the broader filings endpoint because the conversion universe is small.

**Sample response:**
```json
{
  "conversions": [
    {
      "filerCik": "0001637207",
      "filerName": "TRIAN FUND MANAGEMENT LP",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "priorFormType": "13G",
      "currentFormType": "13D",
      "direction": "passive_to_active",
      "priorAccession": "0001193125-25-987654",
      "currentAccession": "0001193125-26-001999",
      "convertedAt": "2026-04-15T20:14:32.000Z"
    }
  ]
}
```

### GET /api/v1/ownership/beneficial-ownership/groups

List group filings where multiple parties act together.

**Token cost:** 10 tokens per call

**Response fields:**
- `groups` (array): Array of group rows, sorted by `aggregatePercent DESC` (largest groups first). Each group represents one coordinated filing structure against one issuer. A single issuer can have multiple groups (overlapping or distinct membership) if different consortia have filed separate Schedule 13Ds. Empty array on no match.
- `groups[].groupId` (string): Internal stable group identifier in `grp_XXXXXX` format (e.g. `grp_8a1f`). Unique per `(issuer, group_member_set)` tuple — re-runs return the same ID. Use as a join key when caching group state across polls.
- `groups[].issuerCik` (string): Target issuer CIK in 10-char zero-padded form. The company the coordinated group is filing against.
- `groups[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null for private-company target groups (rare; most groups target public issuers).
- `groups[].members` (array): Array of member filer rows. Length 2-9+ (2 is most common — typical PE LP+GP structure; 5+ is rare and usually indicates a multi-party activist coalition like Engine No. 1's 2021 ExxonMobil board fight). Sorted by member CIK for stable ordering.
- `groups[].members[].filerCik` (string): Member filer CIK in 10-char zero-padded form. Each member is itself a 13D/G filer — pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` to see their full beneficial-ownership book outside of this group.
- `groups[].members[].filerName` (string): Member filer name as filed (typically all-caps EDGAR convention). For activist groups commonly mixes fund-entity names + individual principal names (e.g. `TRIAN FUND MANAGEMENT LP` + `NELSON PELTZ`).
- `groups[].aggregatePercent` (number): Group's combined aggregate `percent_of_class` summed across all members. Above 5.00 by definition (since group membership triggers a Schedule 13D). Wolf-pack groups typically aggregate to 6-12%; SPAC sponsor consortia often 15-25%.
- `groups[].aggregateShares` (number): Group's combined aggregate share count summed across all members. NOT split-adjusted — preserves as-filed view. Use this with `aggregatePercent` to compute the implied total class outstanding.
- `groups[].latestFiledAt` (string): ISO-8601 UTC timestamp of the most recent group-member filing. With `activeOnly=true`, this will always be within the last 12 months. Use to detect group-state changes — long gaps may indicate unfiled cessations or membership changes that haven't yet hit our parser.

**Since:** v3.0.0

**Utility:** Schedule 13D groups — coordinated filers who file together as a single beneficial-ownership group under SEC Section 13(d)(3) (a 'group' is formed whenever 2+ entities agree to act together for the purpose of acquiring or holding the issuer's securities). Each row lists ALL members + their aggregate position. The most actionable use case is detecting 'wolf pack' formations — 2-5 activist funds quietly coordinating a >5% position before any individual filer crosses the threshold. Also surfaces SPAC sponsor consortia, family-office layered structures, and buyout-fund + management rollups in pre-merger filings. Pair with `/ownership/beneficial-ownership/activists` to see groups whose purpose is classified as activist intent.

**Use case:** Identify coordinated investor groups, wolf pack formations.

**Parameters:**
- `issuerCik` (query, optional): Filter to groups targeting this issuer (the company being collectively held). Accepts both 10-char zero-padded form (`0000051143`) and unpadded (`51143`). Returns empty array when no groups have ever filed against this issuer (most companies).
- `activeOnly` (query, optional, default: true): When `true` (default), returns only groups whose latest filing was within the last 12 months — i.e. structurally still active. When `false`, includes historical groups whose campaigns have wound down (member departure, group dissolution amendment, full position exit). Set to `false` for activism-history research; leave default for current-state surveillance.

**Sample response:**
```json
{
  "groups": [
    {
      "groupId": "grp_8a1f",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "members": [
        {
          "filerCik": "0001637207",
          "filerName": "TRIAN FUND MANAGEMENT LP"
        },
        {
          "filerCik": "0001637208",
          "filerName": "NELSON PELTZ"
        }
      ],
      "aggregatePercent": 6.2,
      "aggregateShares": 56830000,
      "latestFiledAt": "2026-04-15T20:14:32.000Z"
    }
  ]
}
```

---

## Unified Holders

Cross-system holder identity linking Form 4 insiders, 13F institutional managers, and 13D/G beneficial owners into unified profiles.

### GET /api/v1/ownership/holders

Search unified holders across all filing types.

**Token cost:** 5 tokens per call

**Response fields:**
- `holders` (array): Array of unified-holder rows matching the search. Order: by relevance score DESC for `q` search, by name ASC for `cik` exact match. Empty array on no matches — does NOT 404.
- `holders[].holder_uuid` (string): Stable UUID identifier across all three SEC reporting regimes (Form 4 / 13F / 13D-G). Generated by the Phase 47 holder-linker via deterministic hashing of `(canonical_cik, normalized_name)` clustering. Pass to [GET /api/v1/ownership/holders/{uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid) for full detail or [GET /api/v1/ownership/cross-reference/{holder_uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-cross-reference) for cross-source filing history.
- `holders[].name` (string): Canonical holder name (typically all-caps EDGAR convention for SEC-registered entities). For natural persons this preserves the as-filed Form 4 name (`BUFFETT WARREN E`); for institutions it's the legal entity name.
- `holders[].cik` (string (nullable)): Primary 10-character zero-padded SEC CIK. Multi-CIK holders (rare — typically post-merger institutions) expose a primary CIK here and the full list under [GET /api/v1/ownership/holders/{uuid}](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid) `alternate_ciks[]`. Null on holders identified by name-only (no SEC CIK ever assigned — rare; mostly natural-person consortium members in 13D groups).
- `holders[].type` (string): Primary classification — `individual` (natural persons — Buffett, Icahn, Ackman), `institution` (fund entities — Berkshire, BlackRock, Vanguard), `group` (Schedule 13D consortia — multi-party activist groups). Derived from filing patterns + name heuristics by the Phase 47 linker.
- `holders[].is_insider` (boolean): `true` when the holder has filed at least one Form 3/4/5 (Section 16 insider). Section 16 covers officers, directors, and 10%+ beneficial owners.
- `holders[].is_institutional` (boolean): `true` when the holder has filed at least one 13F-HR/NT (institutional investment manager — required for entities with $100M+ AUM in 13(f) securities).
- `holders[].is_beneficial_owner` (boolean): `true` when the holder has filed at least one Schedule 13D / 13G / 13D-A / 13G-A (beneficial ownership of >5% of any registered class).
- `holders[].filing_count` (integer): Total filing count across ALL three regimes for this holder. Useful for sorting holders by activity volume client-side.
- `meta` (object): Pagination block: `{ total: integer, page: integer, size: integer, pages: integer }`. `total` is the full match count across all pages.

**Since:** v3.0.0

**Utility:** Search the Phase 47 unified-holder layer — the cross-system identity table that links Form 4 insiders, 13F institutional managers, and 13D/G beneficial owners into one canonical profile per holder. The natural search entrypoint for 'who is this entity, and what kinds of filings have they made?'. Each row carries cross-system flags (`is_insider`, `is_institutional`, `is_beneficial_owner`) so a customer can answer 'is Berkshire Hathaway both a 13F filer AND a 13D filer?' (yes — for AAPL pre-2020) in one call. The `holder_uuid` is the stable identifier across all three SEC reporting regimes — pass it to the per-holder detail endpoints for drill-downs.

**Use case:** Building a unified holder-profile UI where users can search for any party (e.g. `Buffett` or `Berkshire` or `0001067983`) and see every filing-type that party has been involved in. Also useful for 'find all hedge funds with both insider activity AND 13F holdings' screens — filter `type=insider` AND post-filter on `is_institutional=true`.

**Parameters:**
- `q` (query, optional): Name search (partial, case-insensitive). Trigram fuzzy matching on the holder_name field — `berkshire` matches `BERKSHIRE HATHAWAY INC`, `BERKSHIRE GROUP LP`, etc. Either `q` or `cik` must be provided (server returns 400 when both are omitted).
- `cik` (query, optional): CIK exact match. Both 10-character zero-padded (`0001067983`) and short unpadded (`1067983`) formats accepted via server-side `ltrim('0')` normalization. Either `q` or `cik` must be provided.
- `type` (query, optional): Filter holders by primary type: `insider` (Form 4 / Section 16 filers), `institutional` (13F filers), `beneficial` (13D/13G filers). Omit for all types. Multi-type holders (e.g. Berkshire — both institutional AND beneficial) appear under their primary type but expose all flags.
- `page` (query, optional, default: 1): 1-indexed page number for pagination.
- `size` (query, optional, default: 50): Page size (max 200). Values > 200 silently clamp to 200.

**Sample response:**
```json
{
  "holders": [
    {
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983",
      "type": "institution",
      "is_insider": false,
      "is_institutional": true,
      "is_beneficial_owner": true,
      "filing_count": 487
    },
    {
      "holder_uuid": "a2c4e6f8-1b3d-5e7f-9a0b-c1d2e3f4a5b6",
      "name": "BUFFETT WARREN E",
      "cik": "0000315090",
      "type": "individual",
      "is_insider": true,
      "is_institutional": false,
      "is_beneficial_owner": true,
      "filing_count": 124
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "size": 50,
    "pages": 1
  }
}
```

### GET /api/v1/ownership/holders/{uuid}

Get holder detail with alternate CIKs and cross-system flags.

**Token cost:** 5 tokens per call

**Response fields:**
- `holder_uuid` (string): Echoed UUID identifier.
- `name` (string): Canonical holder name.
- `type` (string): Primary classification — `individual` / `institution` / `group`.
- `primary_cik` (string (nullable)): Primary 10-character zero-padded SEC CIK (the canonical CIK chosen by the linker; typically the most-filed CIK across all regimes). Null on holders identified by name-only.
- `alternate_ciks` (array): Array of alternate 10-char zero-padded CIKs the same holder has used across filings. Multi-CIK holders are uncommon (post-merger institutions, holding-company-vs-subsidiary distinctions, or 13F-filer-vs-Section-16-filer CIK splits). Empty array for the typical single-CIK holder.
- `name_aliases` (array): Array of historical name variants the holder has filed under (former names, DBAs, post-rebrand identifiers). E.g. Facebook -> Meta Platforms appears here as `["FACEBOOK INC", "META PLATFORMS INC"]`. Useful for surfacing 'formerly known as' on profile pages.
- `is_insider` (boolean): `true` when the holder has filed Form 3/4/5.
- `is_institutional` (boolean): `true` when the holder has filed 13F-HR/NT.
- `is_beneficial_owner` (boolean): `true` when the holder has filed Schedule 13D/G.
- `filing_counts` (object): Per-regime filing counts: `{ form_4: integer, form_13f: integer, form_13dg: integer }`. Useful for activity-level visualization on profile pages (e.g. donut chart of filing-type distribution).
- `first_filing_at` (string (nullable)): ISO-8601 UTC timestamp of the holder's earliest known filing across all three regimes. Null on rare holders with empty filing history.
- `last_filing_at` (string (nullable)): ISO-8601 UTC timestamp of the holder's most-recent filing. Useful for sorting profile pages by recency or surfacing 'last seen' on dashboards.

**Since:** v3.0.0

**Utility:** Full profile of a unified holder by UUID — includes alternate CIKs (multi-CIK holders post-merger), name aliases (former names + DBAs), cross-system filing-volume metadata (per-regime counts + first/last filing dates), and the same `is_insider/is_institutional/is_beneficial_owner` flags surfaced by the search endpoint. The natural detail-page backend after a [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders) search palette resolves a UUID. Pair with [GET /api/v1/ownership/holders/{uuid}/filing-history](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid-filing-history) for the filing timeline view.

**Use case:** Building a comprehensive holder-profile page (e.g. `/holders/{uuid}`) with all CIKs, name aliases, filing-volume metadata, and cross-system flags. Also useful for verifying that the Phase 47 linker has correctly clustered identities — if an expected alternate CIK is missing from `alternate_ciks[]`, the linker may need a manual override (rare; <0.5% of holders).

**Parameters:**
- `uuid` (path, required): Holder UUID — the stable Phase-47 identifier. Look up via [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders) (`q` or `cik` search). UUIDs are deterministic across linker re-runs for the same `(canonical_cik, normalized_name)` cluster, so they're safe to persist client-side. Returns 404 on unknown UUIDs.

**Sample response:**
```json
{
  "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "name": "BERKSHIRE HATHAWAY INC",
  "type": "institution",
  "primary_cik": "0001067983",
  "alternate_ciks": [],
  "name_aliases": [
    "BERKSHIRE HATHAWAY INC"
  ],
  "is_insider": false,
  "is_institutional": true,
  "is_beneficial_owner": true,
  "filing_counts": {
    "form_4": 0,
    "form_13f": 102,
    "form_13dg": 8
  },
  "first_filing_at": "1999-11-15T17:00:00Z",
  "last_filing_at": "2026-04-15T20:14:32Z"
}
```

### GET /api/v1/ownership/holders/{uuid}/filing-history

All filings across Form 4, 13F, and 13D/G for a unified holder.

**Token cost:** 10 tokens per call

**Response fields:**
- `holder` (object): Holder identity block: `{ uuid: string, name: string, cik: string, type: 'individual'|'institution'|'group' }`. The unified profile across all three SEC reporting regimes. `type` is derived: `individual` for natural persons (Warren Buffett, Carl Icahn), `institution` for fund entities, `group` for Schedule 13D consortia.
- `history` (array): Array of filing-history rows, sorted by `filedAt DESC` (most recent first). Mixes Form 4, 13F-HR, 13D, 13G, and amendment variants — one row per filing this holder has been a party to. Empty array on holders with no SEC filing footprint (rare; the linker only creates UUIDs for holders observed in at least one filing).
- `history[].formType` (string): Canonical form type — `4` (Form 4 insider), `13F-HR` (13F holdings), `13D` (active beneficial ownership), `13G` (passive), `13D/A` / `13G/A` (amendments), `3` (initial Form 3), `5` (annual Form 5). Use to filter client-side to one regime when needed.
- `history[].accessionNumber` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to the form-type-specific filing-detail endpoint (`/insider-module/api/insiders/filings/{accession_number}` for Form 4, `/ownership/beneficial-ownership/filings/{accession}` for 13D/G).
- `history[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance. The chronological-order key for the timeline. For Form 4 this is typically within 2 business days of the trade; for 13F it's within 45 days of the quarter end; for 13D it's within 10 days of the trigger event.
- `history[].issuerCik` (string (nullable)): Issuer CIK when the filing has a single issuer (Form 4, 13D, 13G all do). Null for 13F-HR filings (those are portfolio-level — the issuer field is per-position not per-filing). Use the per-position drill-down for 13F detail.
- `history[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when (a) the filing is a 13F-HR (multi-issuer), or (b) the issuer has no public-equity ticker.
- `history[].action` (string (nullable)): Human-readable action summary derived from the filing's structured data — e.g. `"Purchased 5,000 shares at $175.25"` (Form 4), `"13G filed at 5.2% of class"` (13G), `"13D/A: position increased to 7.1%"` (13D amendment), `"13F-HR: 245 positions, $42.3B AUM"` (13F). Useful for one-line timeline rendering. Null on legacy filings where structured data is incomplete.
- `meta` (object): Pagination + filter echo block: `{ total: integer, limit: integer }`. `total` is the full filing count for the holder across all form types.

**Since:** v3.1.0

**Utility:** Cross-system filing timeline for a single beneficial-owner identity — unifies Form 4 insider transactions, 13F institutional positions, and 13D/G beneficial-ownership filings into one chronological feed. The Phase 31 Unified Holders linker matches identities across these three SEC reporting regimes via CIK + name fuzzy matching, so a single fund (e.g. Berkshire Hathaway) shows you both its Form 4 insider filings (Warren Buffett's personal trades), its 13F holdings (the institutional book), AND its 13D/G beneficial ownership (large-block positions like AAPL pre-2020). The single audit view that answers 'show me everything this entity has filed with the SEC, in time order'. Pair with `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}` for the position-state view of the same data, or `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history` for time-series of one position.

**Use case:** See the complete SEC filing history of a person/fund in chronological order.

**Parameters:**
- `uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker, NOT a SEC-issued identifier. Lookup the UUID by CIK or name via `GET /api/v1/ownership/holders` (which has a `q` search parameter). UUIDs are stable across re-runs of the linker for the same `(cik, name)` cluster.

**Sample response:**
```json
{
  "holder": {
    "uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
    "name": "BERKSHIRE HATHAWAY INC",
    "cik": "0001067983",
    "type": "institution"
  },
  "history": [
    {
      "formType": "13D",
      "accessionNumber": "0001193125-26-001234",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000320193",
      "issuerTicker": "AAPL",
      "action": "Filed 13D at 5.84%"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

---

## Position Tracking

Unified position tracking across Form 4, 13F, and 13D/G with event-sourced ledger and point-in-time calculations.

### GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}

Calculate current ownership position for a holder in an issuer.

**Token cost:** 10 tokens per call

**Response fields:**
- `holderUuid` (string): Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping is correct.
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker.
- `currentShares` (number): Net shares held by this holder in this issuer as of `asOf`. Positive = long position; 0 = position fully exited (still returned for audit trail). Computed from the event-sourced ledger replay, NOT looked up from a single filing — combines 13F base + Form 4 deltas. Split-adjusted to most recent split for clean cross-time comparison.
- `currentPercent` (number (nullable)): Estimated `percent_of_class` when computable from the most recent 13D/13G assertion in the ledger replay. Null when only 13F + Form 4 sources contribute (since 13F doesn't carry percent-of-class — only an aggregate value). Below 5% positions typically have null `currentPercent` since they're not subject to 13D/G disclosure.
- `sourceFormTypes` (array): Array of form types that contributed to the ledger-replay calculation (e.g. `["13F-HR", "4", "4", "13D/A"]`). Order matches chronological replay order. Use to audit the position derivation and surface 'last-13D-was-N-quarters-ago' staleness signals to consumers.
- `asOf` (string): ISO-8601 UTC timestamp of the MOST RECENT filing contributing to the position calculation (i.e. the high-water-mark of the ledger replay). Echoes the `asOfDate` query parameter when one was passed; otherwise reflects the latest contributing filing's `filedAt`. Use to detect position staleness — if `asOf` is months old, the ledger has no fresh signal.
- `firstObservedAt` (string): ISO-8601 UTC timestamp of the EARLIEST filing contributing to the position. Useful for tenure metrics — `asOf - firstObservedAt` is roughly the holder's holding-period in this issuer. Berkshire's AAPL position has `firstObservedAt` around 2016-Q1 (when the 13F first surfaced the position).

**Since:** v3.1.0

**Utility:** Compute the current (or as-of-date) ownership position of a unified holder in an issuer by REPLAYING THE EVENT-SOURCED LEDGER: take the most recent 13D/13G or 13F assertion as the base position, then apply Form 4 transaction deltas chronologically forward to today. Solves the per-holder-per-issuer 'what's their current position?' question without forcing the customer to manually replay 30+ filings. Returns the source form types contributing to the calculation so you can audit the derivation. Pair with `/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history` for the time-series version of the same calculation. The right endpoint when you need a single-number answer like 'how many AAPL shares does Berkshire hold right now?'

**Use case:** Get point-in-time ownership estimate with confidence scoring.

**Parameters:**
- `holder_uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker. Lookup via `GET /api/v1/ownership/holders` with the `q` search parameter. UUIDs are stable across re-runs for the same `(cik, name)` cluster.
- `issuer_cik` (path, required): Issuer CIK (the company being held). Accepts both 10-char zero-padded form and unpadded. Returns 404 when no filings exist linking this holder to this issuer.
- `asOfDate` (query, optional): Compute position AS OF this date (ISO `YYYY-MM-DD`). Default is today. The ledger replays only filings with `filedAt <= asOfDate`. Useful for historical reconstruction — 'what was Berkshire's AAPL position on Q4 2024 close?' Returns same shape as today-calculation; does NOT mark-to-market the price.

**Sample response:**
```json
{
  "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "issuerCik": "0000320193",
  "issuerTicker": "AAPL",
  "currentShares": 905560000,
  "currentPercent": 5.84,
  "sourceFormTypes": [
    "13F",
    "13D"
  ],
  "asOf": "2026-04-15T20:14:32.000Z",
  "firstObservedAt": "2016-05-16T20:14:32.000Z"
}
```

### GET /api/v1/ownership/positions/{holder_uuid}/issuer/{issuer_cik}/history

Time series of position events for a holder-issuer pair.

**Token cost:** 10 tokens per call

**Response fields:**
- `holderUuid` (string): Holder UUID echoed back. Useful for asserting your client's holder-resolution mapping.
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `events` (array): Array of position events sorted by `eventDate ASC` (oldest first — chart-friendly ordering). Mixes transactional events (`sharesDelta` set) and assertion events (`sharesDelta` null, `postEventShares` is a snapshot value). Empty array when no events match the filters.
- `events[].eventDate` (string): ISO `YYYY-MM-DD` event date — for Form 4 this is the trade date; for 13F-HR it's the quarter-end (`period_of_report`); for 13D/G it's the filing's reported event date (which may pre-date `filedAt`). The chart x-axis.
- `events[].sourceFormType` (string): Canonical form type of the source filing — `4`, `13F-HR`, `13D`, `13G`, plus amendment variants. Use to color-code chart events (Form 4 = transaction dot, 13F = snapshot line, 13D = annotation marker).
- `events[].accessionNumber` (string): SEC accession number of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to the form-type-specific filing-detail endpoint to drill into the underlying filing.
- `events[].action` (string): Event action label — one of `"buy"`, `"sell"`, `"snapshot"`, `"13D filed"`, `"13G filed"`, `"13D amendment"`, etc. Use for chart-tooltip labels and timeline-row icons. `snapshot` is the canonical action for 13F quarterly assertions.
- `events[].sharesDelta` (number (nullable)): Share-count delta this event contributed to the running position. Positive = position increased (Form 4 buy); negative = position decreased (Form 4 sell). NULL for snapshot/assertion events (13F-HR, 13D, 13G) where the source filing reports a level rather than a delta — for those rows, only `postEventShares` is meaningful.
- `events[].postEventShares` (number): Cumulative position after this event was applied. For transactional events (`sharesDelta` set): `prior_position + sharesDelta`. For snapshot events (`sharesDelta` null): the AS-FILED level reported on the source filing (which becomes the new ledger baseline). Always non-negative.
- `events[].postEventPercent` (number (nullable)): Percent-of-class after this event when computable. Set on 13D/G assertion events (which carry `percent_of_class`). Null on Form 4 events (since Form 4 doesn't typically carry a percent reading) and on 13F events (since 13F doesn't carry percent — only an aggregate value).

**Since:** v3.1.0

**Utility:** The chart-ready time-series view of one holder's position in one issuer — every contributing event (Form 4 transaction, 13F quarterly snapshot, 13D/G filing) in chronological order with the post-event position. Drives the position-history chart on holder-detail pages and the 'show me how Berkshire's AAPL stake evolved over 8 years' workflow. Each event carries `sharesDelta` (for transactional events — buys/sells) OR a snapshot indicator (for assertion events — 13F quarter-ends, 13D filings). The right endpoint when you need the time-series (use `/positions/{holder_uuid}/issuer/{issuer_cik}` for the single-number current-state version of the same data).

**Use case:** Build ownership change timeline charts.

**Parameters:**
- `holder_uuid` (path, required): Unified holder UUID — internally generated by the Phase 31 holder-linker. Lookup via `GET /api/v1/ownership/holders` with the `q` search parameter. Stable across linker re-runs for the same `(cik, name)` cluster.
- `issuer_cik` (path, required): Issuer CIK (the company being held). Accepts both 10-char zero-padded and unpadded forms.
- `startDate` (query, optional): Inclusive lower bound on `eventDate`. Format ISO `YYYY-MM-DD`. Default: no lower bound (full history back to first observed event). Useful for narrowing chart x-axis to recent periods.
- `endDate` (query, optional): Inclusive upper bound on `eventDate`. Format ISO `YYYY-MM-DD`. Default: no upper bound (up to today).
- `sourceType` (query, optional): Filter to one source-form-type — `SC_13D`, `SC_13G`, `FORM_4`, or `FORM_13F`. Default returns all event types blended. Use `FORM_4` to see only the discrete buy/sell events; use `FORM_13F` to see only the quarterly snapshot points.

**Sample response:**
```json
{
  "holderUuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "issuerCik": "0000320193",
  "events": [
    {
      "eventDate": "2026-04-15",
      "sourceFormType": "13D",
      "accessionNumber": "0001193125-26-001234",
      "action": "13D filed",
      "sharesDelta": null,
      "postEventShares": 905560000,
      "postEventPercent": 5.84
    }
  ]
}
```

### GET /api/v1/ownership/positions/issuer/{issuer_cik}/holders

All holders of an issuer from position events, deduplicated via unified_holders.

**Token cost:** 5 tokens per call

**Response fields:**
- `issuer_cik` (string): Echoed issuer CIK in 10-character zero-padded form.
- `issuer_ticker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker.
- `as_of` (string): ISO-8601 UTC timestamp of the latest contributing event across all holders. Use to verify staleness (>30 days warrants a refresh during 13F filing windows).
- `holders` (array): Array of unified-holder rows for this issuer. Order: by `shares_held` DESC (largest holders first). Deduplicated via Phase 47 unified-holder layer — a fund that filed both 13F and 13D for the same position appears as ONE row, not two.
- `holders[].holder_uuid` (string): Phase 47 unified-holder UUID.
- `holders[].name` (string): Canonical holder name.
- `holders[].cik` (string (nullable)): Primary 10-char zero-padded holder CIK.
- `holders[].type` (string): Holder classification — `individual` / `institution` / `group`.
- `holders[].shares_held` (integer): Latest known share count for this holder. NOT split-adjusted server-side (preserves the as-filed view per Phase 52 redirect convention) — for split-adjusted aggregation queries use [GET /api/v1/tickers/{ticker}/fund-trends](/docs/company-data/ticker-research/get-tickers-ticker-fund-trends) instead.
- `holders[].percent_of_class` (number (nullable)): Latest known percent of class held (0.0-100.0 decimal). Null on Form-4-only holders where the underlying filing did not include a class-percentage calculation.
- `holders[].sources` (array): Array of source-flag strings indicating which SEC reporting regimes contributed to this position — e.g. `["13F"]` (13F filer only), `["13D", "13F"]` (filed both), `["Form 4"]` (Section 16 insider only). Multi-source positions are common for activist 13F filers who cross 5% (Buffett's BRK both files 13F and 13D for AAPL pre-2020).
- `holders[].last_event_at` (string): ISO-8601 UTC timestamp of the most-recent event affecting this position. The chronological sort key for 'recently active holders'.
- `meta` (object): Pagination block: `{ total: integer, limit: integer, offset: integer }`. `total` is the holder count for this issuer.

**Since:** v3.1.0

**Utility:** All holders of an issuer rolled up from the Phase 47 unified position-event ledger — combines 13F snapshots + 13D/13G filings + Form 4 insider holdings into one deduplicated holder list per issuer. Each row shows the latest position state for the (holder, issuer) pair, derived from the most-recent contributing event of any type. The single canonical 'who owns this stock?' rollup that spans all three SEC reporting regimes — institutional 13F filers, 5%+ beneficial owners (13D/G), and Section 16 insiders all in one list. Pair with [GET /api/v1/ownership/positions/issuer/{issuer_cik}/timeline](/docs/ownership-and-positions/unified-holders/get-ownership-positions-issuer-timeline) for the time-ordered event view.

**Use case:** WhaleWisdom-style institutional-ownership-breakdown pages — show all funds + insiders + beneficial owners holding AAPL today, sorted by share count or percent of class. Also useful for 'find all activist 13D filers in Berkshire's portfolio' workflows (filter `holders[].type=group` and the source-flag list to `[13D]`).

**Parameters:**
- `issuer_cik` (path, required): Issuer CIK (the company being analyzed). Both 10-character zero-padded (`0000320193`) and short unpadded (`320193`) formats accepted. Returns 404 when no positions have ever been observed for the issuer (rare; typically only pre-IPO entities or de-registered issuers).

**Sample response:**
```json
{
  "issuer_cik": "0000320193",
  "issuer_ticker": "AAPL",
  "as_of": "2026-04-15T20:14:32Z",
  "holders": [
    {
      "holder_uuid": "f0e1d2c3-b4a5-9876-5432-10fedcba9876",
      "name": "VANGUARD GROUP INC",
      "cik": "0000884144",
      "type": "institution",
      "shares_held": 1380000000,
      "percent_of_class": 8.85,
      "sources": [
        "13F"
      ],
      "last_event_at": "2026-02-14T18:52:10Z"
    },
    {
      "holder_uuid": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "name": "BLACKROCK INC",
      "cik": "0001364742",
      "type": "institution",
      "shares_held": 1100000000,
      "percent_of_class": 7.05,
      "sources": [
        "13F",
        "13G"
      ],
      "last_event_at": "2026-02-14T17:24:05Z"
    },
    {
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "name": "BERKSHIRE HATHAWAY INC",
      "cik": "0001067983",
      "type": "institution",
      "shares_held": 300000000,
      "percent_of_class": 1.92,
      "sources": [
        "13F"
      ],
      "last_event_at": "2026-02-14T16:12:48Z"
    }
  ],
  "meta": {
    "total": 4218,
    "limit": 50,
    "offset": 0
  }
}
```

### GET /api/v1/ownership/positions/issuer/{issuer_cik}/timeline

Chronological events across all holders for one issuer.

**Token cost:** 5 tokens per call

**Response fields:**
- `issuer_cik` (string): Echoed issuer CIK in 10-character zero-padded form.
- `issuer_ticker` (string (nullable)): Resolved issuer ticker (canonical hyphen form).
- `events` (array): Array of position-events in REVERSE chronological order (most-recent first). Mixes Form 4 transactions, 13F snapshot deltas, 13D/G filings into one sorted feed.
- `events[].event_id` (string): Unique event identifier — composite of `(holder_uuid, source, accession_number, line_number)`. Stable across re-runs of the unified position-event ledger build.
- `events[].event_at` (string): ISO-8601 UTC timestamp of the event. For Form 4: trade execution date (or filing-acceptance if trade date is missing). For 13F: quarter-end period_of_report. For 13D/G: signature date or filing date (whichever is earlier).
- `events[].source` (string): Source-type — `Form 4` / `13F` / `13D` / `13G` / `13D/A` / `13G/A`.
- `events[].holder_uuid` (string): Phase 47 unified-holder UUID of the party affecting the position.
- `events[].holder_name` (string): Holder name at the time of the event.
- `events[].action` (string): Human-readable action summary — `"BUY 50,000 shares @ $175.25"` (Form 4 P transaction), `"13G filed at 5.2%"` (13G), `"Position increased to 7.1%"` (13D-A), `"13F-HR: position held 245,000 shares"` (13F snapshot).
- `events[].shares_after` (integer (nullable)): Post-event share count for the (holder, issuer) position. Null on 13D/G events that did not include explicit share counts.
- `events[].percent_after` (number (nullable)): Post-event percent of class held. Null on Form-4-only events without a class-percentage calculation.
- `events[].accession_number` (string): SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format.
- `meta` (object): Pagination + filter echo: `{ total: integer, limit: integer, startDate: string|null, endDate: string|null, source: string|null }`.

**Since:** v3.1.0

**Utility:** Time-ordered event feed across ALL holders for one issuer — every contributing event from the unified position-event ledger (Form 4 transactions, 13F snapshots, 13D/G filings) in reverse chronological order, with the post-event position state. The natural backend for 'show me all ownership activity for AAPL in the last 30 days' dashboards. Pair with [GET /api/v1/ownership/positions/issuer/{issuer_cik}/holders](/docs/ownership-and-positions/unified-holders/get-ownership-positions-issuer-holders) for the holder-rollup view of the same data.

**Use case:** Monitor all ownership activity for a specific company in chronological order — useful for compliance review, news-driven activity analysis ('did anyone trim their position around the Q4 earnings miss?'), and activist-tracking workflows ('show me every 13D filing on this issuer in the last 90 days').

**Parameters:**
- `issuer_cik` (path, required): Issuer CIK. Both 10-character zero-padded (`0000320193`) and short unpadded (`320193`) formats accepted.
- `startDate` (query, optional): Start date filter (ISO 8601 date). Returns events with `event_at >= startDate`. Omit for the full available history (typically 5+ years for established issuers).
- `endDate` (query, optional): End date filter (ISO 8601 date, inclusive). Pair with `startDate` for date-range filtering.
- `source` (query, optional): Filter by source-type — `Form 4` / `13F` / `13D` / `13G`. Omit for all sources.
- `limit` (query, optional, default: 100): Max events returned (1-500). Server caps at 500.

**Sample response:**
```json
{
  "issuer_cik": "0000320193",
  "issuer_ticker": "AAPL",
  "events": [
    {
      "event_id": "evt_a1b2c3d4_0",
      "event_at": "2026-04-15T20:14:32Z",
      "source": "13D",
      "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
      "holder_name": "BERKSHIRE HATHAWAY INC",
      "action": "13D filed at 5.4% of class",
      "shares_after": 845000000,
      "percent_after": 5.42,
      "accession_number": "0001193125-26-001234"
    },
    {
      "event_id": "evt_e5f6g7h8_0",
      "event_at": "2026-03-31T00:00:00Z",
      "source": "13F",
      "holder_uuid": "f0e1d2c3-b4a5-9876-5432-10fedcba9876",
      "holder_name": "VANGUARD GROUP INC",
      "action": "13F-HR: position held 1,380,000,000 shares",
      "shares_after": 1380000000,
      "percent_after": 8.85,
      "accession_number": "0000884144-26-001892"
    },
    {
      "event_id": "evt_i9j0k1l2_0",
      "event_at": "2026-02-12T14:35:00Z",
      "source": "Form 4",
      "holder_uuid": "b3c4d5e6-7f80-9abc-def0-123456789abc",
      "holder_name": "COOK TIMOTHY D",
      "action": "SELL 50,000 shares @ $175.25",
      "shares_after": 3284621,
      "percent_after": null,
      "accession_number": "0000320193-26-000056"
    }
  ],
  "meta": {
    "total": 1247,
    "limit": 100,
    "startDate": null,
    "endDate": null,
    "source": null
  }
}
```

### GET /api/v1/ownership/cross-reference/{holder_uuid}

Cross-system filing reference for a unified holder.

**Token cost:** 5 tokens per call

**Response fields:**
- `holder_uuid` (string): Echoed UUID.
- `name` (string): Canonical holder name.
- `form_4` (array): Array of Form 3/4/5 (Section 16 insider) filings the holder has been a party to, sorted by `filed_at DESC`. Empty array on holders who have never filed Section 16. Each entry: `{ accession_number: string, filed_at: string, issuer_cik: string, issuer_ticker: string|null, action: string }`.
- `form_13f` (array): Array of 13F-HR/NT filings the holder has filed, sorted by `period_of_report DESC`. Empty array on holders who have never filed 13F. Each entry: `{ accession_number: string, filed_at: string, period_of_report: string, position_count: integer, total_aum_usd: number }`. `period_of_report` is the calendar quarter-end (always calendar-aligned per SEC mandate).
- `form_13dg` (array): Array of Schedule 13D / 13G / 13D-A / 13G-A filings the holder has filed, sorted by `filed_at DESC`. Empty array on holders who have never filed 13D/G. Each entry: `{ accession_number: string, filed_at: string, form_type: string, issuer_cik: string, issuer_ticker: string|null, percent_of_class: number|null, purpose: string|null }`.
- `summary` (object): Cross-source rollup metadata: `{ total_filings: integer, form_4_count: integer, form_13f_count: integer, form_13dg_count: integer, first_filing_at: string, last_filing_at: string, unique_issuers: integer }`. The `unique_issuers` count rolls up issuers across all three source-types — useful for sizing the holder's coverage breadth (Berkshire ~75 unique issuers, BlackRock ~12K).

**Since:** v3.1.0

**Utility:** Cross-source filing rollup grouped by source-type — for one unified holder, returns separate `form_4[]`, `form_13f[]`, and `form_13dg[]` arrays so consumers can render per-source-type drill-down panels (e.g. 'Berkshire's Form 4 history (Buffett's personal trades) here, 13F portfolio history there, 13D activist positions in a third panel'). Differs from [GET /api/v1/ownership/holders/{uuid}/filing-history](/docs/ownership-and-positions/unified-holders/get-ownership-holders-uuid-filing-history) which returns ONE merged chronological feed — use whichever shape is more natural for your UI.

**Use case:** Per-source-type drill-down panels on a holder profile page where the user wants to see Form 4 / 13F / 13D-G activity SEPARATELY (vs the merged-chronological feed from `/holders/{uuid}/filing-history`). Also useful for compliance audits that need 'show me ALL Section 16 filings from this entity, separately from their 13F/13D activity'.

**Parameters:**
- `holder_uuid` (path, required): Phase 47 unified-holder UUID. Look up via [GET /api/v1/ownership/holders](/docs/ownership-and-positions/unified-holders/get-ownership-holders). Returns 404 on unknown UUIDs.

**Sample response:**
```json
{
  "holder_uuid": "7f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "name": "BERKSHIRE HATHAWAY INC",
  "form_4": [],
  "form_13f": [
    {
      "accession_number": "0001067983-26-000037",
      "filed_at": "2026-02-14T16:12:48Z",
      "period_of_report": "2025-12-31",
      "position_count": 42,
      "total_aum_usd": 312485000000
    },
    {
      "accession_number": "0001067983-25-000189",
      "filed_at": "2025-11-14T17:03:21Z",
      "period_of_report": "2025-09-30",
      "position_count": 41,
      "total_aum_usd": 295712000000
    }
  ],
  "form_13dg": [
    {
      "accession_number": "0001193125-26-001234",
      "filed_at": "2026-04-15T20:14:32Z",
      "form_type": "SC 13D",
      "issuer_cik": "0000320193",
      "issuer_ticker": "AAPL",
      "percent_of_class": 5.42,
      "purpose": "Investment"
    }
  ],
  "summary": {
    "total_filings": 110,
    "form_4_count": 0,
    "form_13f_count": 102,
    "form_13dg_count": 8,
    "first_filing_at": "1999-11-15T17:00:00Z",
    "last_filing_at": "2026-04-15T20:14:32Z",
    "unique_issuers": 75
  }
}
```

---

## Ownership Analytics

Analytics endpoints for ownership concentration, threshold crossings, and activist tracking.

### GET /api/v1/ownership/analytics/ownership-concentration/{cik}

Ownership concentration metrics for an issuer.

**Token cost:** 10 tokens per call

**Response fields:**
- `issuerCik` (string): Issuer CIK echoed back in 10-char zero-padded form regardless of input.
- `issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when issuer has no public-equity ticker.
- `asOf` (string): ISO-8601 UTC timestamp of the most-recent filing contributing to the metrics computation. Concentration metrics are recomputed on the `sec_13f_summary` matview refresh cadence (~6 hours).
- `top5Percent` (number): Aggregate `percent_of_class` held by the top-5 holders by position size (sum, not mean). Above 30% indicates highly concentrated ownership; above 50% indicates float-constrained ownership where 5 funds effectively control the company. Tech mega-caps (AAPL, MSFT) typically sit at 22-28%; activist-held mid-caps can reach 40-60%.
- `top10Percent` (number): Aggregate `percent_of_class` held by the top-10 holders. The standard institutional-concentration metric (Sharpe, Damodaran). Values above 50% indicate the most-impactful 10 holders effectively control the float; below 30% indicates broad institutional dispersion.
- `top25Percent` (number): Aggregate `percent_of_class` held by the top-25 holders. The 'tail of the distribution' metric — gap between top10 and top25 indicates how concentrated the long tail is. Index-fund-heavy names (mega caps) have small gaps (top10 ~30%, top25 ~50%); activist-targeted names have larger gaps (concentrated top-5, dispersed long tail).
- `herfindahl` (number): Herfindahl-Hirschman Index (HHI) of holder concentration on a 0-10000 scale (sum of squared percent shares × 100). Below 1500 = unconcentrated (broad ownership); 1500-2500 = moderately concentrated; above 2500 = highly concentrated (FTC merger-review threshold). The single-number summary metric used in academic literature.
- `institutionalPercent` (number): Aggregate institutional ownership percentage — sum of all 13F-HR-reported positions normalized against shares outstanding. Mega-caps (AAPL, MSFT) typically 60-75%; small-caps 30-50%; closely-held names < 20%. The complement of retail-+-insider ownership.
- `insiderPercent` (number): Aggregate insider ownership percentage from Form 4 / Form 3 / Form 5 filings — the cumulative `total_beneficial_ownership` of all insiders normalized against shares outstanding. Founder-led companies (TSLA, META, SHOP) typically 5-25%; mature large-caps < 1%. High `insiderPercent` correlates with founder-CEO governance regimes.

**Since:** v3.0.0

**Utility:** Quantitative concentration metrics for one issuer's ownership structure: top-5 / top-10 / top-25 holder share, Herfindahl-Hirschman Index of holder concentration, and the institutional-vs-insider split. The right endpoint for screening on float-pressure thesis ('find issuers where >70% of float is held by ≤5 funds, then look for cluster buys at lower levels') and for assessing concentration risk in covered names. Pair with `/ownership/analytics/threshold-crossings` to surface the recent filings that drove changes in these metrics, and with `/ownership/beneficial-ownership/issuers/{cik}/summary` for the underlying holder list.

**Use case:** Assess ownership concentration risk, identify companies with highly concentrated ownership.

**Parameters:**
- `cik` (path, required): Issuer CIK (the company being analyzed). Accepts both 10-char zero-padded form (`0000320193`) and unpadded (`320193`). Returns 404 when no ownership filings (13F + 13D/G + Form 4) have ever surfaced this issuer.

**Sample response:**
```json
{
  "issuerCik": "0000320193",
  "issuerTicker": "AAPL",
  "asOf": "2026-05-01T20:55:12.000Z",
  "top5Percent": 22.4,
  "top10Percent": 31.7,
  "top25Percent": 48.3,
  "herfindahl": 412.6,
  "institutionalPercent": 61.8,
  "insiderPercent": 0.07
}
```

### GET /api/v1/ownership/analytics/threshold-crossings

Recent filings that crossed 5%, 10%, 15%, or 20% ownership thresholds.

**Token cost:** 10 tokens per call

**Response fields:**
- `crossings` (array): Array of threshold-crossing rows, sorted by `filedAt DESC` (most recent crossings first). Each row represents one threshold-crossing event by one filer at one issuer (a single filing that crosses multiple thresholds emits multiple rows — e.g. going from 4% to 11% emits both `5%` and `10%` rows). Empty array on no match.
- `crossings[].accessionNumber` (string): SEC accession of the filing that triggered the crossing. Pass to `/ownership/beneficial-ownership/filings/{accession}` for the full filing payload (purpose, intent flags, exhibits).
- `crossings[].filedAt` (string): ISO-8601 UTC timestamp of SEC EDGAR acceptance for the crossing-triggering filing. Use for time-bucketed crossing-rate analytics ('how many 10% crossings filed this quarter?').
- `crossings[].issuerCik` (string): Issuer CIK in 10-char zero-padded form. The company whose ownership threshold was crossed.
- `crossings[].issuerTicker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null only for private-issuer filings (rare; most threshold-crossings target public issuers).
- `crossings[].filerCik` (string): Filer CIK in 10-char zero-padded form. The entity that crossed the threshold. Pass to `/ownership/beneficial-ownership/filers/{cik}/portfolio` for the filer's full position book.
- `crossings[].filerName` (string): Filer name from the crossing filing (typically all-caps EDGAR convention). For activist crossings commonly surfaces names like `TRIAN FUND MANAGEMENT LP`, `STARBOARD VALUE LP`, `ELLIOTT INVESTMENT MANAGEMENT LP`.
- `crossings[].threshold` (integer): The threshold that was crossed — `5`, `10`, `15`, or `20`. A single filing can produce multiple rows in this response if it crossed multiple thresholds (e.g. accumulating from 4% to 11% → two rows: one for `5` and one for `10`).
- `crossings[].direction` (string): Crossing direction — literal `"up"` (accumulating: prior was below threshold, current is at-or-above) or `"down"` (reducing: prior was at-or-above, current is below). The actionable direction for surveillance is `"up"`.
- `crossings[].priorPercent` (number (nullable)): Filer's `percent_of_class` from the IMMEDIATELY-PRIOR filing (the last filing before this crossing-triggering one). Together with `currentPercent` defines the magnitude of the threshold crossing. Null on first-ever filings by this `(filer, issuer)` pair (i.e. fresh 5% accumulations from zero).
- `crossings[].currentPercent` (number): Filer's `percent_of_class` on the crossing-triggering filing. Always above the threshold for `direction='up'`; always below the threshold for `direction='down'`. Use `currentPercent - priorPercent` (when prior is not null) to compute crossing-event size.

**Since:** v3.0.0

**Utility:** Surfaces 13D/13G filings that crossed a beneficial-ownership threshold (5%, 10%, 15%, 20%) in either direction — the leading-indicator endpoint for material ownership-buildup or position-trim events. Computed via amendment-chain analysis: comparing each filing's `percentOfClass` against the prior filing by the same `(filer, issuer)` pair and emitting a row whenever the crossing occurs. Filterable by issuer ticker, specific threshold level, direction (`up` = accumulating; `down` = reducing), and date range. The 5% threshold is the SEC trigger; 10% triggers Section 16 short-swing-profit rules and is a common activist threshold; 15% (added v3.7.3) is a finer-grained activist-watching level; 20% is the often-used 'control-position' threshold. The right endpoint for compliance teams monitoring control-block accumulation and for analysts tracking activist position-building campaigns.

**Use case:** Monitor for large ownership buildups/reductions, detect threshold trigger events, filter by crossing direction.

**Parameters:**
- `issuerTicker` (query, optional): Issuer ticker filter, case-insensitive (server normalizes to canonical hyphen form). Returns only crossings against this specific issuer. Useful for company-overview pages: 'has anyone crossed 5% in this name recently?'
- `threshold` (query, optional): Specific threshold to filter on — `5`, `10`, `15`, or `20`. Default: returns crossings of any threshold. The `15` threshold was added in v3.7.3; pre-v3.7.3 only `5`, `10`, `20` were detected.
- `direction` (query, optional): Crossing direction filter — `up` (accumulating: prior < threshold ≤ current) or `down` (reducing: prior ≥ threshold > current). Default: returns both directions blended. `up` crossings are the more actionable surveillance target.
- `dateFrom` (query, optional): Inclusive lower bound on `filedAt` (the date of the crossing-triggering filing). Format ISO `YYYY-MM-DD`. Use for incremental polling: `dateFrom = last_run_timestamp`.
- `dateTo` (query, optional): Inclusive upper bound on `filedAt` (added v3.7.3). Format ISO `YYYY-MM-DD`. Combine with `dateFrom` for closed ranges.
- `page` (query, optional, default: 1): 1-based page number. Crossings are a moderate-density subset of 13D/G filings — even broad date ranges typically fit on 5-20 pages.
- `size` (query, optional, default: 50): Page size, capped at 200 server-side. For full-corpus enumeration use date-range chunking + `size=200`.

**Sample response:**
```json
{
  "crossings": [
    {
      "accessionNumber": "0001193125-26-001999",
      "filedAt": "2026-04-15T20:14:32.000Z",
      "issuerCik": "0000051143",
      "issuerTicker": "IBM",
      "filerCik": "0001637207",
      "filerName": "TRIAN FUND MANAGEMENT LP",
      "threshold": 5,
      "direction": "up",
      "priorPercent": 4.12,
      "currentPercent": 6.2
    }
  ]
}
```

---

## Company Financials (XBRL)

Standardized financial data from SEC EDGAR XBRL filings. Covers ~7,000+ publicly traded companies with quarterly/annual income statement, balance sheet, cash flow metrics, and 29 derived financial ratios. Data sourced from SEC companyfacts bulk download, updated daily.

### GET /api/v1/financials/metrics

Get standardized financial metrics for a company over time.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): Company name as registered with SEC (typically Title Case from EDGAR's company-tickers.json — NOT the all-caps EDGAR-doc-header convention). Use for human-readable financial-table headers.
- `data.ticker` (string): Issuer ticker echoed back in canonical hyphen form. Useful for asserting your client passed the ticker you intended after server-side normalization.
- `data.period_type` (string): Echoed back: `Q` (quarterly) or `Y` (annual). Quarterly rows are 10-Q derived (with the fiscal-Q4 row backfilled from the 10-K minus first three quarters); annual rows are 10-K derived directly.
- `data.data[]` (array): Array of period rows, sorted by `period_end DESC` (most recent first). Empty array on tickers without parsed XBRL data — gate via `/api/v1/financials/tickers` first if you're not sure of coverage.
- `data.data[].period_end` (string): ISO `YYYY-MM-DD` fiscal-period-end date. NOT calendar-quarter-aligned for non-calendar issuers — AAPL Q4 2025 ends `2025-09-27` (final Saturday of Sep 2025), not 2025-09-30. Use this field for chart x-axes and time-series joins.
- `data.data[].revenue` (number (nullable)): Revenue (USD). Concept: `us-gaap:Revenues` or `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` (post-ASC 606). DURATION fact (sum across the fiscal period). For TTM, sum the last 4 quarterly rows. Null when issuer hasn't filed for the period yet (most-recent quarter during 45-day filing window) or when revenue concept isn't tagged in the source XBRL.
- `data.data[].cost_of_revenue` (number (nullable)): Cost of revenue / cost of goods sold (USD). Concept: `us-gaap:CostOfRevenue` or `us-gaap:CostOfGoodsAndServicesSold`. DURATION fact. Null for non-COGS business models (banks, insurers, asset managers — interpret null as 'not applicable to this issuer's structure', not 'missing data').
- `data.data[].gross_profit` (number (nullable)): Gross profit (USD). Concept: `us-gaap:GrossProfit`. DURATION fact. Computed as `revenue - cost_of_revenue` when both are available. Null when either input is null. Combine with `revenue` for gross-margin calculation.
- `data.data[].operating_income` (number (nullable)): Operating income / EBIT (USD). Concept: `us-gaap:OperatingIncomeLoss`. DURATION fact. Negative for operating-loss companies (tech-growth, biotech). Null when issuer doesn't tag the concept (uncommon).
- `data.data[].net_income` (number (nullable)): Net income attributable to common stockholders (USD). Concept: `us-gaap:NetIncomeLoss`. DURATION fact. Negative for loss-makers. For TTM, sum the last 4 quarterly rows.
- `data.data[].eps_basic` (number (nullable)): Basic earnings per share (USD per share). Concept: `us-gaap:EarningsPerShareBasic`. DURATION fact. Negative for loss-makers. NOT split-adjusted server-side — corresponds to as-filed share count for the period; for split-adjusted historical EPS use `/api/v1/tickers/{ticker}/overview`.
- `data.data[].eps_diluted` (number (nullable)): Diluted earnings per share (USD per share). Concept: `us-gaap:EarningsPerShareDiluted`. DURATION fact. Includes dilutive effect of options, RSUs, convertibles. NOT split-adjusted server-side.
- `data.data[].shares_outstanding` (number (nullable)): Weighted-average diluted shares outstanding for the period (NOT a point-in-time count). Concept: `us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding`. Use for back-computing market cap × period-EPS rather than for current shares-outstanding. NOT split-adjusted.
- `data.data[].total_assets` (number (nullable)): Total assets (USD). Concept: `us-gaap:Assets`. INSTANT fact — point-in-time at `period_end`. For balance-sheet ratios use this directly; for averaged denominators (e.g. ROA) average current and prior period.
- `data.data[].total_equity` (number (nullable)): Total stockholders' equity (USD). Concept: `us-gaap:StockholdersEquity`. INSTANT fact — point-in-time at `period_end`. Negative for issuers with accumulated deficit > paid-in capital (common in early-stage tech/biotech and aggressive-buyback names like MMM, MCD, SBUX). Null when issuer doesn't tag the concept.
- `data.data[].total_debt` (number (nullable)): Total debt (short-term + long-term) (USD). Computed sum across `us-gaap:LongTermDebt` + `us-gaap:ShortTermBorrowings` + `us-gaap:CommercialPaper` etc. INSTANT fact at `period_end`. For debt-to-equity/coverage ratios use this directly.
- `data.data[].cash_and_equivalents` (number (nullable)): Cash and cash equivalents (USD). Concept: `us-gaap:CashAndCashEquivalentsAtCarryingValue`. INSTANT fact at `period_end`. Excludes marketable securities; for total-liquidity use `cash_and_short_term_investments` if surfaced. Combine with `total_debt` for net-debt computation.
- `data.data[].operating_cash_flow` (number (nullable)): Cash flow from operations (USD). Concept: `us-gaap:NetCashProvidedByUsedInOperatingActivities`. DURATION fact (period total). For TTM, sum last 4 quarters. Negative for cash-burning growth companies.
- `data.data[].capex` (number (nullable)): Capital expenditures (USD, NEGATIVE convention — cash outflow). Concept: `us-gaap:PaymentsToAcquirePropertyPlantAndEquipment`. DURATION fact. Reported as negative (cash outflow); use absolute value for capex-to-revenue ratios.
- `data.data[].free_cash_flow` (number (nullable)): Free cash flow (USD). Computed as `operating_cash_flow + capex` (capex is negative, so this subtracts capex magnitude). DURATION fact (period total). The canonical Buffett-style cash-quality metric. Negative for FCF-burning growth companies (recent IPOs, hyper-growth tech).

**Since:** v3.4.0

**Utility:** Retrieve income statement, balance sheet, and cash flow data in quarterly or annual series.

**Use case:** Building financial data tables, charting revenue/earnings trends, comparing financial performance across periods.

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (e.g., AAPL). Canonical hyphen form (`BRK-A`); server normalizes `BRK.A`/`BRK/A`/`BRKA` → `BRK-A`. Returns 404 if no XBRL coverage — gate via `/api/v1/financials/tickers` for the ~7,000-ticker covered universe.
- `period` (query, optional, default: Q): Period type: `Q` (quarterly) returns one row per fiscal quarter; `Y` (annual) returns one row per fiscal year (10-K-anchored, fiscal-year-end-aware so non-calendar issuers like AAPL/September-end and ORCL/May-end report against their actual fiscal year boundaries — NOT calendar).
- `years` (query, optional, default: 5): Number of years of history (1-20). Quarterly returns up to `years × 4` rows; annual up to `years` rows. FinRadar's XBRL ETL coverage starts ~2013 for most issuers, ~2009 for large-caps that filed early-XBRL voluntarily.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "period_type": "Q",
    "data": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "revenue": 94930000000,
        "cost_of_revenue": 51260000000,
        "gross_profit": 43670000000,
        "operating_income": 29610000000,
        "net_income": 24470000000,
        "eps_basic": 1.65,
        "eps_diluted": 1.64,
        "shares_outstanding": 14840000000,
        "total_assets": 364980000000,
        "total_equity": 56950000000,
        "total_debt": 101700000000,
        "cash_and_equivalents": 28160000000,
        "operating_cash_flow": 26810000000,
        "capex": -3130000000,
        "free_cash_flow": 23680000000
      }
    ],
    "note": "Use /ratios endpoint for calculated financial ratios"
  }
}
```

### GET /api/v1/financials/ratios

Get derived financial ratios (margins, returns, growth, leverage) over time.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.period_type` (string): Echoed back: `Q`, `Y`, or `TTM`. TTM rows are computed by summing the most-recent 4 quarterly DURATION facts (revenue, net_income, OCF, capex) and using the latest INSTANT fact for balance-sheet denominators.
- `data.category` (string): Echoed-back filter: `profitability` / `leverage` / `liquidity` / `efficiency` / `per_share` / `runway` / `growth` / `all`. When `all` is selected, every ratio in the response carries the same shape regardless of category.
- `data.data[]` (array): Array of period rows, sorted by `period_end DESC` (most recent first). Empty array on tickers without parsed XBRL data.
- `data.data[].period_end` (string): ISO `YYYY-MM-DD` fiscal-period-end date. NOT calendar-aligned for non-calendar fiscal years.
- `data.data[].gross_margin` (number (nullable)): Gross margin (UNIT: ratio, decimal — `0.473` = 47.3%). Computed as `gross_profit / revenue`. Null when either input is null. Profitability category.
- `data.data[].operating_margin` (number (nullable)): Operating margin (decimal). `operating_income / revenue`. Negative for operating-loss companies. Profitability category.
- `data.data[].net_margin` (number (nullable)): Net margin (decimal). `net_income / revenue`. Negative for loss-makers. Profitability category.
- `data.data[].roe` (number (nullable)): Return on Equity (decimal). For TTM uses AVERAGED denominator: `ttm_net_income / avg_book_equity` (per the v3.7.2 DO-parity fix — non-averaged denominators inflate ROE on rapidly-changing equity). Null when book equity is negative or one of the inputs is missing. Profitability category.
- `data.data[].roa` (number (nullable)): Return on Assets (decimal). `ttm_net_income / avg_total_assets` (averaged denominator for TTM). Profitability category.
- `data.data[].roic` (number (nullable)): Return on Invested Capital (decimal). v3.5.0 DO-parity formula: `ttm_nopat / (avg_equity + avg_total_debt - avg_cash)` where `nopat = ebit × (1 - 0.25 fixed tax)`. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15. Profitability category.
- `data.data[].debt_to_equity` (number (nullable)): Total debt / book equity (ratio). INSTANT-on-INSTANT (point-in-time at period_end). Null when equity is zero or negative. Below 0.5 = conservative; above 2.0 = leveraged. Leverage category.
- `data.data[].current_ratio` (number (nullable)): Current assets / current liabilities (ratio). Liquidity category. Below 1.0 indicates short-term-funding gap (note: AAPL routinely runs <1.0 with no liquidity issue — interpret in context). Liquidity category.
- `data.data[].quick_ratio` (number (nullable)): (Current assets - inventory) / current liabilities (ratio). Strict-liquidity test excluding inventory. Liquidity category.
- `data.data[].eps_diluted_ttm` (number (nullable)): Trailing-twelve-month diluted EPS (USD per share). Sum of last 4 quarterly `eps_diluted` values. NOT split-adjusted server-side — for split-adjusted EPS history use `/api/v1/tickers/{ticker}/overview`. Per-share category.
- `data.data[].book_value_per_share` (number (nullable)): Book value per share (USD). `total_equity / shares_outstanding`. Negative for issuers with negative book equity. Per-share category.
- `data.data[].free_cash_flow_per_share` (number (nullable)): TTM Free Cash Flow per share (USD). `ttm_free_cash_flow / shares_outstanding`. Negative for FCF-burning companies. Per-share category.
- `data.data[].revenue_growth_yoy` (number (nullable)): Year-over-year revenue growth (decimal — `0.061` = 6.1% growth). Computed as `(period_revenue / prior_year_same_period_revenue) - 1`. Null on the first year of coverage (no prior baseline). Growth category.
- `data.data[].eps_growth_yoy` (number (nullable)): Year-over-year diluted EPS growth (decimal). Same formula shape as revenue_growth_yoy. Negative when EPS shrank YoY. Null when prior-year EPS is zero/negative (division undefined). Growth category.
- `data.data[].cash_runway_status` (string (nullable)): Tiered cash-runway label (added v3.6.0). Values: `cash_generating` (FCF-positive, no runway concept), `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens. Runway category.

**Since:** v3.4.0

**Utility:** Retrieve calculated financial ratios separated from raw metrics.

**Use case:** Trend analysis of profitability, leverage, liquidity, and growth metrics. Filter by ratio category.

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 on tickers without XBRL coverage; gate via `/api/v1/financials/tickers`.
- `period` (query, optional, default: Q): Period type: `Q` (quarterly point-in-time ratios), `Y` (annual), or `TTM` (trailing-twelve-month rolling — most useful for cross-issuer comparison since it smooths quarterly seasonality). For most fundamental-screener UIs, default to `TTM`.
- `years` (query, optional, default: 5): Years of history (1-20). With `period=Q` returns up to `years × 4` rows; with `period=Y` or `period=TTM` returns up to `years` rows. TTM rolls the 4-quarter window forward by one quarter per row.
- `category` (query, optional, default: all): Filter to one ratio category: `profitability` (margins + ROE/ROA/ROIC), `leverage` (debt-to-equity, interest coverage), `liquidity` (current/quick ratios), `efficiency` (asset/inventory turnover), `per_share` (EPS, BVPS, FCFPS), `runway` (cash-runway-status tier), `growth` (YoY/QoQ revenue + EPS), or `all` (everything). Use `category=profitability` for margin-trend charts; `category=leverage` for credit-risk dashboards.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "period_type": "TTM",
    "category": "all",
    "data": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "gross_margin": 0.473,
        "operating_margin": 0.319,
        "net_margin": 0.27,
        "roe": 1.455,
        "roa": 0.323,
        "roic": 0.498,
        "debt_to_equity": 1.785,
        "current_ratio": 0.974,
        "quick_ratio": 0.825,
        "eps_diluted_ttm": 7.14,
        "book_value_per_share": 3.84,
        "free_cash_flow_per_share": 6.62,
        "revenue_growth_yoy": 0.061,
        "eps_growth_yoy": 0.103,
        "cash_runway_status": "cash_generating"
      }
    ]
  }
}
```

### GET /api/v1/financials/snapshot

Get snapshot with all metrics and ratios grouped by category. Supports TTM (default) or latest quarter.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`). Useful as join key against the SEC ownership endpoints (13D/G/F surface) and Insider Form 4 transactions.
- `data.period` (string): Echoed back: `TTM` or `Q`.
- `data.period_end` (string): ISO `YYYY-MM-DD` fiscal-period-end date for the most-recent fiscal quarter (the right boundary of the TTM window when `period=TTM`). Non-calendar fiscal-year-end-aware.
- `data.sector` (string (nullable)): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when ticker is unmapped in Sharadar (private CUSIPs, recent IPOs, 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.cash_runway_status` (string (nullable)): Tiered cash-runway label. Values: `cash_generating` (FCF-positive — no runway concept), `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Surfaced at top-level for company-overview-card prominence.
- `data.metrics` (object): Income-statement + balance-sheet + cash-flow primitives — TTM totals (sum of last 4 quarterly DURATION facts) for income/cash-flow items; INSTANT (point-in-time at `period_end`) for balance-sheet items. Includes: `revenue`, `net_income`, `operating_income`, `free_cash_flow`, `total_assets`, `total_equity`, `total_debt`, `cash_and_equivalents`, `shares_outstanding`. All USD. See [/financials/metrics](/docs/company-data/company-financials-xbrl/get-financials-metrics) for full per-period time series.
- `data.ratios` (object): Derived ratios grouped by category. Sub-objects: `profitability` (gross/operating/net margins + ROE/ROA/ROIC), `leverage` (debt-to-equity, debt-to-assets, interest_coverage), `liquidity` (current/quick ratios), `per_share` (eps_diluted_ttm, book_value_per_share, free_cash_flow_per_share), `growth` (revenue_growth_yoy, eps_growth_yoy). All ratios are decimals (`0.473` = 47.3%). Per-share metrics are USD/share. NOT split-adjusted server-side.
- `data.ratios.profitability` (object): Profitability sub-object: `gross_margin`, `operating_margin`, `net_margin` (each = matching DURATION-on-DURATION ratio), `roe`, `roa`, `roic` (each computed with AVERAGED balance-sheet denominators per v3.7.2 DO-parity fix). Decimal values.
- `data.ratios.leverage` (object): Leverage sub-object: `debt_to_equity`, `debt_to_assets` (both INSTANT-on-INSTANT at `period_end`), `interest_coverage` (TTM EBIT / TTM interest expense — null when interest expense is zero). Decimals.
- `data.ratios.liquidity` (object): Liquidity sub-object: `current_ratio` (current assets / current liabilities), `quick_ratio` ((current assets - inventory) / current liabilities). Both INSTANT-on-INSTANT. AAPL routinely runs current_ratio < 1.0 with no liquidity issue — interpret in context (mature large-caps with negative working-capital cycles can run sub-1.0 indefinitely).
- `data.ratios.per_share` (object): Per-share sub-object (USD/share): `eps_diluted_ttm` (sum of last 4 quarters' diluted EPS), `book_value_per_share` (total_equity / shares_outstanding), `free_cash_flow_per_share` (TTM FCF / shares_outstanding). NOT split-adjusted server-side — for split-adjusted historical view use [/api/v1/tickers/{ticker}/overview](/docs/company-data/ticker-research/get-tickers-ticker-overview).
- `data.ratios.growth` (object): Growth sub-object (decimals): `revenue_growth_yoy` (YoY revenue growth = `(current_period_rev / prior_year_same_period_rev) - 1`), `eps_growth_yoy` (same shape on diluted EPS). Null when prior-year baseline is zero/negative (division undefined).

**Since:** v3.4.0

**Utility:** Single-call summary of a company's current financial position.

**Use case:** Company overview cards, financial health dashboards, screening criteria.

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 on tickers without XBRL coverage; gate via `/api/v1/financials/tickers`.
- `period` (query, optional, default: TTM): Period basis: `TTM` (trailing-twelve-month rolling — default; smooths quarterly seasonality, comparable across issuers) or `Q` (latest quarterly point-in-time — useful when you specifically want the most-recent fiscal quarter's results, not a smoothed view). For company-overview cards default to `TTM`; for earnings-watch dashboards use `Q`.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "cik": "0000320193",
    "period": "TTM",
    "period_end": "2025-09-27",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "cash_runway_status": "cash_generating",
    "metrics": {
      "revenue": 401450000000,
      "net_income": 105320000000,
      "operating_income": 128190000000,
      "free_cash_flow": 105820000000,
      "total_assets": 364980000000,
      "total_equity": 56950000000,
      "total_debt": 101700000000,
      "cash_and_equivalents": 28160000000,
      "shares_outstanding": 14840000000
    },
    "ratios": {
      "profitability": {
        "gross_margin": 0.473,
        "operating_margin": 0.319,
        "net_margin": 0.27,
        "roe": 1.455,
        "roa": 0.323,
        "roic": 0.498
      },
      "leverage": {
        "debt_to_equity": 1.785,
        "debt_to_assets": 0.279,
        "interest_coverage": 28.4
      },
      "liquidity": {
        "current_ratio": 0.974,
        "quick_ratio": 0.825
      },
      "per_share": {
        "eps_diluted_ttm": 7.1,
        "book_value_per_share": 3.84,
        "free_cash_flow_per_share": 7.13
      },
      "growth": {
        "revenue_growth_yoy": 0.061,
        "eps_growth_yoy": 0.103
      }
    }
  }
}
```

### GET /api/v1/financials/tickers

Search or list companies with financial data available.

**Token cost:** 10 tokens per call

**Response fields:**
- `tickers` (array): Array of matching tickers, sorted by `fact_count DESC` (data-richest tickers first) when `q` is empty, OR by exact-match relevance + `fact_count DESC` when `q` is provided. Empty array on no match.
- `tickers[].ticker` (string): Canonical ticker (hyphen form). Use as input to `/financials/metrics`, `/financials/snapshot`, `/financials/ratios` etc. Multi-class issuers preserve the requested class.
- `tickers[].cik` (string): Issuer CIK in 10-char zero-padded form. Useful as join key against the SEC ownership endpoints (13D/G/F surface).
- `tickers[].company_name` (string): Company name from EDGAR's company-tickers.json file (typically Title Case — NOT all-caps EDGAR convention because this comes from the SEC's curated list). Use for human-readable autocomplete labels.
- `tickers[].latest_period_end` (string (nullable)): ISO `YYYY-MM-DD` end-date of the most-recent fiscal period for which we have parsed XBRL facts. Null only for tickers that have CIK but no XBRL data yet (rare; mostly very recent IPOs). Use to detect filing-staleness — values older than ~6 months on an active filer indicate either delayed XBRL parsing or an actual 10-K/10-Q skip.
- `tickers[].fact_count` (integer): Total parsed XBRL facts across all quarters for this ticker. Mature large-caps: 8000-20000 (multi-decade history × 1500 facts per filing). Small-caps: 500-3000. Recent IPOs: 100-500. Use as a data-richness gauge.
- `tickers[].sector` (string (nullable)): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when the ticker is unmapped in Sharadar (private CUSIPs, recently-listed issuers, foreign issuers without ADRs). Useful for sector-filtered autocomplete.
- `tickers[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar.
- `meta` (object): Result metadata block: `{ total: integer, limit: integer }`. `total` reflects full-corpus match count for the search; `limit` is the effective server-side-capped limit.

**Since:** v3.4.0

**Utility:** Discovery + autocomplete endpoint for the XBRL company-financials universe — lists tickers for which FinRadar has parsed and standardized at least one quarter of SEC company-facts data (~7,000+ companies, sourced from EDGAR's XBRL companyfacts daily bulk download). Use as the gating layer for financial-screener UIs: query this first to know which tickers can be queried via `/financials/metrics`, `/financials/snapshot`, `/financials/ratios`. Returns the latest available period plus total parsed fact count per ticker — useful for surfacing data-completeness signals (a ticker with only 200 facts is a recent-IPO with thin history; one with 12,000+ has a full multi-decade book). Sharadar sector/industry classifications are joined-in to support sector-specific autocomplete filters.

**Use case:** Building ticker search/autocomplete UI for the financials page.

**Parameters:**
- `q` (query, optional): Free-text search across (1) ticker (exact match boost) and (2) company name (partial match `ILIKE '%name%'`). Case-insensitive. Empty `q` returns the full list ordered by `fact_count DESC` (most-data-rich tickers first) — useful for default-state autocomplete dropdowns.
- `limit` (query, optional, default: 50): Maximum tickers returned (capped at 200 server-side). For typical autocomplete dropdowns, 10-20 is enough; for full-list preload (all 7000 tickers for offline indexing) use 200 + paginated walks.

**Sample response:**
```json
{
  "tickers": [
    {
      "ticker": "AAPL",
      "cik": "0000320193",
      "company_name": "APPLE INC",
      "latest_period_end": "2025-09-28",
      "fact_count": 12480,
      "sector": "Technology",
      "industry": "Consumer Electronics"
    }
  ],
  "meta": {
    "total": 7000,
    "limit": 100
  }
}
```

### GET /api/v1/financials/changes

Get recently updated companies (filing changes detected).

**Token cost:** 5 tokens per call

**Response fields:**
- `data.since` (string): ISO-8601 UTC timestamp echoed back — the lower-bound used for the query (defaults to 7 days ago when not specified).
- `data.count` (integer): Total number of tickers updated since `since`. May exceed `limit` (response is capped at `limit` rows; `count` reflects the full match set).
- `data.tickers[]` (array): Array of changed-ticker rows, sorted by `last_updated_at DESC` (most-recently-updated first). Empty array when no XBRL data has been loaded since `since`.
- `data.tickers[].ticker` (string): Issuer ticker (canonical hyphen form). Pass to `/api/v1/financials/changes/{ticker}` for per-ticker change details (which periods + which metrics).
- `data.tickers[].cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`).
- `data.tickers[].company_name` (string): Company name from EDGAR's company-tickers.json.
- `data.tickers[].last_updated_at` (string): ISO-8601 UTC timestamp of when FinRadar's XBRL ETL last loaded data for this ticker (NOT the SEC filing time — that's earlier; the gap reflects the daily company-facts ETL cadence + Phase 49+ standardization step). Use as the `since` cursor for incremental polling.
- `data.tickers[].periods_updated` (array): Array of fiscal periods (`YYYYQq` format like `2025Q4` for quarterly, `2024Y` for annual) that received new or updated metrics in this load. Most loads update one period (the freshly-filed quarter); restatements update multiple historical periods.
- `data.tickers[].metrics_count` (integer): Total count of standardized metrics affected across `periods_updated`. Typical 10-Q load: 30-40 metrics; 10-K load: 40-60; restatement: variable.
- `data.tickers[].trigger` (string (nullable)): Human-readable cause of the update. Values: `10-Q filing`, `10-K filing`, `8-K/A restatement`, `XBRL re-parse`, `Backfill load`. Null when the trigger isn't classifiable (rare).
- `data.tickers[].latest_period_end` (string): ISO `YYYY-MM-DD` end-date of the most-recent fiscal period now available for this ticker. Useful for staleness detection (compare against today's date).

**Since:** v3.4.0

**Utility:** Track which companies had new XBRL data loaded.

**Use case:** Delta feeds for downstream consumers, monitoring data freshness.

**Parameters:**
- `since` (query, optional, default: 7d-ago): ISO-8601 UTC timestamp lower-bound on `last_updated_at`. Default = 7 days ago. Pass the most-recent `last_updated_at` from your last poll to receive only newly-updated tickers (incremental delta-feed pattern).
- `limit` (query, optional, default: 50): Maximum tickers returned (capped at 200 server-side). For typical delta-feed cadence (every 6-24 hours) 50-100 is plenty; for rare large-batch backfill catch-ups use 200 + paginated walks.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "since": "2026-04-25T00:00:00Z",
    "count": 48,
    "tickers": [
      {
        "ticker": "AAPL",
        "cik": "0000320193",
        "company_name": "APPLE INC",
        "last_updated_at": "2026-04-30T01:42:13Z",
        "periods_updated": [
          "2025Q4"
        ],
        "metrics_count": 36,
        "trigger": "10-Q filing",
        "latest_period_end": "2025-09-27"
      },
      {
        "ticker": "MSFT",
        "cik": "0000789019",
        "company_name": "MICROSOFT CORP",
        "last_updated_at": "2026-04-29T08:14:50Z",
        "periods_updated": [
          "2026Q1"
        ],
        "metrics_count": 38,
        "trigger": "10-Q filing",
        "latest_period_end": "2025-12-31"
      }
    ]
  }
}
```

### GET /api/v1/financials/screen

Screen stocks by financial ratio criteria. Supports greater-than and less-than filters on 20+ financial metrics.

**Token cost:** 10 tokens per call

**Response fields:**
- `rows` (array): Array of screen-result rows — each ticker that satisfies ALL filters (AND-combined). Sorted by ticker alphabetically by default; pass `sort_by` parameter to sort by ratio (e.g. `sort_by=roe&sort_order=desc` for ROE-ranked output). Empty array on overly-narrow filter combinations.
- `rows[].ticker` (string): Issuer ticker (canonical hyphen form). Pass to `/financials/snapshot` or `/financials/metrics` for per-ticker drill-downs.
- `rows[].company_name` (string): Company name from EDGAR's company-tickers.json (typically Title Case). Use for human-readable labels in screener UIs.
- `rows[].pe_ratio` (number (nullable)): TTM (trailing 12 months) Price / Earnings ratio. Computed as `current_price / ttm_eps_diluted`. Null when EPS is negative (earnings-loss companies) — interpret null as 'P/E undefined for loss-makers'. Use `pe_lt=20` to filter to value names; combine with `pe_gt=0` to exclude loss-makers.
- `rows[].pb_ratio` (number (nullable)): TTM Price / Book ratio. Computed as `current_price / book_value_per_share`. Null when book value is negative (rare; some heavily-distressed companies). `pb_lt=1` is the classic deep-value Graham filter; `pb_gt=10` typical for high-quality compounders.
- `rows[].roe` (number (nullable)): TTM Return on Equity, computed using AVERAGED denominator (`ttm_net_income / avg_book_equity`) per the v3.7.2 DO-parity fix. Decimal value (`0.15` = 15%). Null when book equity is negative or when one of the inputs is missing. ROE > 0.20 indicates high-quality compounder territory.
- `rows[].roic` (number (nullable)): TTM Return on Invested Capital using the v3.5.0 DO-formula (`ttm_nopat / (avg_equity + avg_total_debt - avg_cash)`, with NOPAT = EBIT × (1 - 0.25 fixed tax)). Decimal value. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15.
- `rows[].ebitda_margin` (number (nullable)): TTM EBITDA / TTM Revenue. Decimal value (`0.30` = 30% margin). Null when revenue is zero or near-zero (rare). Useful for capital-intensity / scale-quality screens — software companies typically 25-40%; commodity producers 10-20%.
- `rows[].debt_to_equity` (number (nullable)): Total debt (short + long) / book equity, point-in-time at the latest fiscal-period end. Null when book equity is negative or zero. Below 0.5 indicates conservative balance sheet; above 2.0 indicates leveraged. Banks and insurers are excluded from typical screens (their structural leverage skews comparison).
- `rows[].cash_runway_status` (string (nullable)): Tiered cash-runway label (added v3.6.0): `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Null for profitable companies (no runway concept). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens.
- `rows[].sector` (string (nullable)): Sharadar sector classification. Null when ticker is unmapped in Sharadar. Pre-filter screens with `sector` parameter to avoid sector-bias in cross-industry-incomparable ratios (e.g. ROE comparisons across Banks vs Tech).
- `rows[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Em-dash characters preserved verbatim from Sharadar.
- `meta` (object): Result metadata: `{ total: integer, applied_filters: array<string>, ... }`. `applied_filters` echoes the parsed `_gt`/`_lt` filters as human-readable strings (e.g. `["roe > 0.15", "debt_to_equity < 1.0"]`) — useful for dashboards rendering 'currently filtered by:' breadcrumbs.

**Since:** v3.5.0

**Utility:** The XBRL-driven stock screener — filter the ~7,000-company financials universe by 20+ derived ratio criteria (profitability, leverage, liquidity, efficiency, growth) using composable greater-than / less-than filters. Built on the same standardized XBRL ratio engine as `/financials/ratios` so the math is consistent across endpoints. Each result row carries the full ratio block (P/E, P/B, ROE, ROIC, EBITDA margin, debt-to-equity, cash-runway-status, sector/industry) so dashboards can render results without follow-up per-ticker calls. The right entry point for fundamental-screener UIs and quant pre-screens (e.g. 'find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin'). For per-ticker drill-downs use `/financials/metrics` (line items) or `/financials/snapshot` (TTM summary).

**Use case:** Stock screener: find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin. Chain with /snapshot for details.

**Parameters:**
- `gross_margin_gt` (query, optional): Keep only companies whose gross margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `gross_margin_lt` (query, optional): Keep only companies whose gross margin is less than this value (decimal, e.g. 0.15 = 15%).
- `operating_margin_gt` (query, optional): Keep only companies whose operating margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `operating_margin_lt` (query, optional): Keep only companies whose operating margin is less than this value (decimal, e.g. 0.15 = 15%).
- `net_margin_gt` (query, optional): Keep only companies whose net margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `net_margin_lt` (query, optional): Keep only companies whose net margin is less than this value (decimal, e.g. 0.15 = 15%).
- `fcf_margin_gt` (query, optional): Keep only companies whose free-cash-flow margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `fcf_margin_lt` (query, optional): Keep only companies whose free-cash-flow margin is less than this value (decimal, e.g. 0.15 = 15%).
- `roe_gt` (query, optional): Keep only companies whose ROE is greater than this value (decimal, e.g. 0.15 = 15%).
- `roe_lt` (query, optional): Keep only companies whose ROE is less than this value (decimal, e.g. 0.15 = 15%).
- `roa_gt` (query, optional): Keep only companies whose ROA is greater than this value (decimal, e.g. 0.15 = 15%).
- `roa_lt` (query, optional): Keep only companies whose ROA is less than this value (decimal, e.g. 0.15 = 15%).
- `roic_gt` (query, optional): Keep only companies whose ROIC is greater than this value (decimal, e.g. 0.15 = 15%).
- `roic_lt` (query, optional): Keep only companies whose ROIC is less than this value (decimal, e.g. 0.15 = 15%).
- `debt_to_equity_gt` (query, optional): Keep only companies whose debt-to-equity ratio is greater than this value (ratio).
- `debt_to_equity_lt` (query, optional): Keep only companies whose debt-to-equity ratio is less than this value (ratio).
- `debt_to_assets_gt` (query, optional): Keep only companies whose debt-to-assets ratio is greater than this value (ratio).
- `debt_to_assets_lt` (query, optional): Keep only companies whose debt-to-assets ratio is less than this value (ratio).
- `current_ratio_gt` (query, optional): Keep only companies whose current ratio is greater than this value (ratio).
- `current_ratio_lt` (query, optional): Keep only companies whose current ratio is less than this value (ratio).
- `quick_ratio_gt` (query, optional): Keep only companies whose quick ratio is greater than this value (ratio).
- `quick_ratio_lt` (query, optional): Keep only companies whose quick ratio is less than this value (ratio).
- `asset_turnover_gt` (query, optional): Keep only companies whose asset turnover is greater than this value (ratio).
- `asset_turnover_lt` (query, optional): Keep only companies whose asset turnover is less than this value (ratio).
- `interest_coverage_gt` (query, optional): Keep only companies whose interest coverage is greater than this value (ratio).
- `interest_coverage_lt` (query, optional): Keep only companies whose interest coverage is less than this value (ratio).
- `inventory_turnover_gt` (query, optional): Keep only companies whose inventory turnover is greater than this value (ratio).
- `inventory_turnover_lt` (query, optional): Keep only companies whose inventory turnover is less than this value (ratio).
- `receivables_turnover_gt` (query, optional): Keep only companies whose receivables turnover is greater than this value (ratio).
- `receivables_turnover_lt` (query, optional): Keep only companies whose receivables turnover is less than this value (ratio).
- `revenue_growth_yoy_gt` (query, optional): Keep only companies whose YoY revenue growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_yoy_lt` (query, optional): Keep only companies whose YoY revenue growth is less than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_yoy_gt` (query, optional): Keep only companies whose YoY EPS growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_yoy_lt` (query, optional): Keep only companies whose YoY EPS growth is less than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_qoq_gt` (query, optional): Keep only companies whose QoQ revenue growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_qoq_lt` (query, optional): Keep only companies whose QoQ revenue growth is less than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_qoq_gt` (query, optional): Keep only companies whose QoQ EPS growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_qoq_lt` (query, optional): Keep only companies whose QoQ EPS growth is less than this value (decimal, e.g. 0.15 = 15%).

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "filters": [
      "roe > 0.15",
      "debt_to_equity < 1.0"
    ],
    "count": 847,
    "results": [
      {
        "ticker": "AAPL",
        "company": "Apple Inc."
      },
      {
        "ticker": "MSFT",
        "company": "Microsoft Corp"
      }
    ]
  }
}
```

### GET /api/v1/financials/changes/{ticker}

Get details of what changed for a specific company in the last 7 days.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`).
- `data.since` (string): ISO-8601 UTC timestamp echoed back — the lower-bound used for the query.
- `data.periods_updated[]` (array): Array of period-update rows, sorted by `updated_at DESC`. Empty array when no updates within `since` window. Restatement events emit multiple rows (one per affected historical period); typical 10-Q/10-K loads emit one row.
- `data.periods_updated[].year` (integer): Fiscal year of the updated period (e.g. `2025`).
- `data.periods_updated[].period` (string): Fiscal period label: `Q1`/`Q2`/`Q3`/`Q4` for quarterly, `FY` for annual.
- `data.periods_updated[].period_end` (string): ISO `YYYY-MM-DD` end-date of the updated fiscal period. Non-calendar fiscal-year-end-aware.
- `data.periods_updated[].metrics_count` (integer): Total count of standardized metrics that were inserted or updated for this period in this load. Typical 10-Q: 30-40; 10-K: 40-60; restatement: variable.
- `data.periods_updated[].updated_at` (string): ISO-8601 UTC timestamp of when the ETL load completed for this period.
- `data.periods_updated[].trigger` (string (nullable)): Human-readable cause: `10-Q filing` / `10-K filing` / `8-K/A restatement` / `XBRL re-parse` / `Backfill load`. Null when uncertain.
- `data.metrics_affected` (array): Deduplicated list of standardized metric names (matches `/financials/metrics` response field names) that changed in any of the `periods_updated` rows. Use to selectively re-fetch only the affected metrics in your downstream sync.
- `data.ratios_affected` (array): Deduplicated list of derived ratio names (matches `/financials/ratios` response field names) that changed because their underlying metrics changed. Useful for cache-invalidation in ratio-driven UIs.

**Since:** v3.4.0

**Utility:** Drill into per-ticker filing changes.

**Use case:** After /changes shows a company was updated, use this to see which periods and metrics changed.

**Parameters:**
- `ticker` (path, required): Stock ticker symbol (canonical hyphen form). Returns 404 if ticker has no XBRL coverage; returns empty `periods_updated[]` if ticker exists but has no recent updates.
- `since` (query, optional, default: 7d-ago): ISO-8601 UTC timestamp lower-bound on `updated_at`. Default = 7 days ago. Pass a wider window to surface restatement events that backfill historical periods.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "ticker": "AAPL",
    "company": "Apple Inc.",
    "cik": "0000320193",
    "since": "2026-04-25T00:00:00Z",
    "periods_updated": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "metrics_count": 36,
        "updated_at": "2026-04-30T01:42:13Z",
        "trigger": "10-Q filing"
      }
    ],
    "metrics_affected": [
      "revenue",
      "net_income",
      "eps_basic",
      "eps_diluted",
      "operating_income",
      "free_cash_flow",
      "total_assets",
      "total_equity"
    ],
    "ratios_affected": [
      "gross_margin",
      "operating_margin",
      "net_margin",
      "roe",
      "roa",
      "roic"
    ]
  }
}
```

### GET /api/v1/financials/status

System status for the XBRL pipeline: table row counts, last sync times, and pipeline health.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `data.database` (object): Row counts for each XBRL pipeline table. Useful for capacity-planning and ETL-completeness checks. Sub-fields: `cf_facts` (raw concept-level facts — typically 40-50M post-Phase-49), `cf_standardized_metrics` (Phase-49 standardized metrics — typically 2-3M), `cf_derived_metrics` (Phase-49 derived ratios — typically 1.5-2M), `cf_companies` (covered ticker count — typically 7000-7300), `cf_concepts` (unique us-gaap + dei concepts seen — typically 20K-25K).
- `data.database.cf_facts` (integer): Total raw concept-level facts in the system (e.g. one row per (cik, concept, period, value) tuple from EDGAR's companyfacts JSON). Grows ~50K rows/day during normal filing cadence.
- `data.database.cf_standardized_metrics` (integer): Total Phase-49-standardized metrics (e.g. `revenue` collapsing across `us-gaap:Revenues` + `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` + `us-gaap:SalesRevenueNet`). One row per (ticker, fiscal-period, metric-name).
- `data.database.cf_derived_metrics` (integer): Total derived ratios (e.g. ROE, debt-to-equity, gross_margin). One row per (ticker, fiscal-period, ratio-name). Computed nightly from `cf_standardized_metrics`.
- `data.database.cf_companies` (integer): Distinct ticker count with at least one parsed XBRL fact. Equals the result count of `/api/v1/financials/tickers` with empty `q`.
- `data.last_update` (string): ISO-8601 UTC timestamp of the most-recent ETL completion (any step). Compare against current time for staleness detection.
- `data.recent_syncs[]` (array): Recent ETL step executions, sorted by `time DESC`. Each row represents one daily-pipeline step run.
- `data.recent_syncs[].step` (string): Pipeline step name. Values: `companyfacts_download` (EDGAR bulk JSON download), `facts_load` (ingest into cf_facts), `standardized_metrics` (Phase-49 standardization pass), `derived_metrics` (Phase-49 ratio computation), `delta_detection` (changes-feed population).
- `data.recent_syncs[].time` (string): ISO-8601 UTC timestamp of step completion.
- `data.recent_syncs[].records` (integer): Records processed in this step run. For incremental loads this is the delta count; for full re-syncs (rare) this is the total table count.
- `data.recent_syncs[].duration_sec` (number): Step duration in seconds. Use as performance baseline (e.g. companyfacts_download typically 400-600 sec; standardized_metrics typically 150-200 sec). Spikes >2x baseline indicate degradation.
- `data.recent_syncs[].status` (string): Step outcome: `success` / `failed` / `partial` / `skipped`. Failed steps surface in `pipeline_health: degraded`.
- `data.pipeline_health` (string): Overall pipeline health summary. Values: `healthy` (last 4 step runs all succeeded, staleness < 24h), `degraded` (any failed step in last 24h OR staleness > 24h but < 48h), `critical` (staleness > 48h OR multiple consecutive failures). For status-page dashboards consume this directly; for deep diagnostics inspect `recent_syncs[]`.
- `data.staleness_hours` (number): Hours since `last_update` (rounded to 1 decimal). Useful for staleness-alert thresholds (e.g. alert if > 30h — XBRL pipeline runs daily ~01:00 UTC, so 24-30h is normal weekend/holiday cycle).

**Since:** v3.4.0

**Utility:** Monitor pipeline health and data freshness.

**Use case:** Admin dashboards, health checks, debugging data staleness issues.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "database": {
      "cf_facts": 45000000,
      "cf_standardized_metrics": 2800000,
      "cf_derived_metrics": 1900000,
      "cf_companies": 7200,
      "cf_concepts": 21500
    },
    "last_update": "2026-05-02T01:45:00Z",
    "recent_syncs": [
      {
        "step": "companyfacts_download",
        "time": "2026-05-02T00:30:00Z",
        "records": 7200,
        "duration_sec": 482.1,
        "status": "success"
      },
      {
        "step": "facts_load",
        "time": "2026-05-02T01:05:00Z",
        "records": 84300,
        "duration_sec": 612.4,
        "status": "success"
      },
      {
        "step": "standardized_metrics",
        "time": "2026-05-02T01:25:00Z",
        "records": 12800,
        "duration_sec": 178.3,
        "status": "success"
      },
      {
        "step": "derived_metrics",
        "time": "2026-05-02T01:40:00Z",
        "records": 8200,
        "duration_sec": 45.2,
        "status": "success"
      }
    ],
    "pipeline_health": "healthy",
    "staleness_hours": 8.5
  }
}
```

### GET /api/v1/financials/stock-overview

Market data snapshot for a ticker from yfinance-sourced daily data. Returns beta, close price, sector, industry, market cap, enterprise value, float shares, short data, first traded date, plus technical indicators (RSI, score, volume, pct_change, pct_from_high, above_200_sma, above_50_sma).

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Issuer ticker (canonical hyphen form, echoed back).
- `data.company` (string): Company name (Title Case from yfinance).
- `data.date` (string): ISO `YYYY-MM-DD` reference date for the snapshot (latest market close — typically prior trading day during US market hours, current trading day after close). May be 1-2 days stale on weekends/holidays.
- `data.close` (number): Last close price (USD per share). NOT split-adjusted server-side — reflects as-traded price for the reference date. For split-adjusted historical price series use external market-data sources.
- `data.beta` (number (nullable)): 5-year monthly beta vs S&P 500. Decimal (`1.0` = market-neutral, `>1` = higher-volatility, `<1` = lower-volatility). Null for very-recent IPOs (<1 year of price history).
- `data.sector` (string (nullable)): yfinance sector classification (matches Yahoo Finance's sector taxonomy — slightly different from Sharadar's). Null for unmapped tickers.
- `data.industry` (string (nullable)): yfinance industry classification (more specific than sector). Null for unmapped tickers.
- `data.market_cap` (number (nullable)): Market capitalization (USD). Computed as `close × shares_outstanding`. Use for size-based universe filters (e.g. mega-cap > $200B, large-cap $10-200B, mid-cap $2-10B, small-cap $300M-2B, micro-cap <$300M).
- `data.enterprise_value` (number (nullable)): Enterprise value (USD). `market_cap + total_debt - cash_and_equivalents`. The classic 'all-stakeholder' valuation metric — combine with [/financials/snapshot](/docs/company-data/company-financials-xbrl/get-financials-snapshot) EBITDA for EV/EBITDA multiple.
- `data.float_shares` (number (nullable)): Public float (shares freely tradable, excluding insider + institutional restricted holdings). Useful for liquidity-aware position sizing — small-caps with float < 50M shares can have wide bid-ask spreads.
- `data.shares_outstanding` (number (nullable)): Total shares outstanding (point-in-time). Compare against [/financials/metrics](/docs/company-data/company-financials-xbrl/get-financials-metrics) `shares_outstanding` (which is weighted-average for the period); they differ for issuers with active buyback/issuance.
- `data.short_percent_of_float` (number (nullable)): Short interest as fraction of float (decimal — `0.0072` = 0.72%). Updated bi-monthly (NYSE/NASDAQ short-interest publication cadence) so may lag by 2-3 weeks. Above 0.20 flags potentially-squeeze-able names.
- `data.short_ratio` (number (nullable)): Days-to-cover ratio: `short_interest / avg_daily_volume`. Higher = harder for shorts to cover. Above 5 days flags squeeze risk.
- `data.first_traded` (string (nullable)): Unix epoch seconds (as a string) of the ticker's first trading day. Useful for filtering recent IPOs (within 1 year). For human-readable date use the existing `date` semantic on `/api/v1/tickers/{ticker}/overview`.
- `data.rsi_14d` (number (nullable)): 14-day Relative Strength Index (technical momentum indicator). Range `[0, 100]`. Standard interpretation: >70 overbought, <30 oversold. Useful for short-term mean-reversion screens.
- `data.score` (number (nullable)): FinRadar composite technical score (proprietary blend of RSI + SMA-trend + volume signals). Range `[0, 100]`. Higher = stronger technical setup. NOT a buy/sell recommendation — a single technical-flavor signal among many.
- `data.volume` (number (nullable)): Latest trading-day volume (shares). Compare against `avg_volume_30d` for volume-spike detection.
- `data.avg_volume_30d` (number (nullable)): 30-day average daily trading volume. Smoother baseline than spot volume — `volume / avg_volume_30d > 2` flags abnormal-volume sessions.
- `data.pct_change_1d` (number (nullable)): 1-day percent price change (decimal — `0.0048` = +0.48%). Same-day if calling after close; previous-day-vs-day-before-that during market hours.
- `data.pct_change_30d` (number (nullable)): 30-day percent price change (decimal). Useful for medium-term momentum filters.
- `data.pct_from_52w_high` (number (nullable)): Percent from 52-week high (decimal — typically negative since price <= 52w high; `-0.038` = 3.8% below high). Above `-0.05` indicates strong-trend territory; below `-0.30` indicates significant drawdown.
- `data.pct_from_52w_low` (number (nullable)): Percent from 52-week low (decimal — typically positive). Combine with `pct_from_52w_high` for range-position assessment.
- `data.sma_50` (number (nullable)): 50-day simple moving average price (USD). Short-trend reference.
- `data.sma_200` (number (nullable)): 200-day simple moving average price (USD). Long-trend reference. Standard 'golden cross' = sma_50 crossing above sma_200; 'death cross' = below.
- `data.above_200_sma` (boolean (nullable)): Boolean: `true` when `close > sma_200`. The classic long-trend filter — most quant momentum strategies require `above_200_sma=true`.
- `data.above_50_sma` (boolean (nullable)): Boolean: `true` when `close > sma_50`. Short-trend filter.

**Since:** v3.4.0

**Utility:** Get current market data for DCF models and stock research pages.

**Use case:** DCF module (beta + close price), Financials module (sector, industry, market cap, enterprise value, float, short interest).

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 if ticker has no Yahoo Finance / yfinance daily-data coverage. Cache: 24h server-side.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "ticker": "AAPL",
    "company": "Apple Inc.",
    "date": "2026-05-01",
    "close": 268.5,
    "beta": 1.121,
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "market_cap": 3984500000000,
    "enterprise_value": 4058044000000,
    "float_shares": 14820000000,
    "shares_outstanding": 14840000000,
    "short_percent_of_float": 0.0072,
    "short_ratio": 1.38,
    "first_traded": "345479400",
    "rsi_14d": 58.4,
    "score": 72,
    "volume": 48230000,
    "avg_volume_30d": 52100000,
    "pct_change_1d": 0.0048,
    "pct_change_30d": 0.041,
    "pct_from_52w_high": -0.038,
    "pct_from_52w_low": 0.214,
    "sma_50": 261.2,
    "sma_200": 244.8,
    "above_200_sma": true,
    "above_50_sma": true
  }
}
```

---

## SQL Proxy (SCC Migration)

Raw SQL SELECT proxy for WordPress Social Command Center migration. Executes read-only queries against a whitelist of tables. Authenticated via api_key.

### POST /api/v1/sql-proxy

Execute a read-only SELECT query against whitelisted PostgreSQL tables. Returns rows as array of objects with column names as keys. **Error responses are sanitized** (issue #273): raw SQL / psycopg2 / SQLAlchemy traces are NEVER echoed to the caller — the response body is always a short generic message. **Status codes:** 200 success; 401 `Invalid api_key`; 403 `Forbidden keyword: <X>` or `Table not allowed: <X>` (policy violations); 400 `query parameter is required`; 500 `Query execution failed.` (DB-runtime error — full detail is logged server-side with the request_id). **All 4xx and 5xx responses AUTO-REFUND the 25-token charge** (paired `debit` + `4xx_refund`/`5xx_refund` rows in `/account/transactions`; net zero on the ledger; see also issue #254).

**Token cost:** 25 tokens per call

**Utility:** Drop-in replacement for DigitalOcean dbQuery() — WordPress pgQuery() POSTs here with SQL and api_key.

**Use case:** SCC pages that need stock prices, signals, earnings calendar, or AI summaries from PostgreSQL.

**Parameters:**
- `query` (body, required): SQL SELECT statement to execute. Only SELECT allowed; INSERT/UPDATE/DELETE/DROP rejected. Tables restricted to: all_stocks_strategies_yf_daily, all_stocks_list, all_stocks_signals_daily, all_stocks_signals_weekly, all_stocks_signals_monthly, all_etfs_signals_daily, all_etfs_signals_weekly, all_etfs_signals_monthly, market_calendar, ai_daily_summaries.
- `api_key` (body, required): API key for authentication. Also accepted via X-API-Key header, Authorization: Bearer header, or api_Token/apiKey query params.

**Sample response:**
```json
{
  "success": true,
  "data": [
    {
      "symbol": "AAPL",
      "close": 198.15
    }
  ]
}
```

---

## Operations / Airflow (Admin)

Proxy endpoints for the Airflow REST API v2. Admin-only access. Enables monitoring and controlling DAG pipelines from the FinRadar dashboard without direct Airflow UI access.

### GET /api/v1/admin/airflow/dags

List all Airflow DAGs with merged run statistics.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Get a combined view of DAG definitions and their execution state counts.

**Use case:** Populating the Operations dashboard DAG table with status badges and last-run info.

### GET /api/v1/admin/airflow/dags/{dag_id}/runs

List recent runs for a specific DAG.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** View execution history and status of a pipeline.

**Use case:** Drilling into a DAG to see its recent run outcomes, durations, and failure details.

**Parameters:**
- `dag_id` (path, required): The DAG identifier
- `limit` (query, optional): Max runs to return (default 10)

### POST /api/v1/admin/airflow/dags/{dag_id}/trigger

Trigger a new DAG run.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Manually start a pipeline execution on demand.

**Use case:** Ad-hoc execution of data pipelines (e.g., re-running XBRL sync after a fix).

**Parameters:**
- `dag_id` (path, required): The DAG identifier

### GET /api/v1/admin/airflow/health

Check Airflow scheduler and API server health.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Verify the orchestration layer is operational.

**Use case:** Health monitoring badge on the Operations dashboard.

### PATCH /api/v1/admin/airflow/dags/{dag_id}/toggle

Pause or unpause a DAG.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Utility:** Enable or disable scheduled execution of a pipeline.

**Use case:** Emergency pause of a misbehaving pipeline from the dashboard.

**Parameters:**
- `dag_id` (path, required): The DAG identifier
- `is_paused` (body, required): Boolean — true to pause, false to unpause

---

## Bulk Data Downloads

Download historical insider trading data in bulk. Monthly JSONL.gz files for Form 3, 4, and 5 filings. Each file contains complete filing records (same structure as individual filing detail endpoint).

### GET /api/insiders/bulk/form-{form_type}/index.json

Get index of available monthly bulk download files for a form type. Returns list of available months with file size, record count, generation date, and download URL. Status is 'available' (pre-generated) or 'pending' (will be generated on first download).

**Token cost:** 25 tokens per call

**Response fields:**
- `form_type` (string): Form type echoed back (`3`, `4`, or `5`). Useful for asserting your client's request resolved correctly.
- `files` (array): Array of monthly bulk-file metadata rows, sorted by `(year, month) DESC` (most-recent month first). Coverage starts in 2003 (the SEC's electronic Form 4 mandate). Empty array on form types with no bulk coverage (won't happen in practice — all 3 form types are covered).
- `files[].year` (integer): Calendar year of the file's coverage period (e.g. `2026`). Combined with `month` forms the file's coverage window.
- `files[].month` (integer): Calendar month 1-12 of the file's coverage period. Files cover the calendar month exactly (no fiscal-period offset).
- `files[].filename` (string): Bulk file name in `form-{type}-{YYYY}-{MM}.jsonl.gz` format (e.g. `form-4-2026-04.jsonl.gz`). Pass to `/bulk/form-{form_type}/{year}/{filename}` to retrieve the signed download URL.
- `files[].row_count` (integer): Number of JSONL lines (= filings) in the gzipped file. Form 4 monthly files: typically 25K-35K; Form 3: 1K-3K; Form 5: 0.5K-2K. Use for client-side cost-budgeting before download.
- `files[].size_bytes` (integer): Compressed file size in bytes (post-gzip). Form 4 monthly files: typically 4-8 MB compressed (~50-80 MB uncompressed). Form 3 and Form 5 files: < 1 MB. Plan downstream consumer pipelines accordingly.
- `files[].sha256` (string): SHA-256 hex digest of the gzipped file contents. Use for download-integrity verification — the bulk-fetch endpoint returns the same SHA, so client code can assert the downloaded blob matches before processing.
- `files[].generated_at` (string): ISO-8601 UTC timestamp when this file was last regenerated. Files are regenerated nightly to incorporate late amendments — values within the last 24 hours indicate a fresh generation; older values indicate the cold-storage path is being served.

**Since:** v3.14.0

**Utility:** Discover the bulk-data inventory before fetching individual files — returns the full list of monthly Form 3/4/5 bulk export files with file sizes, row counts, generation timestamps, and SHA-256 digests for integrity verification. The right entry point for any bulk-export workflow: enumerate this first to find the months you need, then drill into `/bulk/form-{form_type}/{year}/{filename}` to retrieve signed download URLs. Files cover one calendar month each, regenerated nightly to incorporate late amendments. Files older than 12 months are kept in cold storage with ~1 minute extra latency on first surface — once warmed, subsequent index calls return them instantly.

**Use case:** Building a bulk data download page that shows available months, file sizes, and record counts — like SEC EDGAR's full-text search bulk download index.

**Parameters:**
- `form_type` (path, required): SEC insider-trading form type to enumerate. Accepts `3` (initial statement of beneficial ownership — filed when an insider first joins), `4` (statement of changes — every transaction; the highest-volume), or `5` (annual statement — captures missed Form 4 filings). Form 4 is the most-requested for trading analytics; Forms 3 and 5 are typically only relevant for compliance / governance research.

**Sample response:**
```json
{
  "form_type": "4",
  "files": [
    {
      "year": 2026,
      "month": 4,
      "filename": "form-4-2026-04.jsonl.gz",
      "row_count": 28432,
      "size_bytes": 4128000,
      "sha256": "a1b2c3d4...",
      "generated_at": "2026-05-01T00:30:12.000Z"
    }
  ]
}
```

### GET /api/insiders/bulk/form-{form_type}/{year}/{filename}

Download a monthly bulk data file as gzip-compressed JSONL (one JSON object per line). Each line is a complete filing record with issuer, owners, transactions, holdings, footnotes, and signatures. Files are pre-generated when available, or streamed on-the-fly if not yet cached.

**Token cost:** 25 tokens per call

**Response fields:**
- `download_url` (string): Signed S3 download URL valid for 24 hours from response time. Direct download — no auth required for the URL itself, signature handles authorization. Stream the response with `gzip` decompression; do NOT load the full uncompressed payload into memory for large months (Form 4 monthly files uncompress to 50-80 MB).
- `filename` (string): Filename echoed back, useful for asserting your client's path-construction matched what was retrieved (especially when constructing from an enumeration loop).
- `row_count` (integer): Number of JSONL lines (= filings) in the file. Use for download-completeness verification: after gunzip, your client should see exactly `row_count` lines (`wc -l`) — any mismatch indicates a partial download, retry.
- `size_bytes` (integer): Compressed file size in bytes. Use for `Content-Length` validation against the S3 download — mismatches indicate a corrupted or partial download.
- `sha256` (string): SHA-256 hex digest of the gzipped file contents. Compute the SHA-256 of the downloaded blob locally and compare to assert integrity before processing — critical for any pipeline that depends on byte-exact reproducibility.
- `expires_at` (string): ISO-8601 UTC timestamp when the signed URL expires (always `now + 24h`). After expiry the URL returns 403 — re-call this endpoint to mint a fresh signed URL (cheap; cache hit on the underlying file for up to 7 days).

**Since:** v3.14.0

**Utility:** Retrieve a signed S3 download URL for one month's worth of insider filings as gzip-compressed JSONL — one filing per line, fully nested with issuer + reporters + non-derivative/derivative transactions + holdings + footnotes + signatures (matches the per-filing `/insiders/filings/{accession_number}` shape). The bulk-export workflow for quantitative research: backtest insider-signal strategies on 20+ years of Form 4 history, build a local database mirror, or train models on the full event-time stream. Pair with `/bulk/form-{form_type}/index.json` to enumerate available months first, then fetch each file via this endpoint. The 24-hour signed-URL TTL gives you ample window for download retries; for fresh URLs after expiry, just re-call (the underlying file is cached for 7 days, so re-call is fast).

**Use case:** Bulk downloading all Form 4 filings from 2024 for quantitative research, backtesting insider trading strategies, or building a local database mirror.

**Parameters:**
- `form_type` (path, required): SEC insider-trading form type — `3` (initial statement), `4` (changes — highest volume), or `5` (annual statement). Same set as the index endpoint's `form_type` parameter.
- `year` (path, required): 4-digit calendar year of the file (e.g. `2025`). Coverage starts 2003 (SEC's electronic Form 4 mandate). Returns 404 for years outside coverage.
- `filename` (path, required): Bulk file name in `form-{type}-{YYYY}-{MM}.jsonl.gz` format. Get exact filenames from `/bulk/form-{form_type}/index.json` — DO NOT hand-construct (filename schema may evolve). Returns 404 if the filename doesn't match any indexed file.

**Sample response:**
```json
{
  "download_url": "https://finradar-bulk.s3.amazonaws.com/form-4/2026/form-4-2026-04.jsonl.gz?X-Amz-Signature=...",
  "filename": "form-4-2026-04.jsonl.gz",
  "row_count": 28432,
  "size_bytes": 4128000,
  "sha256": "a1b2c3d4...",
  "expires_at": "2026-05-02T20:55:12.000Z"
}
```

### POST /api/insiders/bulk/form-{form_type}/generate/{year}/{month}

Generate a monthly bulk data file on demand. Use this when /api/insiders/bulk/form-{form_type}/index.json reports the desired month as 'pending'. Triggers a server-side packing job and returns the download URL once the file is ready. Idempotent — a second call against an already-generated month returns the cached file.

**Token cost:** 25 tokens per call

**Response fields:**
- `job_id` (string): Celery task UUID assigned to the regeneration job. Surface in support tickets when a regeneration appears stuck — operations can grep this directly out of `flower` / Celery logs to trace the exact worker, queue, and per-step duration.
- `queued_at` (string): ISO-8601 UTC timestamp at which the job entered the bulk-export queue. For end-to-end latency measurement, compare this against the new `generated_at` timestamp on the index endpoint after polling.
- `estimated_seconds` (integer): Server-side ETA in whole seconds for the regeneration to complete, computed from the requested month's row count + worker concurrency. Form 4 recent months: typically 60-120 seconds; cold-storage months: 90-300 seconds. Treat as a hint — schedule a re-poll at `queued_at + 1.5 × estimated_seconds`.
- `status` (string): Always the literal string `"queued"` on a successful enqueue. The regeneration itself is asynchronous — this endpoint never returns `"completed"`. Detect completion by polling `/bulk/form-{form_type}/index.json` and watching for the new `generated_at` timestamp + updated `sha256`.

**Since:** v3.14.0

**Utility:** Force on-demand regeneration of a monthly bulk file — useful when amendments have been filed AFTER the nightly regeneration window and you want a fresh file that incorporates them. Also the right endpoint for cold-storage warming (months older than 12 months may need this call to surface). The job is enqueued on the bulk-export Celery worker and runs asynchronously — returns a job descriptor immediately, then poll `/bulk/form-{form_type}/index.json` for the new `generated_at` timestamp and updated `sha256`. Idempotent — calling against an already-generated month returns the cached file with the same SHA. Heavy operation: 25-token cost reflects the full month re-pack; budget accordingly for backfill workflows that hit many months.

**Parameters:**
- `form_type` (path, required): SEC insider-trading form type — `3`, `4`, or `5`. Same set as the read endpoints. Form 4 has the highest regeneration latency due to volume; Forms 3 and 5 typically complete in < 30 seconds.
- `year` (path, required): 4-digit calendar year of the month to regenerate. Coverage starts 2003. Returns 400 for years outside coverage. Old months (>12 months) may take an extra ~60 seconds for the cold-storage hydration step.
- `month` (path, required): Calendar month 1-12 to regenerate. Single-month scope only — for multi-month backfills, loop the call client-side. The job's `estimated_seconds` reflects the volume of the requested month; recent months are faster due to warm cache, archival months are slower.

**Sample response:**
```json
{
  "job_id": "8f1a2b30-c4d5-46e7-9f01-23456789abcd",
  "queued_at": "2026-05-01T20:55:12.000Z",
  "estimated_seconds": 90,
  "status": "queued"
}
```

---

## Facts (XBRL Concept Index)

Concept-indexed XBRL facts. Where Company Financials (XBRL) returns standardized metrics + ratios, this section returns the raw concept-level facts (e.g. us-gaap:Revenues, us-gaap:NetIncomeLoss) so customers can build custom calculations against the underlying SEC filing data.

### GET /api/v1/facts/by-concept

XBRL facts queried by concept. Returns every reported value of a given XBRL concept (e.g. us-gaap:Revenues) across companies, periods, and filings.

**Token cost:** 10 tokens per call

**Response fields:**
- `concept` (string): Concept name echoed back, case-preserved (e.g. `us-gaap:Revenues`). Useful for asserting your client passed the concept you intended.
- `facts` (array): Array of matching fact rows, sorted by `(ticker ASC, period_end DESC)` so per-ticker time-series are grouped. One row per `(ticker, period, dimension)` tuple — same ticker can appear multiple times if reported across multiple periods or dimensional members.
- `facts[].ticker` (string (nullable)): Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker. Use as primary grouping key when rendering cross-company comparisons.
- `facts[].cik` (string): Filer CIK in 10-char zero-padded form. Stable identifier even when ticker is null.
- `facts[].value` (number (nullable)): Numeric fact value in the unit specified by `unit`. Null for textual or non-numeric facts (rare on the standard us-gaap concepts since they're almost all numeric). NOT scale-adjusted — reconcile against `unit` to interpret (e.g. value=391035 + unit=USD-thousands means $391.035M).
- `facts[].unit` (string (nullable)): XBRL unit. Common values: `USD`, `shares`, `pure` (dimensionless), `USD-per-share`, `iso4217:JPY`/`iso4217:EUR` (foreign currencies). Null only when `value` is null. Always check unit before arithmetic — companies routinely mix `USD` and `USD-thousands` within the same filing.
- `facts[].period_start` (string (nullable)): ISO `YYYY-MM-DD` start date for duration concepts (income-statement and cash-flow facts). Null for instant concepts (balance-sheet facts that are point-in-time at `period_end`).
- `facts[].period_end` (string): ISO `YYYY-MM-DD` end date — for instant concepts the as-of date; for duration concepts the period end. Always present. Use for time-series x-axis and for range-filtering.
- `facts[].accession_number` (string): SEC accession of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `GET /api/v1/sec/filings/{accession_number}` to drill into the source filing's metadata.
- `facts[].form_type` (string): Source filing form type — typically `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`. Useful for filtering to annual-only (`10-K`) for clean YoY analysis or quarterly-only (`10-Q`) for QoQ tracking.
- `meta` (object): Pagination + filter echo block: `{ total: integer, limit: integer, applied_filters: object }`. `total` is the cap-aware match count for the concept × filter set.

**Since:** v3.4.0

**Utility:** Cross-company concept-level XBRL fact lookup — pass a concept name (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`) and receive every reported value across the ~7,000-company XBRL universe, optionally filtered by date range, ticker list, or sector. The 'raw' lookup — does NOT standardize across filings, fiscal calendars, or restated numbers. Use this when you need the AS-FILED fact for audit trails, custom analytical workflows, or LLM-grounded research that needs the exact reported value (not FinRadar's standardized reconciliation). For standardized cross-company comparisons (e.g. 'compare TTM revenue across S&P 500') use `/financials/metrics` instead, which standardizes the messy as-filed facts into a clean canonical schema.

**Parameters:**
- `concept` (query, required): XBRL concept name in `prefix:LocalName` format. Standard concepts use `us-gaap:` prefix (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`); company-specific extensions use the company's own prefix. Case-sensitive. Returns 400 for unknown concepts; use the SEC EDGAR taxonomy browser to verify concept names before query.
- `ticker` (query, optional): Restrict to one issuer ticker (case-insensitive, canonical hyphen normalization). Default: returns facts across all ~7,000 companies. Useful for per-ticker concept time-series ('show me every reported `us-gaap:Revenues` for AAPL across all quarters').
- `date_from` (query, optional): Inclusive lower bound on `period_end` (ISO `YYYY-MM-DD`). Useful for limiting to recent fiscal periods on high-cardinality concepts.
- `date_to` (query, optional): Inclusive upper bound on `period_end` (ISO `YYYY-MM-DD`). Combine with `date_from` for closed ranges.
- `limit` (query, optional, default: 100): Maximum fact rows returned, capped at 1000 server-side. For bulk concept exports use date-range chunking + `limit=1000`.

**Sample response:**
```json
{
  "concept": "us-gaap:Revenues",
  "facts": [
    {
      "ticker": "AAPL",
      "cik": "0000320193",
      "value": 391035000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28",
      "accession_number": "0000320193-25-000123",
      "form_type": "10-K"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### POST /api/v1/facts/aggregate

Aggregate XBRL facts across companies. Reduces a concept across a filter set (sector, ticker list, period) and returns sum / avg / median / count statistics.

**Token cost:** 10 tokens per call

**Response fields:**
- `concept` (string): Concept name echoed back. Useful for asserting your client passed the concept correctly.
- `period` (string): Period filter echoed back as ISO date / quarter-string / year-string (whichever form was passed). Useful for chart annotations.
- `aggregates` (object): Computed aggregate statistics across all facts matching the filter set. All fields use the most-common unit across contributing facts (e.g. `USD` is preferred over `USD-thousands`); units are NOT auto-converted — when the contributing facts have mixed units, the aggregation falls back to filtering by majority-unit and excluding the minority. Use `count` to detect when this happened.
- `aggregates.sum` (number (nullable)): Sum across all matching fact values (in the dominant unit). Useful for total-revenue-style aggregates. Null when no facts match the filter set OR when all values are null.
- `aggregates.avg` (number (nullable)): Arithmetic mean across matching facts. Useful for sector-average analysis. Null when count=0. Note: not weighted — for revenue-weighted averages, run two queries (numerator-aggregated + denominator-aggregated) and divide.
- `aggregates.median` (number (nullable)): Median (50th percentile) across matching facts. Useful for distribution-center analysis on heavy-tailed concepts where mean is skewed by outliers (e.g. revenue distributions are typically log-normal — median is the better center metric than mean). Null when count=0.
- `aggregates.count` (integer): Number of facts contributing to the aggregation. Always non-negative. Use to detect filter-too-narrow cases (count=0 means no matches; count<10 means small sample warrants caution).
- `aggregates.min` (number (nullable)): Minimum value across matching facts. Useful for identifying outlier candidates (lowest reported revenue in sector, smallest cap-ex spend). Null when count=0.
- `aggregates.max` (number (nullable)): Maximum value across matching facts. Useful for identifying top-of-distribution outliers. Null when count=0.
- `meta` (object): Filter echo block: `{ sector: string, tickers: array, period: string, dominant_unit: string, excluded_count: integer }`. `excluded_count` flags facts that were skipped due to unit mismatch — when non-zero, suggests you should filter your input cohort to a single-unit subset for cleaner aggregation.

**Since:** v3.4.0

**Utility:** Cross-company aggregation of one XBRL concept across a filter set — pass `concept` + `period` + optional sector / ticker-list filters and receive `sum`, `avg`, `median`, `count`, `min`, `max` in one shot. The right endpoint for sector-wide research workflows like 'median capex / revenue across S&P 500 Industrials in 2025', 'total reported revenue across all reporting companies in Q4 2025', or 'distribution of book-value-per-share across Healthcare names'. Pair with `/facts/by-concept` when you need the underlying row-level data; pair with `/financials/screen` when you want filter-then-rank workflows on standardized ratios. The 10-token cost reflects the heavy multi-row reduction.

**Parameters:**
- `concept` (body, required): XBRL concept name in `prefix:LocalName` format (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`). Same concept syntax as `/facts/by-concept`. Returns 400 for unknown concepts.
- `period` (body, required): Period filter — accepts (a) exact ISO `YYYY-MM-DD` for a specific period-end date, or (b) `YYYY-Q1`/`YYYY-Q2`/`YYYY-Q3`/`YYYY-Q4` for fiscal-quarter rollup, or (c) `YYYY` for full-year (annual filings only). Calendar-year scope; for fiscal-year offsets (companies with non-calendar fiscal years) use `/facts/by-concept` and aggregate client-side.
- `sector` (body, optional): Sharadar sector filter (e.g. `Technology`, `Healthcare`, `Industrials`). Default: aggregate across all sectors. Excludes companies unmapped in Sharadar (~5% of universe).
- `tickers` (body, optional): Array of ticker strings to restrict the aggregation to (max 500 entries). Useful for index-defined cohort aggregations (e.g. 'aggregate over the S&P 500'). Mutually exclusive with `sector` — pass one or the other, not both.

**Sample response:**
```json
{
  "concept": "us-gaap:Revenues",
  "period": "2025-12-31",
  "aggregates": {
    "sum": 12400000000000,
    "avg": 24800000000,
    "median": 1820000000,
    "count": 500,
    "min": 50000000,
    "max": 391035000000
  },
  "meta": {
    "sector": "all",
    "period": "2025-12-31"
  }
}
```

---

## MCP Connect (OAuth 2.1)

One-click **Connect** for MCP clients (Cursor, Claude Desktop): instead of pasting an X-API-Key, the client runs the OAuth 2.1 authorization-code + PKCE flow against FinRadar's own login and gets a short-lived token. Discovery follows RFC 9728 (protected-resource) + RFC 8414 (authorization-server); the resource is `/api/mcp`. Both auth methods work side-by-side (dual auth) — existing X-API-Key clients are unaffected. Select FinRadar's MCP server in your client and click Connect to use it.

### GET /.well-known/oauth-protected-resource/api/mcp

Served by the MCP server (the resource server), NOT main_api. Returns `{ resource: <canonical /api/mcp URI>, authorization_servers: [<FinRadar AS>], scopes_supported: ['mcp'], bearer_methods_supported: ['header'] }`. An unauthenticated MCP call returns 401 with `WWW-Authenticate: Bearer ... resource_metadata=<this URL>` — how a client discovers where to authorize.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

### GET /.well-known/oauth-authorization-server

FinRadar AS metadata: `issuer`, `authorization_endpoint` (/oauth/authorize), `token_endpoint` (/oauth/token), `jwks_uri`, `code_challenge_methods_supported: ['S256']` (PKCE S256 required), `scopes_supported: ['mcp']`, `grant_types_supported: ['authorization_code','refresh_token']`.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

### GET /.well-known/jwks.json

The AS's RS256 public keys. The MCP server verifies access tokens against these (it holds no signing secret). Access tokens are RS256 JWTs with `iss`, `aud` (the canonical resource), `sub` (user uuid), `scope: mcp`, `token_use: mcp_access`, short `exp` (≤15 min), and `kid`.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

### POST /oauth/register

Open registration endpoint (advertised as `registration_endpoint` in the AS metadata). An MCP client POSTs its metadata as JSON and receives a `client_id`. **Public clients only**: `token_endpoint_auth_method` is forced to `none` (no secret — authenticate with PKCE), `scope` is forced to `mcp`, `grant_types` is filtered to `authorization_code`(+`refresh_token`) and `response_types` to `code`. `redirect_uris` (required, 1-5) must each be `https` or a loopback `http://127.0.0.1[:port]` URI with no fragment (RFC 8252; `localhost` is rejected — register the 127.0.0.1 IP literal). Guarded by per-IP + global daily caps. Returns 201 `{ client_id, client_id_issued_at, redirect_uris, grant_types, response_types, token_endpoint_auth_method, scope }` — no `client_secret` (public client).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Parameters:**
- `redirect_uris` (body, required): JSON array (1-5) of allowed redirect URIs. Each must be `https` or loopback `http://127.0.0.1[:port]`, no fragment.
- `client_name` (body, optional): Human-readable client name shown on the consent page (escaped).
- `grant_types` (body, optional, default: authorization_code refresh_token): JSON array; filtered to the supported set (`authorization_code` required).
- `token_endpoint_auth_method` (body, optional, default: none): Public clients only — must be `none` (or omitted).

### GET /oauth/authorize

OAuth 2.1 authorization endpoint. GET renders a login + consent page (PKCE S256 required; CSRF-protected; framebusting). POST authenticates the user against the FinRadar login and, on Allow, redirects to `redirect_uri?code=...&state=...`. Loopback `redirect_uri` (http://127.0.0.1:<any-port>/...) is allowed for native clients (RFC 8252).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Parameters:**
- `response_type` (query, required): Must be `code`.
- `client_id` (query, required): Registered client id.
- `redirect_uri` (query, required): Must match a registered redirect (loopback any-port allowed).
- `scope` (query, optional, default: mcp): Single `mcp` scope.
- `state` (query, required): CSRF/correlation value echoed back.
- `code_challenge` (query, required): PKCE S256 challenge (base64url SHA-256 of the verifier).
- `code_challenge_method` (query, required): Must be `S256` (plain is rejected).

### POST /oauth/token

OAuth 2.1 token endpoint (public client, `token_endpoint_auth_method: none`). `grant_type=authorization_code` exchanges a one-time code + `code_verifier` for `{ access_token (RS256 JWT), token_type: Bearer, expires_in, refresh_token, scope }`. `grant_type=refresh_token` rotates the refresh token (reuse of a rotated token revokes the whole family).

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Parameters:**
- `grant_type` (body, required): `authorization_code` or `refresh_token`.
- `code` (body, optional): Authorization code (authorization_code grant).
- `code_verifier` (body, optional): PKCE verifier (authorization_code grant).
- `redirect_uri` (body, optional): Must match the authorize request.
- `refresh_token` (body, optional): Refresh token (refresh_token grant).
- `client_id` (body, required): Client id.

### POST /oauth/revoke

Revokes the presented refresh token and its whole rotation family. Always returns 200 per RFC 7009.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Parameters:**
- `token` (body, required): The refresh token to revoke.