Institutional ownership

Query institutional stock positions and quarterly aggregates.

GET/api/v1/ownership/institutional
Domain
Flows & Wallets
Level
Asset identification
MCP tool
ownership_flows_query (task=institutional)

Available data

Returns
Institutional positions or quarterly aggregates
Market coverage
Institutional positions: US stocks. Quarterly totals: US and HK stocks.
What each request returns
View positions by institution or quarterly totals; the latest period is returned when no date is selected.

Authentication

Send Authorization: Bearer YOUR_API_KEY or X-API-KEY on every request.

Query Parameters

Asset identification

Provide at least one of asset_id or query. query also requires market

asset_idstringqueryconditional

Asset identifier for stocks, crypto assets and other asset objects

querystringqueryconditional

Stock or ETF ticker/name; market is required when using query

Market

Required with query; optional with asset_id

marketstringqueryconditional

Required with query; optional when asset_id identifies the subject. Institutional positions: US stocks. Quarterly totals: US and HK stocks

Filters and pagination

Positions support US stocks; quarterly totals support US and HK stocks. Selecting HK switches the view to quarterly totals

asset_classstringqueryoptional

Asset class for disambiguation; cannot override the endpoint subject type

viewstringqueryoptional

holders (default) for institutional rows; summary for quarterly aggregates

periodstringqueryoptional

summary only: YYYY/Q1–YYYY/Q4; omit for the latest available quarter

holder_namestringqueryoptional

holders only: filter by institution name

fromdatequeryoptional

Inclusive start date: reporting date for institutional rows, trade date for other lists

todatequeryoptional

Inclusive end date; must not precede from

pageintegerqueryoptional

Page number, starting at 1; defaults to 1

page_sizeintegerqueryoptional

Defaults to 50, maximum 100; explicitly set 20 if preferred

Response

request_idstringExample3f80785d-e708-4aa9-b8a6-a266c2351fed

Request trace ID

resolution_statusResolutionStatusExampleresolved

Object resolution status

data_statusDataStatusExampleok

Data status

dataobject

Business data

viewstringExampleholders

Returned view: holders or summary

historyobject

Reporting period range on this page

fromdateExample2026-09-30

Earliest reporting date on this page

todateExample2026-09-30

Latest reporting date on this page

period_countintegerExample1

Reporting periods on this page

items[]object[]

Business records

holder_namestringExample10Elms Llp

Institution name

as_of_datedateExample2026-09-30

Reporting date; a single batch for fund holdings

shares_heldnumberExample1078

Current shares held

shares_changenumber | nullExample-54

Share change versus the same holder’s previous available quarter

shares_change_pctnumber | nullExample-4.770318

Quarterly share change (%)

change_base_datedate | nullExample2026-06-30

Baseline date for share changes

market_valuenumber | nullExample384

Position value, in the unit specified by market_value_unit

market_value_unitstringExampleUSD_THOUSAND

Value unit; USD_THOUSAND means thousands of USD

period_keystring

Quarter key (summary)

period_end_datedate

Quarter-end date (summary)

institutional_holding_pctnumber

Institutional ownership ratio, 0–1 (summary)

institutional_holding_quantitynumber

Total institutional shares (summary)

institution_countinteger

Institution count (summary)

institutional_holding_pct_changenumber

Ownership ratio change in decimal form (summary)

institutional_holding_quantity_changenumber

Quarterly total share change (summary)

institution_count_changeinteger

Quarterly institution count change (summary)

change_base_period_keystring

Baseline quarter (summary)

periodstring

Returned quarter, YYYY/Qn

metadataobject

Pagination, freshness and limitations

object_refs[]object[]

GateData object references

typeObjectRefTypeExampleasset

Object type

idstringExampleasset_aapl_common_stock

Object ID

paginationobject

Pagination

pageintegerExample1

Current page

page_sizeintegerExample2

Page size

totalintegerExample5542

Total matching records

source_refs[]object[]

Source tracking array

ref_idstringExamplesrc_4ab0eaf5f1fadcac5a94a2b39563d414

Source tracking ID

observed_atdatetime

Data observation time

updated_atdatetimeExample2026-11-16T05:50:29.000+0000

Data update time (UTC)

limitations[]string[]

Additional information

errorobject | null

Error object; null on success

Errors & fallback

200
The request was processed and query results are returned.
400
Missing identity, conflicting parameters, invalid enum/date/range or quarter (YYYY/Qn).
404
Object not found or ambiguous; refine identity.
422
Market or asset type not supported.
503
The requested data is temporarily unavailable.
502
Upstream error without usable cached data.