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

# Institutional Holdings (SEC Form 13F)

> Real-time SEC Form 13F quarterly filings from institutional investment managers with $100M+ in qualifying assets. Covers 14,000+ institutions, 13,800+ securities, and 85M+ holdings rows with history back to Q1 1987.

<Info>**Python function:** `getInstitutionalHoldings()`</Info>

| Specification      | Value                                                             |
| ------------------ | ----------------------------------------------------------------- |
| Delivery Frequency | continuous, daily                                                 |
| Data Frequency     | quarterly                                                         |
| Reporting Lag      | Real-time from EDGAR stream (\< 1 min); daily backfill safety net |
| Coverage           | 14,000+ institutions, 13,800+ securities, SEC Form 13F            |
| History            | Since 1987-03-31                                                  |
| Availability       | Free                                                              |

# Product Overview

## Overview

Institutional Holdings provides structured, real-time data from SEC Form 13F filings — the quarterly disclosure that institutional investment managers exercising discretion over \$100 million or more in qualifying assets must file with the SEC. Each filing's holdings are flattened into per-security rows, enabling queries by ticker, institution, or time period.

The dataset contains **85M+ holdings rows** from **14,000+ unique institutions** covering **13,800+ securities**, with history back to **Q1 1987**.

## Data Pipeline & Latency

Scalar Field ingests 13F filings through two complementary paths:

* **Real-time stream:** A persistent connection to SEC EDGAR receives filing notifications within seconds of acceptance. Holdings and cover page data are fetched by accession number and written to the database.
* **Daily backfill:** A safety-net job runs daily, re-processing the last 3 calendar days of filings to catch anything missed by the real-time stream.
* **Bulk historical:** Full history back to 1987 is loaded from SEC-API's monthly archives.

### Quarterly Filing Volume (recent quarters)

| Quarter | Holdings Rows | Unique Filers |
| ------- | ------------- | ------------- |
| Q1 2024 | 2,119,125     | 7,378         |
| Q2 2024 | 2,122,293     | 7,388         |
| Q3 2024 | 2,408,137     | 7,432         |
| Q4 2024 | 2,560,532     | 8,143         |
| Q1 2025 | 2,584,750     | 8,094         |
| Q2 2025 | 2,579,984     | 8,107         |
| Q3 2025 | 2,586,847     | 8,034         |
| Q4 2025 | 2,920,349     | 8,604         |

Filing volume has grown steadily, with Q4 2025 seeing nearly 2.9M holdings rows from 8,600+ filers.

### Timestamp Semantics: `ts_recv` vs `filed_at` vs `period_of_report`

| Timestamp          | Meaning                                                                                                          | Use Case                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `ts_recv`          | When Scalar Field's pipeline first ingested the record (New York time). This is the **point-in-time** timestamp. | **Point-in-time backtesting.** Use this as your event timestamp to avoid look-ahead bias. |
| `filed_at`         | When the 13F filing was submitted to EDGAR (New York time).                                                      | **Filing-date analysis.** The official SEC submission timestamp.                          |
| `period_of_report` | The quarter-end date the filing covers (e.g., 2025-12-31 for Q4 2025).                                           | **Snapshot analysis.** Use to compare holdings across quarters.                           |

### Annual Volume (recent years)

| Year | Holdings Rows |
| ---- | ------------- |
| 2020 | 6,886,918     |
| 2021 | 8,324,009     |
| 2022 | 8,319,390     |
| 2023 | 8,368,360     |
| 2024 | 9,210,087     |
| 2025 | 10,671,930    |

## Coverage

* **Institutions:** 14,000+ unique filers (hedge funds, mutual funds, pension funds, insurance companies, bank trust departments, endowments). \~8,600 active filers per quarter in recent periods.
* **Securities:** 13,800+ unique tickers in recent quarters. Covers U.S. equity and equity-like securities (ETFs, closed-end funds, certain convertible instruments).
* **History:** Q1 1987 to present, with continuous real-time updates.
* **Filing frequency:** Quarterly (45 days after quarter-end). Most filings arrive in a concentrated window during the 6th week after quarter-end.

# Querying the Data

## Basic Usage

```python theme={null}
from scalarlib import getInstitutionalHoldings

# All funds holding AAPL in recent filings
df = getInstitutionalHoldings(ticker='AAPL', start='2025-01-01', end='2025-12-31')

# Berkshire Hathaway's full portfolio
df = getInstitutionalHoldings(institution_name='berkshire & hathaway', start='2025-01-01', end='2026-02-28')

# Bridgewater OR Citadel holdings of TSLA
df = getInstitutionalHoldings(ticker='TSLA', institution_name='bridgewater | citadel', start='2025-01-01', end='2026-02-28')

# Prefix match for institution names
df = getInstitutionalHoldings(institution_name='bridg:*', start='2025-01-01', end='2025-12-31')
```

## Parameters

| Parameter          | Type | Required | Description                                     |
| ------------------ | ---- | -------- | ----------------------------------------------- |
| `ticker`           | str  | No       | Stock ticker symbol to filter (e.g., `'AAPL'`). |
| `institution_name` | str  | No       | Fund or institution name.                       |
| `start`            | str  | Yes      | Start date (`YYYY-MM-DD`).                      |
| `end`              | str  | Yes      | End date (`YYYY-MM-DD`).                        |
| `date_column`      | str  | No       | `'filed_at'` (default) or `'ts_recv'`.          |

# Column Definitions

## Institutional Holdings Schema

| Column                  | Type     | Description                                                                         |
| ----------------------- | -------- | ----------------------------------------------------------------------------------- |
| `ts_recv`               | datetime | **Point-in-time timestamp:** when Scalar Field ingested the record (New York time). |
| `filed_at`              | datetime | When the 13F filing was submitted to EDGAR (New York time).                         |
| `fund_name`             | string   | Name of the institutional investment manager.                                       |
| `cik`                   | string   | SEC Central Index Key — unique identifier for the filing entity.                    |
| `ticker`                | string   | Ticker symbol of the held security.                                                 |
| `cusip`                 | string   | CUSIP identifier (9-character) for the security.                                    |
| `name_of_issuer`        | string   | Legal name of the security's issuer.                                                |
| `title_of_class`        | string   | Class of security (e.g., `COM`, `CL A`, `SH BEN INT`).                              |
| `value`                 | float    | Fair market value of the position in thousands of USD (as reported on the 13F).     |
| `shares`                | float    | Number of shares or principal amount held.                                          |
| `share_type`            | string   | Type of shares: `SH` (shares) or `PRN` (principal).                                 |
| `put_call`              | string   | For options: `Put`, `Call`, or null for equity positions.                           |
| `investment_discretion` | string   | `SOLE`, `DEFINED`, or `SHARED` — who has investment authority.                      |
| `voting_sole`           | integer  | Number of shares with sole voting authority.                                        |
| `voting_shared`         | integer  | Number of shares with shared voting authority.                                      |
| `voting_none`           | integer  | Number of shares with no voting authority.                                          |
| `period_of_report`      | date     | Quarter-end date the filing covers.                                                 |
| `form_type`             | string   | SEC form type (e.g., `13F-HR`, `13F-HR/A` for amendments).                          |
| `accession_no`          | string   | SEC EDGAR accession number — unique filing identifier.                              |