# 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.

If you are looking to build a database of insitutional positions use https://unusualwhales.com/skills/institutional.md


## 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 | The close stock price of the ticker. |
| `date` | General ISO Date | An ISO date. |
| `first_buy` | General ISO Date | An ISO date. |
| `full_name` | Full Name |  |
| `historical_units` | Historical Units | Historical unit counts. Maximum length = 8. |
| `perc_of_share_value` | Perc of Share Value | The percentage of the total share value of this institution that this holding represents. For example, if the sum of all the institution's holdings total $100 million and this holding has reported value $4 million, then the perc_of_share_value result will be 0.04. |
| `perc_of_total` | Perc of Total | The percentage of the total outstanding shares owned by this institution. For example, if there are 500 million outstanding shares and this institution owns 1 million shares, then the perc_of_total result will be 0.002. |
| `price_first_buy` | Price First Buy | The close price of the ticker on the first buy date. |
| `put_call` | PutCall | Whether the holding is a put or a call (null if neither). |
| `sector` | Sector | A financial sector. |
| `security_type` | Security Type |  |
| `shares_outstanding` | Shares Outstanding | Total outstanding shares for the ticker. |
| `ticker` | Ticker Symbol |  |
| `units` | Units |  |
| `units_change` | Units Change | The change in units |
| `value` | Value | The rounded total value on the reporting date. |


## 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
    }
  ]
}
```