EdgarTools
Analyze SEC filings and financial statements using EdgarTools
Overview
Essential SEC filing analysis operations. See [objects.md](./objects.md) for object reference, [workflows.md](./workflows.md) for patterns, [readme.md](./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 objectOutput:
**Company:** Apple Inc.
**CIK:** 0000320193
**Ticker:** AAPL
**Exchange:** Nasdaq
**Industry:** Electronic Computers (SIC 3571)
**Fiscal Year End:** Sep 30Filings.to_context()
filings = company.get_filings(form="10-K")
print(filings.to_context()) # ~95 tokens vs 500-1000 for rich tableShows summary + AVAILABLE ACTIONS.
Filing.to_context()
filing = filings.latest()
print(filing.to_context()) # ~109 tokens, includes available methodsXBRL.to_context()
xbrl = filing.xbrl()
print(xbrl.to_context()) # ~275 tokens vs 2,500+ for full statementsToken Comparison:
| Object | Full Output | to_context() | Savings | |--------|-------------|--------------|---------| | Company | ~200 tokens | ~88 tokens | 56% | | Filings | ~500-1000 | ~95 tokens | 80-90% | | XBRL | ~2,500 tokens | ~275 tokens | 89% |
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 statementCore 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 quarters2. 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