Institutional holdings

GET /v1/securities/{symbol}/institutional-holders serves institutional investment managers' quarter-end holdings of the security, as reported on SEC Form 13F. Each answer states how complete the quarter is.

Routes

what	route
13F holdings of a security	GET /v1/securities/{symbol}/institutional-holders

curl "https://api.tauric.ai/v1/securities/AAPL/institutional-holders?period=2026-06-30&limit=10" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

13F covers long positions only (no short positions), reported up to 45 days after the quarter. The filings served are those made over about the last two years; coverage.periods lists the quarters.

Rows and double counting

Each row is one line of one filing, so adding rows up can count the same holding more than once:

• a line can be a share position or an option position. A put or call line's value is the underlying's, not shares held; position=shares keeps share lines only;
• one manager can appear on several rows: filings by affiliated filing entities, several lines of one filing, or a filing served beside one whose relation is unresolved (view_state: conflict_unresolved); each row names its filing (accession, amendment, view_state);
• a combination report can include positions that an included manager also reports in its own filing (other_managers_also_filing).

To build a top-holder view, start from share lines in filings with view_state: current, and decide how to treat affiliated filers yourself.

Periods and completeness

period is a calendar quarter end; a future quarter or a date that is not a quarter end is refused (422). The default is the newest complete quarter, or the newest quarter served when none is.

coverage.period_state says how much of the period's filing span, from the day after the quarter end to its 45-day deadline, is served:

period_state	meaning
complete	every filing day of the span is served, as published. A manager that did not file is absent
partial	part of the span is served
not_covered	none of it is served

coverage.periods lists the quarters served, newest first, each with its state (complete or partial).

coverage.filed_through is the last filing date served for the period; a filing made later is not served yet. It is null when the days right after the quarter end are not served. Late filings and amendments can arrive after the deadline.

For a not_covered quarter, late filings and amendments of it made inside a served span are still served, labeled. Read them as individual filings, not as that quarter's holders.

Page layout

• data: one row per filing and holding line, ordered by value as filed, descending;
• filings: each filing on the page once, by accession, with the manager (CIK and name), the filing date, the report type, the amendment, the included managers its lines on this page cite, its flags, and security_totals.

other_managers_count is the full count of included managers; merging pages merges the cited lists.

security_totals sums that one filing's lines in the security by kind (shares, principal, value of the non-option lines; option lines are counted, never added), over all its lines on every page, and regardless of the position filter. It is null on a filing that is not part of the current report.

The filters are position and manager_cik. position is shares, options, or all (default). Under all, option lines rank by the underlying's notional, so a top-N can be led by market makers' hedges.

Served filings

Each manager's current report for the period is served: the latest original or restatement, plus new-holdings amendments filed after it (view_state: current). Superseded filings are not served.

An amendment that cannot be combined with the current report is served beside it as conflict_unresolved. Never add the two.

Values and flags

Values are as filed, unconverted, in the filing's own value_unit: dollars for filings made from 2023-01-03, thousands before. An option line's amount can be in contracts rather than shares.

A filing's flags never change a filed value:

• value_unit_suspect: the values may be in another unit; check it before comparing with other filings.
• duplicate_table: another manager filed the same holdings table; count it once.
• cusip_invalid: some of the filing's lines carry an invalid CUSIP and are served for no security; its holdings may be incomplete.
• suspected_restatement_mislabeled: read the filing as a replacement of its base report; never add the two.

CUSIP coverage

Holdings are served for the security through its share class's CUSIPs (coverage.cusips). A holding under any other CUSIP, including an old one changed by a corporate action, is not served for the security.

coverage.cusip_state	meaning
matched	at least one CUSIP matched
not_matched_yet	no CUSIP is matched yet; this does not mean the security has none
not_matched	no 13F CUSIP resolves to this share class
no_share_class_figi	the security has no share-class FIGI, so no CUSIP can be matched to it

ambiguous_cusips lists CUSIPs that name this security among several; they are not served.

Lines filed under an old CUSIP are not served, so a quarter can be incomplete even when cusip_state is matched and period_state is complete. When coverage.historical_cusips.state is unidentified_lines_present, read the holders and totals as incomplete; candidate_cusips and candidate_lines name those lines.

Point in time

known_at is not offered (422): 13F filings carry no acceptance time.