> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beliefstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# get_institutional_holdings

> Get institutional holdings

**Get institutional holdings** · \$0.02 per call (x402, USDC)

Retrieves reported institutional holdings for one ticker across supported retained 13F history. Filter by manager name or CIK, report period, filing dates, amendments, share class and shares versus PUT/CALL positions. Returns typed quantities, native reported values, manager identities and source support. Identifier and filing-join checks hold ambiguous records; report dates differ from filing dates, and native value scales remain explicit. Current requests recheck stale mirror metadata; historical/pinned reads never switch snapshots. Continue with the returned snapshot ID/hash, as\_of, filters and cursor or next\_offset.

## Input parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cursor` | string | No | Archive continuation token; reuse with snapshot ID/hash, as\_of and unchanged filters. max length 4096 |
| `ticker` | string | Yes | |
| `as_of` | string | No | Availability cutoff, separate from event/period filters. Historical reads never refresh. |
| `snapshot_id` | string | No | Pin continuation to the returned snapshot ID; reuse with snapshot\_hash and as\_of. |
| `snapshot_hash` | string | No | |
| `filters_sha256` | string | No | Reuse the returned filter hash unchanged with continuation pages. |
| `offset` | integer | No | min 0; max 10000000 |
| `limit` | integer | No | Matching typed observations per page; default32. min 1; max 100 |
| `max_snapshot_age_hours` | number | No | Requested verification-age tolerance: default1hour for retained archives,24hours for closing-price references. Record dates and publication cadence are separate. max 87600 |
| `date_from` | string | No | Inclusive native date lower bound, selected by date\_field. |
| `date_to` | string | No | Inclusive native date upper bound, selected by date\_field. |
| `date_field` | "period" \| "report" | No | Date meaning; defaults to period for facts/macro/holdings/returns, event for insider trades, observation for options/short volume, scheduled for calendar. |
| `manager_cik` | string | No | |
| `manager_name` | string | No | min length 1; max length 128 |
| `report_period` | string | No | |
| `include_amendments` | boolean | No | |
| `put_call` | "PUT" \| "CALL" \| "SHARES" | No | Reported 13F position category; SHARES excludes PUT/CALL reports. |
| `share_class` | string | No | min length 1; max length 128 |

## Transports

* **MCP:** `tools/call` with name `get_institutional_holdings` at `https://beliefstate.ai/mcp` (account access) or `https://beliefstate.ai/v1/research/mcp` (wallet access). See [MCP integration](https://docs.beliefstate.ai/guides/mcp-server.md).
* **x402 HTTP:** `POST https://beliefstate.ai/v1/research/get_institutional_holdings` with the arguments as a JSON body. An unpaid request returns an HTTP 402 payment quote.

## Example request

### MCP

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_institutional_holdings",
    "arguments": {
      "ticker": "NVDA"
    }
  }
}
```

### x402 HTTP

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl --request POST \
  --url 'https://beliefstate.ai/v1/research/get_institutional_holdings' \
  --header 'Content-Type: application/json' \
  --data '{"ticker":"NVDA"}'
```

The example shows request shape only. Identifiers are placeholders, not records.

## Related

* [All research tools](https://docs.beliefstate.ai/tools/index.md)

*Contract version: 2026-11-08. Input parameters and tool metadata come from the
shared executable catalog. REST API version: v1.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.