### Install Earnings Feed Python SDK

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Install the SDK using pip. This is the first step to using the library.

```bash
pip install earningsfeed
```

--------------------------------

### Quick Start: Get Recent Filings and Company Profile

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Initialize the client with your API key and fetch recent 10-K/10-Q filings or a company profile. Demonstrates basic client usage.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Get recent 10-K and 10-Q filings
filings = client.filings.list(forms=["10-K", "10-Q"], limit=10)
for filing in filings.items:
    print(f"{filing.form_type}: {filing.company_name} - {filing.title}")

# Get a company profile
apple = client.companies.get(320193)
print(f"{apple.name} ({apple.primary_ticker})")
```

--------------------------------

### Install Earnings Feed Python SDK

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Install the SDK using pip or uv. Ensure you are using Python 3.9+.

```bash
pip install earningsfeed
```

```bash
# or
uv add earningsfeed
```

--------------------------------

### Get Company Profile using client.companies.get()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a full company profile by its SEC CIK. Requires an initialized EarningsFeed client with an API key.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

company = client.companies.get(320193)  # Apple Inc.

print(f"Name:        {company.name}")
print(f"Ticker:      {company.primary_ticker}")
print(f"Entity Type: {company.entity_type}")
print(f"FYE:         {company.fiscal_year_end}")
print(f"Website:     {company.website}")
print(f"Has insiders: {company.has_insider_transactions}")

print("\nAll tickers:")
for ticker in company.tickers:
    primary = " (primary)" if ticker.is_primary else ""
    print(f"  {ticker.symbol} on {ticker.exchange}{primary}")

print("\nSIC codes:")
for sic in company.sic_codes:
    print(f"  {sic.code}: {sic.description}")

print("\nAddresses:")
for addr in company.addresses:
    print(f"  [{addr.type}] {addr.street1}, {addr.city}, {addr.state_or_country} {addr.zip_code}")
```

--------------------------------

### Get Filing Detail using client.filings.get()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch full metadata and document list for a single filing by accession number. Handles NotFoundError if the filing is not found.

```python
from earningsfeed import EarningsFeed, NotFoundError

client = EarningsFeed("your_api_key")

try:
    detail = client.filings.get("0000320193-24-000123")

    print(f"Form: {detail.form_type}")
    print(f"Filed: {detail.filed_at}")
    print(f"Company: {detail.company_name} (CIK {detail.cik})")
    print(f"SEC URL: {detail.url}")

    print("\nDocuments:")
    for doc in detail.documents:
        marker = "★" if doc.is_primary else " "
        print(f"  {marker} [{doc.seq}] {doc.doc_type}: {doc.filename}")

    print("\nRoles:")
    for role in detail.roles:
        print(f"  CIK {role.cik}: {role.role}")

except NotFoundError:
    print("Filing not found — check the accession number format")
```

--------------------------------

### Get Company Profile Details

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Fetch detailed information about a company using its CIK. Includes name, primary ticker, and SIC code descriptions.

```python
# Get company profile
company = client.companies.get(320193)
print(f"{company.name}")
print(f"Ticker: {company.primary_ticker}")
print(f"Industry: {company.sic_codes[0].description}")
```

--------------------------------

### Get Filing Detail

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch full metadata and document list for a single filing by accession number.

```APIDOC
## Get Filing Detail — `client.filings.get()`

### Description
Fetch full metadata and document list for a single filing by accession number.

Returns a `FilingDetail` including all `documents` (each with `filename`, `doc_type`, `is_primary`) and `roles` (filer, issuer, reporting-owner, etc.).

### Method Signature
`FilingsResource.get(accession)`

### Parameters
#### Path Parameters
- **accession** (string) - Required - The accession number of the filing.

### Request Example
```python
from earningsfeed import EarningsFeed, NotFoundError

client = EarningsFeed("your_api_key")

try:
    detail = client.filings.get("0000320193-24-000123")

    print(f"Form: {detail.form_type}")
    print(f"Filed: {detail.filed_at}")
    print(f"Company: {detail.company_name} (CIK {detail.cik})")
    print(f"SEC URL: {detail.url}")

    print("\nDocuments:")
    for doc in detail.documents:
        marker = "★" if doc.is_primary else " "
        print(f"  {marker} [{doc.seq}] {doc.doc_type}: {doc.filename}")

    print("\nRoles:")
    for role in detail.roles:
        print(f"  CIK {role.cik}: {role.role}")

except NotFoundError:
    print("Filing not found — check the accession number format")
```

### Response
#### Success Response (200)
- **FilingDetail** - An object containing filing metadata, documents, and roles.
  - **form_type** (string)
  - **filed_at** (string)
  - **company_name** (string)
  - **cik** (string)
  - **url** (string)
  - **documents** (list of Document objects)
    - **filename** (string)
    - **doc_type** (string)
    - **is_primary** (boolean)
    - **seq** (integer)
  - **roles** (list of Role objects)
    - **cik** (string)
    - **role** (string)

#### Error Response
- **NotFoundError**: If the filing is not found.
```

--------------------------------

### Get SEC Filing Details and Documents

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Retrieve detailed information for a specific filing using its accession number. Access associated documents like 10-K, 10-Q, etc.

```python
# Get filing details with documents
detail = client.filings.get("0000320193-24-000123")
for doc in detail.documents:
    print(f"{doc.doc_type}: {doc.filename}")
```

--------------------------------

### Get Company Profile

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a full company profile using its CIK. The returned Company object contains details like tickers, addresses, and insider transaction flags.

```APIDOC
## Get Company Profile — `client.companies.get()`

### Description
Fetch full company profile by SEC CIK.

Returns a `Company` object with tickers, SIC codes, addresses, fiscal year end, website links, and flags for insider/institutional activity.

### Method
`CompaniesResource.get(cik)`

### Parameters
#### Path Parameters
- **cik** (int) - Required - The Central Index Key (CIK) of the company.

### Response
#### Success Response (200)
- **Company** (object) - An object containing detailed company information.
  - **name** (str)
  - **primary_ticker** (str)
  - **entity_type** (str)
  - **fiscal_year_end** (str)
  - **website** (str)
  - **has_insider_transactions** (bool)
  - **tickers** (list[Ticker])
  - **sic_codes** (list[SICCode])
  - **addresses** (list[Address])

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")
company = client.companies.get(320193)  # Apple Inc.

print(f"Name: {company.name}")
print(f"Ticker: {company.primary_ticker}")
```

### Response Example
```json
{
  "name": "Apple Inc.",
  "primary_ticker": "AAPL",
  "entity_type": "operating",
  "fiscal_year_end": "09-30",
  "website": "https://www.apple.com",
  "has_insider_transactions": true,
  "tickers": [
    {
      "symbol": "AAPL",
      "exchange": "NASDAQ",
      "is_primary": true
    }
  ],
  "sic_codes": [
    {
      "code": "3571",
      "description": "Electronic Computers"
    }
  ],
  "addresses": [
    {
      "type": "mailing",
      "street1": "ONE APPLE PARK WAY",
      "city": "CUPERTINO",
      "state_or_country": "CA",
      "zip_code": "95014"
    }
  ]
}
```
```

--------------------------------

### Initialize EarningsFeed Client

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Instantiate the main API client with your API key. Optionally configure the base URL and timeout. The client can be used as a context manager for automatic connection cleanup.

```python
from earningsfeed import EarningsFeed

# Basic initialization
client = EarningsFeed("your_api_key")

# Custom timeout
client = EarningsFeed("your_api_key", timeout=60.0)

# Context manager — connection is closed automatically on exit
with EarningsFeed("your_api_key") as client:
    filings = client.filings.list(ticker="AAPL", limit=5)
    for f in filings.items:
        print(f"{f.form_type}: {f.title}")
    # Output:
    # 10-K: Apple Inc. Annual Report
    # 10-Q: Apple Inc. Quarterly Report
    # ...
```

--------------------------------

### Client Initialization

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Instantiate the EarningsFeed client with your API key. Optionally override the base URL or timeout. The client can be used as a context manager for automatic connection cleanup.

```APIDOC
## Client Initialization

`EarningsFeed(api_key, *, base_url, timeout)` — Create the main API client.

Instantiate the client with your API key. Optionally override `base_url` or `timeout` (default 30 seconds). The client is also a context manager for automatic connection cleanup.

```python
from earningsfeed import EarningsFeed

# Basic initialization
client = EarningsFeed("your_api_key")

# Custom timeout
client = EarningsFeed("your_api_key", timeout=60.0)

# Context manager — connection is closed automatically on exit
with EarningsFeed("your_api_key") as client:
    filings = client.filings.list(ticker="AAPL", limit=5)
    for f in filings.items:
        print(f"{f.form_type}: {f.title}")
    # Output:
    # 10-K: Apple Inc. Annual Report
    # 10-Q: Apple Inc. Quarterly Report
    # ...
```
```

--------------------------------

### Iterate Through All SEC Filings (Auto-Pagination)

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Use the `.iter()` method to automatically paginate and retrieve all filings matching the specified criteria, such as form type.

```python
# Iterate through all filings (auto-pagination)
for filing in client.filings.iter(ticker="AAPL", forms="8-K"):
    print(filing.title)
```

--------------------------------

### Iterate Institutional Holdings using client.institutional.iter()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all matching 13F holdings with automatic pagination. Useful for retrieving full portfolios or tracking ownership over time.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Full Berkshire Hathaway (CIK 1067983) 13F portfolio for Q4 2023
portfolio = []
for holding in client.institutional.iter(
    manager_cik=1067983,
    report_period="2023-12-31",
):
    portfolio.append(holding)

```

--------------------------------

### List SEC Filings with Filters

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Fetch SEC filings by specifying parameters like ticker, form types, and status. Use 'limit' to control the number of results.

```python
# List filings with filters
filings = client.filings.list(
    ticker="AAPL",
    forms=["10-K", "10-Q", "8-K"],
    status="final",
    limit=25,
)
```

--------------------------------

### Use Earnings Feed Client as a Context Manager

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Utilize the `with` statement for automatic resource management. The client connection is automatically closed upon exiting the block.

```python
with EarningsFeed("your_api_key") as client:
    filings = client.filings.list(limit=10)
    # Connection automatically closed when exiting the block
```

--------------------------------

### Search Companies using client.companies.search()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Search for companies based on various criteria like SIC code, state, and insider transaction activity. Returns a paginated response.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Find California-based software companies with insider filing activity
results = client.companies.search(
    sic_code=7372,                    # Prepackaged software
    state="CA",
    has_insider_transactions=True,
    limit=10,
)

print(f"Found {len(results.items)} results (more: {results.has_more})")
for co in results.items:
    print(f"  CIK {co.cik:>10} | {co.ticker or 'N/A':<6} | {co.name}")
```

--------------------------------

### Iterate Insider Transactions using client.insider.iter()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all matching insider transactions with automatic pagination. Useful for tracking specific individuals or market-wide trends.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Track all transactions by Warren Buffett (CIK 315090) across all companies
for txn in client.insider.iter(insider_cik=315090):
    direction = "BUY" if txn.acquired_disposed == "A" else "SELL"
    print(
        f"[{direction}] {txn.company_name} | {txn.transaction_date} | "
        f"{txn.shares:,} shares | Code: {txn.transaction_code}"
    )

# All market-wide insider sales > $1M (equity only, no derivatives)
for txn in client.insider.iter(
    direction="sell",
    derivative=False,
    min_value=1_000_000,
    start_date="2024-01-01",
):
    print(f"{txn.company_name}: ${txn.transaction_value:,.0f} by {txn.person_name}")
```

--------------------------------

### Error Handling

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Demonstrates how to handle various exceptions raised by the EarningsFeed SDK, including retries for rate limiting.

```APIDOC
## Error Handling

All exceptions inherit from `EarningsFeedError`. Import and catch specific types for precise handling.

### Exception Hierarchy
- `EarningsFeedError` (Base exception)
  - `AuthenticationError`
  - `RateLimitError`
  - `NotFoundError`
  - `ValidationError`
  - `APIError`

### Usage Example
```python
from earningsfeed import (
    EarningsFeed,
    EarningsFeedError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    APIError,
)
import time

client = EarningsFeed("your_api_key")

def safe_get_filing(accession: str):
    retries = 3
    for attempt in range(retries):
        try:
            return client.filings.get(accession)

        except AuthenticationError:
            print("Invalid API key — check your credentials")
            raise  # Non-retryable

        except NotFoundError:
            print(f"Filing {accession!r} does not exist")
            return None  # Non-retryable

        except RateLimitError as e:
            wait = (e.reset_at - time.time()) if e.reset_at else 60
            print(f"Rate limited. Waiting {wait:.0f}s before retry {attempt + 1}/{retries}")
            time.sleep(max(wait, 1))

        except ValidationError as e:
            print(f"Bad request parameters: {e}")
            raise  # Non-retryable

        except APIError as e:
            print(f"API error {e.status_code} ({e.code}): {e}")
            if attempt < retries - 1:
                time.sleep(2 ** attempt)

        except EarningsFeedError as e:
            print(f"Unexpected SDK error: {e}")
            raise

    return None

detail = safe_get_filing("0000320193-24-000123")
if detail:
    print(f"Got filing: {detail.title}")
```
```

--------------------------------

### Iterate Company Search using client.companies.iter_search()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all company search results across multiple pages. Useful for collecting all companies matching specific criteria.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Collect all SEC-registered financial institutions
banks = list(client.companies.iter_search(sic_code=6022))  # State commercial banks
print(f"Total state commercial banks on SEC: {len(banks)}")
for bank in banks[:5]:
    print(f"  {bank.name} ({bank.ticker or 'no ticker'})")
```

--------------------------------

### List SEC Filings with Filters

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a single page of SEC filings using optional filters like ticker, form types, date range, and status. Returns a response object with items, next cursor, and a flag for more data.

```python
from datetime import date
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Fetch AAPL's final 10-K and 10-Q filings in 2024
response = client.filings.list(
    ticker="AAPL",
    forms=["10-K", "10-Q"],
    status="final",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 12, 31),
    limit=10,
)

print(f"Total fetched: {len(response.items)}, more available: {response.has_more}")
for filing in response.items:
    print(f"[{filing.filed_at.date()}] {filing.form_type}: {filing.title} — {filing.url}")

# Manual pagination
if response.has_more:
    next_page = client.filings.list(
        ticker="AAPL",
        forms=["10-K", "10-Q"],
        cursor=response.next_cursor,
        limit=10,
    )
```

--------------------------------

### Iterate Through Large Insider Sales

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Use the `.iter()` method to find all insider sales exceeding a specified minimum value across all companies. Useful for tracking significant divestitures.

```python
# Large sales across all companies
for txn in client.insider.iter(direction="sell", min_value=1_000_000):
    print(f"{txn.company_name}: ${txn.transaction_value:,.0f}")
```

--------------------------------

### Iterate All Filings

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Lazily iterate through all matching filings across pages. Yields individual `Filing` objects, automatically fetching subsequent pages behind the scenes. Ideal for bulk data extraction without manual cursor management.

```APIDOC
## Iterate All Filings — `client.filings.iter()`

`FilingsResource.iter(*, forms, cik, ticker, status, issuer_type, start_date, end_date, q, limit)` — Lazily iterate through all matching filings across pages.

Yields individual `Filing` objects, automatically fetching subsequent pages behind the scenes. Ideal for bulk data extraction without manual cursor management.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Collect all 8-K filings for Tesla in Q1 2024
count = 0
for filing in client.filings.iter(
    ticker="TSLA",
    forms="8-K",
    start_date="2024-01-01",
    end_date="2024-03-31",
):
    print(f"{filing.accession_number} | {filing.filed_at.date()} | {filing.title}")
    count += 1

print(f"Total 8-K filings: {count}")
```
```

--------------------------------

### List Insider Transactions using client.insider.list()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a paginated list of Form 3/4/5 insider transactions. Supports filtering by ticker, direction, transaction codes, and minimum value.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Large open-market purchases at Microsoft
response = client.insider.list(
    ticker="MSFT",
    direction="buy",
    codes=["P"],          # Open-market purchases only
    min_value=500_000,    # At least $500K
    limit=20,
)

for txn in response.items:
    print(
        f"{txn.transaction_date} | {txn.person_name} ({txn.officer_title or 'N/A'}) | "
        f"{txn.shares:,} shares @ ${txn.price_per_share} | "
        f"Total: ${txn.transaction_value:,.0f}"
    )
# Example output:
# 2024-03-15 | Satya Nadella (Chief Executive Officer) | 10,000 shares @ $415.20 | Total: $4,152,000
```

--------------------------------

### List Filings

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a single page of SEC filings with optional filters. Retrieve up to 100 filings per call. Filter by ticker, CIK, form types, date range, or full-text search query. Returns a `FilingsResponse` with `items`, `next_cursor`, and `has_more` for manual pagination.

```APIDOC
## List Filings — `client.filings.list()`

`FilingsResource.list(*, limit, cursor, forms, cik, ticker, status, issuer_type, start_date, end_date, q)` — Fetch a single page of SEC filings with optional filters.

Retrieve up to 100 filings per call. Filter by ticker, CIK, form types, date range, or full-text search query. Returns a `FilingsResponse` with `items`, `next_cursor`, and `has_more` for manual pagination.

```python
from datetime import date
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Fetch AAPL's final 10-K and 10-Q filings in 2024
response = client.filings.list(
    ticker="AAPL",
    forms=["10-K", "10-Q"],
    status="final",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 12, 31),
    limit=10,
)

print(f"Total fetched: {len(response.items)}, more available: {response.has_more}")
for filing in response.items:
    print(f"[{filing.filed_at.date()}] {filing.form_type}: {filing.title} — {filing.url}")

# Manual pagination
if response.has_more:
    next_page = client.filings.list(
        ticker="AAPL",
        forms=["10-K", "10-Q"],
        cursor=response.next_cursor,
        limit=10,
    )
```
```

--------------------------------

### List Institutional Holdings using client.institutional.list()

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch 13F institutional holding records, representing individual positions within a manager's filing. Supports filtering by company, manager, and position size.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Top institutional holders of Nvidia with positions >= $1B
response = client.institutional.list(
    ticker="NVDA",
    min_value=1_000_000_000,
    limit=25,
)

for h in response.items:
    print(
        f"{h.manager_name:<40} | {h.shares:>15,} shares | "
        f"${h.value:>20,} | Period: {h.report_period_date}"
    )
```

--------------------------------

### Iterate All SEC Filings Automatically

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Lazily iterate through all matching SEC filings across multiple pages. This method automatically handles pagination, making it suitable for bulk data extraction without manual cursor management.

```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Collect all 8-K filings for Tesla in Q1 2024
count = 0
for filing in client.filings.iter(
    ticker="TSLA",
    forms="8-K",
    start_date="2024-01-01",
    end_date="2024-03-31",
):
    print(f"{filing.accession_number} | {filing.filed_at.date()} | {filing.title}")
    count += 1

print(f"Total 8-K filings: {count}")
```

--------------------------------

### Search Companies by Name and State

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Search for companies using keywords in their name and filtering by state. Results include company name and ticker.

```python
# Search companies
results = client.companies.search(q="software", state="CA", limit=10)
for company in results.items:
    print(f"{company.name} ({company.ticker})")
```

--------------------------------

### Safe Filing Retrieval with Error Handling

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Implements a robust function to retrieve filing details, with retry logic for rate limit errors and specific handling for authentication, not found, validation, and general API errors.

```python
from earningsfeed import (
    EarningsFeed,
    EarningsFeedError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    APIError,
)
import time

client = EarningsFeed("your_api_key")

def safe_get_filing(accession: str):
    retries = 3
    for attempt in range(retries):
        try:
            return client.filings.get(accession)

        except AuthenticationError:
            print("Invalid API key — check your credentials")
            raise  # Non-retryable

        except NotFoundError:
            print(f"Filing {accession!r} does not exist")
            return None  # Non-retryable

        except RateLimitError as e:
            wait = (e.reset_at - time.time()) if e.reset_at else 60
            print(f"Rate limited. Waiting {wait:.0f}s before retry {attempt + 1}/{retries}")
            time.sleep(max(wait, 1))

        except ValidationError as e:
            print(f"Bad request parameters: {e}")
            raise  # Non-retryable

        except APIError as e:
            print(f"API error {e.status_code} ({e.code}): {e}")
            if attempt < retries - 1:
                time.sleep(2 ** attempt)

        except EarningsFeedError as e:
            print(f"Unexpected SDK error: {e}")
            raise

    return None

detail = safe_get_filing("0000320193-24-000123")
if detail:
    print(f"Got filing: {detail.title}")
```

--------------------------------

### Track Holdings of a Specific Fund

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Use the `.iter()` method to track all holdings managed by a specific fund manager, identified by their CIK. Useful for following investment strategies.

```python
# Track a specific fund
for h in client.institutional.iter(manager_cik=1067983):  # Berkshire
    print(f"{h.issuer_name}: {h.shares:,} shares")
```

--------------------------------

### Handle API Errors with Specific Exceptions

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Implement robust error handling using specific exceptions like AuthenticationError, RateLimitError, and NotFoundError. Catches common API issues.

```python
from earningsfeed import (
    EarningsFeed,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

client = EarningsFeed("your_api_key")

try:
    filing = client.filings.get("invalid-accession")
except NotFoundError:
    print("Filing not found")
except RateLimitError as e:
    print(f"Rate limited. Resets at: {e.reset_at}")
except AuthenticationError:
    print("Invalid API key")
```

--------------------------------

### Iterate Insider Transactions

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all matching insider transactions with automatic pagination. Use `insider_cik` to track a specific executive's activity across all companies, or filter for large derivative transactions market-wide.

```APIDOC
## Iterate Insider Transactions — `client.insider.iter()`

### Description
Iterate through all matching insider transactions with automatic pagination. Use `insider_cik` to track a specific executive's activity across all companies, or filter for large derivative transactions market-wide.

### Method Signature
`InsiderResource.iter(*, cik, ticker, insider_cik, direction, codes, derivative, min_value, start_date, end_date, limit)`

### Parameters
#### Query Parameters
- **cik** (string) - Optional - Filter by company CIK.
- **ticker** (string) - Optional - Filter by company ticker symbol.
- **insider_cik** (string) - Optional - Filter by insider CIK.
- **direction** (string) - Optional - Filter by transaction direction ('buy' or 'sell').
- **codes** (list of strings) - Optional - Filter by transaction codes (e.g., 'P', 'S', 'A').
- **derivative** (boolean) - Optional - Filter for derivative transactions.
- **min_value** (float) - Optional - Filter by minimum transaction value in dollars.
- **start_date** (string) - Optional - Filter by start date (YYYY-MM-DD).
- **end_date** (string) - Optional - Filter by end date (YYYY-MM-DD).
- **limit** (integer) - Optional - Maximum number of transactions to fetch per page (for internal use).

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Track all transactions by Warren Buffett (CIK 315090) across all companies
for txn in client.insider.iter(insider_cik=315090):
    direction = "BUY" if txn.acquired_disposed == "A" else "SELL"
    print(
        f"[{direction}] {txn.company_name} | {txn.transaction_date} | "
        f"{txn.shares:,} shares | Code: {txn.transaction_code}"
    )

# All market-wide insider sales > $1M (equity only, no derivatives)
for txn in client.insider.iter(
    direction="sell",
    derivative=False,
    min_value=1_000_000,
    start_date="2024-01-01",
):
    print(f"{txn.company_name}: ${txn.transaction_value:,.0f} by {txn.person_name}")
```

### Response
#### Success Response (200)
- **Transaction objects** - Each yielded object represents an insider transaction.
  - **acquired_disposed** (string)
  - **company_name** (string)
  - **transaction_date** (string)
  - **shares** (integer)
  - **transaction_code** (string)
  - **company_name** (string)
  - **transaction_value** (float)
  - **person_name** (string)

*Note: This method yields transactions one by one, handling pagination automatically.*
```

--------------------------------

### List Institutional Holdings (13F) for a Ticker

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Retrieve institutional holdings for a specific company ticker, filtering for positions above a certain value threshold (e.g., $1 billion).

```python
# Who owns Apple?
holdings = client.institutional.list(
    ticker="AAPL",
    min_value=1_000_000_000,  # $1B+ positions
)

for h in holdings.items:
    print(f"{h.manager_name}: {h.shares:,} shares (${h.value:,})")
```

--------------------------------

### List Recent Insider Purchases

Source: https://github.com/earningsfeed/earningsfeed-python/blob/main/README.md

Fetch recent insider transactions, filtering by ticker, transaction direction ('buy'), and specific codes like 'P' for open market purchases. Limit results with 'limit'.

```python
# Recent insider purchases
purchases = client.insider.list(
    ticker="AAPL",
    direction="buy",
    codes=["P"],  # Open market purchases
    limit=50,
)

for txn in purchases.items:
    print(f"{txn.person_name}: {txn.shares} shares @ ${txn.price_per_share}")
```

--------------------------------

### Iterate Institutional Holdings

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all matching 13F holdings with automatic pagination. Retrieve the full portfolio of a fund by its `manager_cik`, or track all institutional ownership of a security over time.

```APIDOC
## Iterate Institutional Holdings — `client.institutional.iter()`

### Description
Iterate through all matching 13F holdings with automatic pagination. Retrieve the full portfolio of a fund by its `manager_cik`, or track all institutional ownership of a security over time.

### Method Signature
`InstitutionalResource.iter(*, company_cik, ticker, cusip, manager_cik, manager_name, report_period, put_call, min_value, min_shares, start_date, end_date, limit)`

### Parameters
#### Query Parameters
- **company_cik** (string) - Optional - Filter by the CIK of the company held.
- **ticker** (string) - Optional - Filter by the ticker symbol of the company held.
- **cusip** (string) - Optional - Filter by the CUSIP of the company held.
- **manager_cik** (string) - Optional - Filter by the CIK of the fund manager.
- **manager_name** (string) - Optional - Filter by the name of the fund manager.
- **report_period** (string) - Optional - Filter by the reporting period (YYYY-MM-DD).
- **put_call** (string) - Optional - Filter by position type ('put' or 'call').
- **min_value** (float) - Optional - Filter by minimum position value in dollars.
- **min_shares** (integer) - Optional - Filter by minimum number of shares.
- **start_date** (string) - Optional - Filter by start date (YYYY-MM-DD).
- **end_date** (string) - Optional - Filter by end date (YYYY-MM-DD).
- **limit** (integer) - Optional - Maximum number of holdings to fetch per page (for internal use).

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Full Berkshire Hathaway (CIK 1067983) 13F portfolio for Q4 2023
portfolio = []
for holding in client.institutional.iter(
    manager_cik=1067983,
    report_period="2023-12-31",
):
    portfolio.append(holding)
```

### Response
#### Success Response (200)
- **Holding objects** - Each yielded object represents an institutional holding.
  - **manager_name** (string)
  - **shares** (integer)
  - **value** (float)
  - **report_period_date** (string)

*Note: This method yields holdings one by one, handling pagination automatically.*
```

--------------------------------

### List Insider Transactions

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch a paginated list of Form 3/4/5 insider transactions. Filter by company, individual insider, transaction direction, transaction codes, and minimum dollar value.

```APIDOC
## List Insider Transactions — `client.insider.list()`

### Description
Fetch a paginated list of Form 3/4/5 insider transactions. Filter by company, individual insider, transaction direction (`buy`/`sell`), transaction codes (`P` = open-market purchase, `S` = open-market sale, `A` = award, etc.), and minimum dollar value.

### Method Signature
`InsiderResource.list(*, limit, cursor, cik, ticker, insider_cik, direction, codes, derivative, min_value, start_date, end_date)`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of transactions to return.
- **cursor** (string) - Optional - Pagination cursor for fetching the next page.
- **cik** (string) - Optional - Filter by company CIK.
- **ticker** (string) - Optional - Filter by company ticker symbol.
- **insider_cik** (string) - Optional - Filter by insider CIK.
- **direction** (string) - Optional - Filter by transaction direction ('buy' or 'sell').
- **codes** (list of strings) - Optional - Filter by transaction codes (e.g., 'P', 'S', 'A').
- **derivative** (boolean) - Optional - Filter for derivative transactions.
- **min_value** (float) - Optional - Filter by minimum transaction value in dollars.
- **start_date** (string) - Optional - Filter by start date (YYYY-MM-DD).
- **end_date** (string) - Optional - Filter by end date (YYYY-MM-DD).

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Large open-market purchases at Microsoft
response = client.insider.list(
    ticker="MSFT",
    direction="buy",
    codes=["P"],          # Open-market purchases only
    min_value=500_000,    # At least $500K
    limit=20,
)

for txn in response.items:
    print(
        f"{txn.transaction_date} | {txn.person_name} ({txn.officer_title or 'N/A'}) | "
        f"{txn.shares:,} shares @ ${txn.price_per_share} | "
        f"Total: ${txn.transaction_value:,.0f}"
    )
```

### Response
#### Success Response (200)
- **items** (list of Transaction objects)
  - **transaction_date** (string)
  - **person_name** (string)
  - **officer_title** (string or null)
  - **shares** (integer)
  - **price_per_share** (float)
  - **transaction_value** (float)
- **next_cursor** (string or null) - For pagination.
```

--------------------------------

### Iterate Company Search

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Iterate through all company search results across multiple pages without manual cursor management.

```APIDOC
## Iterate Company Search — `client.companies.iter_search()`

### Description
Iterate through all company search results across pages.

### Method
`CompaniesResource.iter_search(*, q, ticker, sic_code, category, entity_type, state, has_insider_transactions, limit)`

### Parameters
#### Query Parameters
- **q** (str) - Optional - Search query for company name.
- **ticker** (str) - Optional - Filter by company ticker symbol.
- **sic_code** (int) - Optional - Filter by Standard Industrial Classification (SIC) code.
- **category** (str) - Optional - Filter by industry category.
- **entity_type** (str) - Optional - Filter by entity type (e.g., 'operating', 'investment').
- **state** (str) - Optional - Filter by state where the company is located.
- **has_insider_transactions** (bool) - Optional - Filter for companies with insider transactions.
- **limit** (int) - Optional - Maximum number of results to return per page (default 100).

### Response
#### Success Response (200)
- An iterator yielding `CompanySearchResult` objects.

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Collect all SEC-registered financial institutions
banks = list(client.companies.iter_search(sic_code=6022))  # State commercial banks
print(f"Total state commercial banks on SEC: {len(banks)}")
for bank in banks[:5]:
    print(f"  {bank.name} ({bank.ticker or 'no ticker'})")
```

### Response Example
```
Total state commercial banks on SEC: 150
  JPMorgan Chase & Co. (JPM)
  Bank of America Corporation (BAC)
  Citigroup Inc. (C)
  Wells Fargo & Company (WFC)
  Goldman Sachs Group, Inc. (GS)
```
```

--------------------------------

### Search Companies

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Search for companies using various criteria like name, ticker, SIC code, or state. Returns a paginated response with company search results.

```APIDOC
## Search Companies — `client.companies.search()`

### Description
Search for companies by name, ticker, SIC code, or state.

Returns a paginated `CompanySearchResponse` with lightweight `CompanySearchResult` objects.

### Method
`CompaniesResource.search(*, q, ticker, sic_code, category, entity_type, state, has_insider_transactions, limit, cursor)`

### Parameters
#### Query Parameters
- **q** (str) - Optional - Search query for company name.
- **ticker** (str) - Optional - Filter by company ticker symbol.
- **sic_code** (int) - Optional - Filter by Standard Industrial Classification (SIC) code.
- **category** (str) - Optional - Filter by industry category.
- **entity_type** (str) - Optional - Filter by entity type (e.g., 'operating', 'investment').
- **state** (str) - Optional - Filter by state where the company is located.
- **has_insider_transactions** (bool) - Optional - Filter for companies with insider transactions.
- **limit** (int) - Optional - Maximum number of results to return per page (default 100).
- **cursor** (str) - Optional - Cursor for pagination to fetch the next page of results.

### Response
#### Success Response (200)
- **CompanySearchResponse** (object) - A paginated response containing company search results.
  - **items** (list[CompanySearchResult]) - A list of company search result objects.
  - **has_more** (bool) - Indicates if there are more results available.

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Find California-based software companies with insider filing activity
results = client.companies.search(
    sic_code=7372,                    # Prepackaged software
    state="CA",
    has_insider_transactions=True,
    limit=10,
)

print(f"Found {len(results.items)} results (more: {results.has_more})")
for co in results.items:
    print(f"  CIK {co.cik:>10} | {co.ticker or 'N/A':<6} | {co.name}")
```

### Response Example
```json
{
  "items": [
    {
      "cik": 1018724,
      "ticker": "MSFT",
      "name": "Microsoft Corporation"
    },
    {
      "cik": 789019,
      "ticker": "ORCL",
      "name": "Oracle Corporation"
    }
  ],
  "has_more": true
}
```
```

--------------------------------

### List Institutional Holdings

Source: https://context7.com/earningsfeed/earningsfeed-python/llms.txt

Fetch 13F institutional holding records. Each record represents one position in a manager's 13F filing. Filter by target company, fund manager, position type, and minimum size.

```APIDOC
## List Institutional Holdings — `client.institutional.list()`

### Description
Fetch 13F institutional holding records. Each record represents one position in a manager's 13F filing. Filter by target company (ticker/CIK/CUSIP), fund manager (CIK or name), position type (equity/put/call), and minimum size.

### Method Signature
`InstitutionalResource.list(*, limit, cursor, company_cik, ticker, cusip, manager_cik, manager_name, report_period, put_call, min_value, min_shares, start_date, end_date)`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of holdings to return.
- **cursor** (string) - Optional - Pagination cursor for fetching the next page.
- **company_cik** (string) - Optional - Filter by the CIK of the company held.
- **ticker** (string) - Optional - Filter by the ticker symbol of the company held.
- **cusip** (string) - Optional - Filter by the CUSIP of the company held.
- **manager_cik** (string) - Optional - Filter by the CIK of the fund manager.
- **manager_name** (string) - Optional - Filter by the name of the fund manager.
- **report_period** (string) - Optional - Filter by the reporting period (YYYY-MM-DD).
- **put_call** (string) - Optional - Filter by position type ('put' or 'call').
- **min_value** (float) - Optional - Filter by minimum position value in dollars.
- **min_shares** (integer) - Optional - Filter by minimum number of shares.
- **start_date** (string) - Optional - Filter by start date (YYYY-MM-DD).
- **end_date** (string) - Optional - Filter by end date (YYYY-MM-DD).

### Request Example
```python
from earningsfeed import EarningsFeed

client = EarningsFeed("your_api_key")

# Top institutional holders of Nvidia with positions >= $1B
response = client.institutional.list(
    ticker="NVDA",
    min_value=1_000_000_000,
    limit=25,
)

for h in response.items:
    print(
        f"{h.manager_name:<40} | {h.shares:>15,} shares | "
        f"${h.value:>20,} | Period: {h.report_period_date}"
    )
```

### Response
#### Success Response (200)
- **items** (list of Holding objects)
  - **manager_name** (string)
  - **shares** (integer)
  - **value** (float)
  - **report_period_date** (string)
- **next_cursor** (string or null) - For pagination.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.