FocusAlphaDocs
Get key
API Reference

Owners (by ticker)

Every institutional manager that holds a given security, parsed from SEC Form 13F-HR filings. Pass a ticker and get one position per filer — each filer's most recent 13F that includes the security — sorted by reported value, largest holder first. Answers 'who owns AAPL?'

GET/v1/institutional-holdings?ticker={ticker}

Provide a ticker. By default you get the current institutional holders — one row per filer, drawn from each filer’s latest 13F that reports the security — sorted by value_usd descending. Use report_period or the date-range filters to narrow that set to filers whose latest reported position falls in a given quarter. Results come back under an institutional_holdings array.

Coverage & freshness
Holders are drawn from the largest US institutional managers by AUM — roughly 500 filers — with up to the last 8 quarters each, parsed straight from SEC Form 13F-HR. This is who, among that covered set, reports the security; it is not the entire shareholder base. See Data source & coverage for the full scope and the 13F boundary.

Query parameters#

tickerstringrequired
US ticker, e.g. AAPL. Provide ticker or filer_cik — exactly one is required.
report_periodstringoptional
Narrow the current-holders view to filers whose most recent reported position falls on this exact report date (YYYY-MM-DD, a calendar quarter-end). It filters the latest-per-filer set down to those filers; it does not back-date each filer to retrieve its historical position for an arbitrary past quarter.
report_period_gtestringoptional
Only positions with a report date on or after this date (YYYY-MM-DD). Also available: report_period_lte, report_period_gt, report_period_lt.
limitnumberoptional
Maximum number of holders to return, largest by value_usd first. Defaults to 1000.

Current holders#

Without a report_period, the response is the current institutional holders of the security. We define that precisely: one position per filer, taken from that filer’s most recent 13F that includes the ticker. When a filer reports both an ordinary long position and a derivative line (a put or call) on the same security in that filing, the main long position is the one returned. Holders are sorted by value_usd descending, so the largest reported position appears first.

Because each filer’s latest including-filing can be a different quarter, the rows in a current-holders response may carry different report_period values. Passing an explicit report_period filters this latest-per-filer set down to the filers whose most recent reported position falls on that date — filers whose latest report is a different quarter are dropped, not back-dated. This route does not retrieve every filer’s position for an arbitrary past quarter.

Example request#

curlbash
curl "https://api.focusalpha.ai/v1/institutional-holdings?ticker=AAPL" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

Response#

Returns the echoed ticker and an institutional_holdings array, sorted by reported value descending. Each row is one filer’s position in the security and carries the same fields as the by-investor view.

institutional_holding#

filer_cikstringrequired
Zero-padded CIK of the institutional manager that holds the security.
filer_namestringrequired
The manager's name as registered with the SEC.
sharesnumber | nullrequired
Shares held (or principal amount when share_type is PRN), summed across the filer’s subsidiary blocks for this security.
value_usdnumber | nullrequired
Reported market value of the filer's position in US dollars, as of its report date. The sort key.
reported_pricenumber | nulloptional
Implied per-share price (value_usd / shares). null for derivatives and PRN rows.
put_call"Put" | "Call" | nulloptional
null for the ordinary long position (the one returned by default); Put or Call for an options line.
share_type"SH" | "PRN"required
Whether shares is a share count (SH) or a principal amount (PRN).
report_periodstringrequired
The report date of the filer’s position (YYYY-MM-DD). In a current-holders response this can differ between filers.
ticker / name_of_issuer / title_of_classstring | nullrequired
The security’s identifiers, same as the by-investor view (ticker resolved from CUSIP). null when the value is not resolved or reported.
cusipstringrequired
CUSIP reported by the filer, same as the by-investor view.
filing_date / form_type / accession_numberstringrequired
The source filing’s submission date, type (13F-HR or 13F-HR/A), and SEC accession number.

Every row carries the full field set documented on the by-investor page — the two views share one row shape.

Example response#

institutional-holdings.jsonjson
{
  "ticker": "AAPL",
  "institutional_holdings": [
    {
      "ticker": "AAPL",
      "name_of_issuer": "APPLE INC",
      "cusip": "037833100",
      "title_of_class": "COM",
      "shares": 1426283914,
      "share_type": "SH",
      "value_usd": 387749544852,
      "reported_price": 271.86,
      "put_call": null,
      "report_period": "2025-12-31",
      "filing_date": "2026-02-11",
      "form_type": "13F-HR",
      "accession_number": "0000102909-26-000004",
      "filer_cik": "0000102909",
      "filer_name": "VANGUARD GROUP INC"
    }
  ]
}
Complete positions across subsidiary filers
A single 13F often splits one position across an institution’s subsidiary managers. We sum those blocks into one position per security per filing, so each holder’s shares and value_usd reflect its complete Form 13F position, not a single subsidiary line.
Who owns it, not how much of it
This is the institutional holders among our covered set of ~500 large managers — not the full shareholder register. Insiders, retail holders, and managers outside the covered set are not represented, and a null ticker means the security’s CUSIP couldn’t be mapped to a symbol.

Errors#

Statuses: 400 (neither ticker nor filer_cik supplied, both supplied at once, or a malformed date), 401 (bad or missing API key), 402 (per-minute rate limit or monthly quota exceeded — upgrade your plan), 404 (disabled route), 500, and 503 (holdings store temporarily unavailable, with a Retry-After header). The ticker is not validated for existence: an unknown ticker, like a known ticker that no covered filer reports holding, returns a successful 200 with an empty institutional_holdings array. See Errors.