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

# Corporate Insider Transactions

> Near real-time SEC Form 3/4/5 insider buying and selling activity derived from EDGAR filings. Covers 5,300+ tickers and 97,000+ unique insiders with history back to January 2009. 87% of filings ingested within 5 minutes of SEC acceptance.

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

| Specification      | Value                                                        |
| ------------------ | ------------------------------------------------------------ |
| Delivery Frequency | continuous, daily                                            |
| Data Frequency     | event-driven                                                 |
| Reporting Lag      | 87% within 5 min of SEC acceptance; full coverage within 24h |
| Coverage           | 5,300+ U.S. equities, 97,000+ insiders, SEC Forms 3/4/5      |
| History            | Since 2009-01-02                                             |
| Availability       | Free                                                         |

# Product Overview

## Overview

Corporate Insider Transactions provides structured, near real-time data on insider buying and selling activity derived from SEC Forms 3, 4, and 5 (including amendments 3/A, 4/A, 5/A). The dataset captures non-derivative transactions — direct open-market purchases and dispositions — filed by corporate officers, directors, and beneficial owners (10%+ holders) of U.S. public companies.

The dataset contains **3.5M+ transactions** spanning **5,300+ tickers** and **97,000+ unique insiders**, with history back to **January 2009**.

## Data Pipeline & Latency

Scalar Field ingests insider filings through two complementary paths:

* **Real-time stream:** A persistent connection to SEC EDGAR receives filing notifications within seconds of acceptance. Structured transaction data is fetched by accession number and written to the database. If the data is not yet available, the system retries automatically until it arrives.
* **Daily reconciliation:** A batch job runs each morning, performing an incremental pull by ticker to catch any filings missed by the real-time stream or delayed in SEC indexing.

### Ingestion Latency (last 7 days)

The gap between when the SEC accepts a filing (`filed_at`) and when it appears in Scalar Field (`ts_recv`):

| Lag          | % of filings |
| ------------ | ------------ |
| \< 1 minute  | 73%          |
| 1–5 minutes  | 14%          |
| 5–60 minutes | 9%           |
| 1–24 hours   | 4%           |
| > 24 hours   | 0%           |

**87% of filings are ingested within 5 minutes of SEC acceptance.** The remaining \~13% are typically filings where the SEC API indexes the structured data with a short delay; these are caught by automatic retries or, in rare cases, the daily batch reconciliation.

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

This distinction is critical for backtesting and signal construction:

| Timestamp         | Meaning                                                                                                                                                                            | Use Case                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `ts_recv`         | When Scalar Field's pipeline first ingested the record (UTC → New York time). This is the **point-in-time** timestamp — the earliest moment this data was available in the system. | **Point-in-time backtesting.** Use this as your event timestamp to avoid look-ahead bias.             |
| `filed_at`        | When the SEC filing was officially accepted by EDGAR (UTC → New York time).                                                                                                        | **Regulatory timing analysis.** Measures the insider's filing delay relative to the transaction.      |
| `transactionDate` | The actual date the insider executed the trade.                                                                                                                                    | **Event studies.** The true economic event date — but note this is only known after the filing lands. |

### Insider Filing Delay (transaction date → SEC filing, last 7 days)

How long after the actual trade do insiders file with the SEC:

| Delay    | % of filings |
| -------- | ------------ |
| Same day | 4%           |
| 1 day    | 19%          |
| 2 days   | 44%          |
| 3–5 days | 29%          |
| > 5 days | 5%           |

Insiders are required to file Form 4 within **2 business days** of the transaction. In practice, \~67% comply within 2 days, while \~33% file later. This means that even with a perfect real-time feed, there is an inherent information delay between when an insider trades and when the market can observe it.

## Coverage

* **Universe:** 5,300+ U.S.-listed equities with SEC insider filings (NYSE, NASDAQ, AMEX, OTC issuers).
* **Insiders:** 97,000+ unique filing insiders.
* **Filing types:** Forms 3 (initial statement of beneficial ownership), 4 (changes in ownership), and 5 (annual summary), plus their amendments (3/A, 4/A, 5/A).
* **Transaction filter:** Only non-derivative transactions with acquired/disposed codes — `Buy` (A) and `Sell` (D). Derivative transactions (option exercises, conversions) are excluded.
* **History:** January 2009 to present, with continuous daily updates.
* **Volume:** \~1,500 transactions/day on average; \~270K/year in recent years.

### Annual Volume

| Year | Transactions |
| ---- | ------------ |
| 2009 | 134,566      |
| 2010 | 156,020      |
| 2011 | 152,509      |
| 2012 | 165,646      |
| 2013 | 170,764      |
| 2014 | 171,229      |
| 2015 | 171,205      |
| 2016 | 171,877      |
| 2017 | 181,639      |
| 2018 | 197,736      |
| 2019 | 205,018      |
| 2020 | 234,433      |
| 2021 | 294,368      |
| 2022 | 241,628      |
| 2023 | 245,931      |
| 2024 | 274,757      |
| 2025 | 271,592      |

## Buy/Sell Split

Across the full dataset: **49% Buy** / **51% Sell**, roughly balanced.

# Querying the Data

## Basic Usage

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

# All AAPL insider trades in 2024
df = getInsiderTradesData('AAPL', '2024-01-01', '2024-12-31')

# Multiple tickers
df = getInsiderTradesData(['AAPL', 'MSFT', 'NVDA'], '2024-01-01', '2024-12-31')

# All tickers (universe-wide scan)
df = getInsiderTradesData(None, '2024-06-01', '2024-06-30')
```

## Filtering by Insider

```python theme={null}
# Filter by insider name
df = getInsiderTradesData('AAPL', '2020-01-01', '2024-12-31', insider_name='Tim Cook')

# Filter by role (supports abbreviations: CEO, CFO, COO, CTO, director, VP, etc.)
df = getInsiderTradesData(None, '2024-01-01', '2024-12-31', insider_role='CEO')
```

## Parameters

| Parameter      | Type               | Required | Description                                         |
| -------------- | ------------------ | -------- | --------------------------------------------------- |
| `tickers`      | str, list, or None | No       | Stock symbol(s). `None` returns all tickers.        |
| `start`        | str                | Yes      | Start date (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`). |
| `end`          | str                | Yes      | End date (same format; date-only is inclusive).     |
| `insider_name` | str                | No       | Insider name.                                       |
| `insider_role` | str                | No       | Insider role or position (e.g. CEO, director).      |

# Column Definitions

## Insider Trades Schema

| Column                  | Type     | Description                                                                                                                                                             |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ts_recv`               | datetime | **Point-in-time timestamp:** when Scalar Field ingested the record (New York time). Use this for backtesting to avoid look-ahead bias.                                  |
| `filed_at`              | datetime | SEC filing acceptance timestamp (New York time). When the Form 3/4/5 was officially filed with EDGAR.                                                                   |
| `symbol`                | string   | Ticker symbol of the issuer (e.g., AAPL, MSFT).                                                                                                                         |
| `transactionAmount`     | float    | Number of shares transacted.                                                                                                                                            |
| `transactionPrice`      | float    | Price per share at which the transaction was executed (USD).                                                                                                            |
| `transactionType`       | string   | SEC transaction code (S = open-market sale, P = open-market purchase, A = grant/award, M = exercise/conversion, F = tax withholding, etc.).                             |
| `side`                  | string   | Direction: `Buy` (acquired) or `Sell` (disposed).                                                                                                                       |
| `transactionDate`       | date     | Calendar date the insider executed the trade.                                                                                                                           |
| `name`                  | string   | Full name of the insider as reported in the SEC filing.                                                                                                                 |
| `typeOfOwner`           | string   | Relationship to issuer (e.g., "Chief Executive Officer", "Director", "10% Owner").                                                                                      |
| `postTransactionAmount` | float    | Shares held by the insider after the transaction.                                                                                                                       |
| `securityTitle`         | string   | Description of the security (e.g., "Common Stock").                                                                                                                     |
| `issuerName`            | string   | Legal name of the issuing company.                                                                                                                                      |
| `accessionNo`           | string   | SEC EDGAR accession number — unique filing identifier. Construct the EDGAR URL as `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&accession={accessionNo}`. |

## Transaction Type Codes

| Code | Meaning                                                  | Count  |
| ---- | -------------------------------------------------------- | ------ |
| S    | Open-market or private sale                              | 1,070K |
| A    | Grant, award, or other acquisition                       | 724K   |
| F    | Payment of exercise price or tax liability (withholding) | 547K   |
| M    | Exercise or conversion of derivative security            | 546K   |
| P    | Open-market or private purchase                          | 296K   |
| J    | Other acquisition or disposition                         | 114K   |
| G    | Gift                                                     | 105K   |
| D    | Disposition to the issuer                                | 55K    |
| C    | Conversion of derivative security                        | 49K    |

# Filtering Reference

## Insider Role Filter

The `insider_role` parameter supports these abbreviations and their expansions:

| Abbreviation         | Matches                                   |
| -------------------- | ----------------------------------------- |
| `CEO`                | Chief Executive Officer                   |
| `CFO`                | Chief Financial Officer                   |
| `COO`                | Chief Operating Officer                   |
| `CTO`                | Chief Technology Officer                  |
| `CIO`                | Chief Information Officer                 |
| `President`          | President                                 |
| `Director`           | Director                                  |
| `VP` / `SVP` / `EVP` | Vice President / Senior VP / Executive VP |
| `Chairman`           | Chairman, Chair                           |
| `General Counsel`    | General Counsel, GC                       |
| `Controller`         | Controller                                |
| `Treasurer`          | Treasurer                                 |
| `Secretary`          | Secretary, Corp Sec                       |
| `10% Owner`          | 10% Owner, Beneficial Owner               |

Unrecognized role strings are matched as literal substrings against the `typeOfOwner` field.