# Institutional Holdings

`GET` `https://api.unusualwhales.com/api/institution/{name}/holdings`

Returns the holdings for a given institution.

WARNING: Providing partial names e.g. "VANGUARD" might lead to unexpected results.
To ensure you get the expected result, it is recommended to use the company CIK (e.g. 0000102909 for VANGUARD GROUP INC) as the name parameter.

You can use endpoint "api/institutions" with a partial name like "VANGUARD" to get all matching institutions with their CIKs.


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | Institution | Yes | A large entity that manages funds and investments for others. Queryable by name or cik. |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticker_symbol` | Ticker | No | A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. |
| `date` | Optional Market Date | No | A trading date in the format of YYYY-MM-DD.
This is optional and by default the last trading date.
 |
| `start_date` | Institutional Report Start Date | No | A date in the format of YYYY-MM-DD, only institutional holdings with `report_date` values on or after this date will be returned.
 |
| `end_date` | Institutional Report End Date | No | A date in the format of YYYY-MM-DD, only institutional holdings with `report_date` values on or before this date will be returned.
 |
| `security_types` | Security Types | No | An array of security types |
| `limit` | Default 500 Max 500 Min 1 | No | How many items to return. Default: 500. Max: 500. Min: 1. |
| `page` | Page | No | Page number (use with limit). Starts on page 0. |
| `order` | Institutional Holdings Order By | No | Optional columns to order the result by |
| `order_direction` | OrderDirection | No | Whether to sort descending or ascending. Descending by default. |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `avg_price` | Avg Price |  |
| `close` | Stock Close Price |  |
| `date` | General ISO Date |  |
| `first_buy` | General ISO Date |  |
| `full_name` | Full Name |  |
| `historical_units` | Historical Units |  |
| `perc_of_share_value` | Perc of Share Value |  |
| `perc_of_total` | Perc of Total |  |
| `price_first_buy` | Price First Buy |  |
| `put_call` | PutCall |  |
| `sector` | Sector |  |
| `security_type` | Security Type |  |
| `shares_outstanding` | Shares Outstanding |  |
| `ticker` | Ticker Symbol |  |
| `units` | Units |  |
| `units_change` | Units Change |  |
| `value` | Value |  |


## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/institution/{name}/holdings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/institution/{name}/holdings", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": [
    {
      "avg_price": "156.53",
      "close": "419.23",
      "date": "2024-10-02",
      "first_buy": "2012-02-23",
      "full_name": "MICROSOFT CORP",
      "historical_units": [
        4103,
        4423
      ],
      "perc_of_share_value": 0.04,
      "perc_of_total": 0.002,
      "price_first_buy": "23.42",
      "put_call": null,
      "sector": "Technology",
      "security_type": "Share",
      "shares_outstanding": "71984388.0",
      "ticker": "MSFT",
      "units": 4103,
      "units_change": -320,
      "value": 1672230
    },
    {
      "avg_price": "359.21",
      "close": "568.23",
      "date": "2024-10-02",
      "first_buy": "2019-12-15",
      "full_name": "ADOBE INC",
      "historical_units": [
        500,
        0
      ],
      "perc_of_share_value": 0.04,
      "perc_of_total": 0.002,
      "price_first_buy": "239.33",
      "put_call": null,
      "sector": "Technology",
      "security_type": "Share",
      "shares_outstanding": "6714388.0",
      "ticker": "ADBE",
      "units": 500,
      "units_change": 500,
      "value": 250000
    }
  ]
}
```