EdgarTools

Analyze SEC filings and financial statements using EdgarTools

Overview

Essential SEC filing analysis operations. See objects.md for object reference, workflows.md for patterns, readme.md for setup.

Prerequisites & Setup

REQUIRED: Set your identity (SEC requirement):

from edgar import set_identity
set_identity("Your Name your@email.com")

Without this, all API calls fail with "User-Agent identity is not set" error.

⚡ Token-Efficient API Usage

ALWAYS use .to_context() first for concise summaries with available actions. 5-10x more token-efficient than full objects.

Company.to_context()

from edgar import Company

company = Company("AAPL")
print(company.to_context())  # ~88 tokens vs 200+ for full object

Output:

**Company:** Apple Inc.
**CIK:** 0000320193
**Ticker:** AAPL
**Exchange:** Nasdaq
**Industry:** Electronic Computers (SIC 3571)
**Fiscal Year End:** Sep 30

Filings.to_context()

filings = company.get_filings(form="10-K")
print(filings.to_context())  # ~95 tokens vs 500-1000 for rich table

Shows summary + AVAILABLE ACTIONS.

Filing.to_context()

filing = filings.latest()
print(filing.to_context())  # ~109 tokens, includes available methods

XBRL.to_context()

xbrl = filing.xbrl()
print(xbrl.to_context())  # ~275 tokens vs 2,500+ for full statements

Token Comparison:

Pattern: to_context() first → see available → access data.

Quick Start

Common starting patterns. Use .to_context() for efficiency.

Get a Company

from edgar import set_identity, Company

set_identity("Your Name your@email.com")  # Required first!

company = Company("AAPL")
print(company.to_context())  # Concise profile (~88 tokens)
# OR for full details:
# print(company)  # Full object (~200 tokens)

Get Recent Filings

from edgar import get_current_filings

filings = get_current_filings()  # Last ~24 hours
print(filings.to_context())  # Summary + available actions (~95 tokens)
# OR to see first 5 in table:
# print(filings.head(5))  # Rich table (~500-1000 tokens)

Get Financial Statements

from edgar import Company

company = Company("AAPL")
income = company.income_statement(periods=3)  # 3 fiscal years
print(income)  # Full statement

Core API Reference

Main API functions and approaches.

Getting Filings (3 Approaches)

Choose the approach based on your use case:

1. Published Filings - Discovery & Bulk Analysis

When to use: Cross-company screening, pattern discovery, historical research, don't know which specific companies.

Data source: SEC quarterly indexes (updated nightly)

from edgar import get_filings

# Get all filings for a quarter
filings = get_filings(2023, 1)  # Q1 2023

# Filter by form type
filings = get_filings(2023, 1, form="10-K")

# Filter by date range
filings = get_filings(2023, 1, filing_date="2023-02-01:2023-02-15")

# Further filter results
filtered = filings.filter(ticker="AAPL")
tech_filings = filings.filter(ticker=["AAPL", "MSFT", "GOOGL"])

2. Current Filings - Real-time Monitoring

When to use: Monitoring recent filing activity, tracking latest submissions

Data source: SEC RSS feed (last ~24 hours)

from edgar import get_current_filings

# Get all recent filings
current = get_current_filings()

# Filter by form type
reports = current.filter(form=["10-K", "10-Q"])

# Filter by specific companies
tech_current = current.filter(ticker=["AAPL", "MSFT"])

3. Company Filings - Known Entity Analysis

When to use: You know the specific company ticker or name

Data source: SEC company submissions endpoint

from edgar import Company

company = Company("AAPL")

# Get all filings
all_filings = company.get_filings()

# Filter by form type
annual_reports = company.get_filings(form="10-K")

# Filter by year
filings_2023 = company.get_filings(year=2023)

# Combine filters
q1_2023_10q = company.get_filings(year=2023, form="10-Q")

Getting Financials (2 Approaches)

1. Entity Facts API - Multi-Period Comparison

When to use: Comparing multiple periods, trend analysis (fastest approach)

Data source: SEC Company Facts API

Advantages: Very fast (single API call), pre-aggregated data, multi-period comparison built-in

from edgar import Company

company = Company("AAPL")

# Annual data (fiscal years)
income = company.income_statement(periods=3)  # Last 3 fiscal years
balance = company.balance_sheet(periods=3)
cash_flow = company.cash_flow_statement(periods=3)

# Quarterly data
quarterly_income = company.income_statement(periods=4, annual=False)  # Last 4 quarters

2. Filing XBRL - Single Period Detail

When to use: Need specific filing details, want complete line items, analyzing single period

Data source: XBRL files attached to specific filings

Advantages: Most comprehensive detail, all line items available, exact as-filed data

from edgar import Company

company = Company("AAPL")

# Get specific filing
filing = company.get_filings(form="10-K")[0]  # Latest 10-K

# Parse XBRL
xbrl = filing.xbrl()

# Get statements
income = xbrl.statements.income_statement()
balance = xbrl.statements.balance_sheet()
cash_flow = xbrl.statements.cash_flow_statement()

# Access metadata
print(f"Entity: {xbrl.entity_name}")
print(f"Fiscal Year: {xbrl.fiscal_year}")
print(f"Period: {xbrl.fiscal_period}")

Searching Filing Content

⚠️ IMPORTANT: Filing has TWO different search methods. Use the right one!

Content Search: filing.search(query) ⭐ Find Text in Filings

Search the actual filing document - find keywords, topics, or sections within SEC filings.

from edgar import Company

company = Company("AAPL")
filing = company.get_filings(form="DEF 14A")[0]  # Proxy statement

# Search for content IN the filing
results = filing.search("executive compensation")

# Process results
print(f"Found {len(results)} matches")
for match in results[:5]:  # Top 5 matches
    print(f"Relevance score: {match.score:.2f}")
    print(f"Excerpt: {str(match)[:200]}...")
    print()

Features: BM25 relevance ranking (best matches first), searches parsed HTML sections, returns DocSection objects with scores, index cached for performance (~1-2 seconds per filing)

Use cases: Find mentions of specific topics ("revenue recognition", "risk factors"), locate sections in large filings, screen filings for relevant content, extract context around keywords

Example: Find proxy statements mentioning compensation changes

from edgar import get_filings
from datetime import datetime, timedelta

# Get recent proxy statements
start_date = datetime.now() - timedelta(days=30)
filings = get_filings(form="DEF 14A")
recent = filings.filter(filing_date=f"{start_date.strftime('%Y-%m-%d')}:")

# Search each filing
companies_with_matches = []
for filing in recent:
    matches = filing.search("executive compensation changes")

    if matches and len(matches) > 0:
        companies_with_matches.append({
            'company': filing.company,
            'date': filing.filing_date,
            'matches': len(matches),
            'top_score': matches[0].score,
            'excerpt': str(matches[0])[:200]
        })

print(f"Found {len(companies_with_matches)} companies")

API Documentation Search: filing.docs.search(query) 📚 Find Methods

Search the Filing API documentation - discover how to use the Filing class.

# Find how to use Filing API
help_text = filing.docs.search("how to get XBRL")
print(help_te