---
title: "Api Institutional Holders"
method: GET
path: "/api/institutional-holders"
---

# Api Institutional Holders

`GET /api/institutional-holders`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/institutional-holders`
- Auth: none declared

Which institutional funds hold this ticker? Sourced from 13F filings.

Queries fund_holdings_snapshot (populated by the 13f_refresh batch job).
Returns the latest known position for each fund, including QoQ change type.

Data source: SEC EDGAR 13F-HR filings from notable institutional filers.
Updated quarterly (batch job: tools/daily_data_jobs.py --job 13f_refresh).
For broader 5%+ holder data from SC 13D/G filings, see /api/holders.

## Query parameters

- `ticker` string, required

## Response `200`

Successful Response

- InstitutionalHoldersResponse: `GET /api/institutional-holders` — 13F-filer positions for a ticker. `holders` is iterated in frontend without a null-check, so it is REQUIRED on every branch including 5xx error paths (the route's exception handler at routes_analysis_fastapi/options_insiders.py:319 already returns `holders: []` for this reason).
  - `ticker` string, required: Echoed ticker (uppercased).
  - `holders` object[], required: Per-fund positions for this ticker. May be empty. Each row carries `stale_quarters` (P1-13f, 2026-09-19): how many quarters behind `as_of_quarter` that row's filing is, 0 for current, null when the row's quarter is unparseable. A row struck at a quarter NEWER than `as_of_quarter` keeps `stale_quarters` 0 and adds `ahead_quarters` (>= 1, absent otherwise) — the clamp alone made such a row indistinguishable from one AT the as-of quarter (DATA_CZAR 2026-09-21 L7; 12 of 100 measured AAPL rows).
  - `total_holders` integer, nullable: Count of `holders`. Optional — present on happy path.
  - `as_of_quarter` string, nullable: Latest quarter represented (e.g. '2026-Q1').
  - `coverage` object, nullable: P2 (13F broad-coverage): {shares_13f, fund_count, shares_outstanding, pct, quarter} — the % of shares outstanding held by the tracked 13F filers. `pct` is None when shares_outstanding is unavailable.
  - `superseded_parents` object[], nullable: P1-13f (2026-09-19): rows WITHHELD from `holders` because the filer stopped filing and its book now arrives under sibling CIKs of the same family, reconciling within 1%. Each carries `superseded: true`, `superseded_by: [fund_cik, ...]`, and both operands of that reconciliation — `shares` (the withheld row's own count), `superseded_by_shares` (the sibling sum) and `reconciled_pct` (their distance apart). Never summed into `coverage` — folding them back in restores the double count this field exists to record; since 2026-09-21 their CIKs are also EXCLUDED from the coverage universe aggregate, which until then counted the same book twice (DATA_CZAR L3). Rendered to the reader on the in-app panel and the SSR /13f/security page.
  - `last_good` object, nullable: Present only when the live read failed and a stored copy was served (Sentry 8K, 2026-10-04): {cached_at (UTC ISO), age_s, reason: read_failed|pool_saturated}.
  - `degraded` string[], nullable: Present only when an enrichment read was pool-starved: 'prior_quarter' (QoQ fields null, not 'new') and/or 'coverage' (coverage.basis top_display). Such a result is never cached.
  - `error` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)