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:

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 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_text) # Shows documentation about filing.xbrl() method

help_text = filing.docs.search("convert to markdown") print(help_text) # Shows documentation about filing.markdown() method

Use cases:

• Learning the Filing API

• Discovering available methods

• Finding parameter details

Quick Reference

What are you searching? Method Returns

Text in the filing (content) filing.search("keyword")

List of DocSection matches with scores

How to use Filing API (methods) filing.docs.search("how to")

API documentation snippets

⚠️ Common Mistake:

WRONG - Searches API docs, not filing content!

matches = filing.docs.search("executive compensation") # ❌

Returns empty - API docs don't mention "executive compensation"

CORRECT - Searches the actual filing document

matches = filing.search("executive compensation") # ✅

Returns 50+ matches from proxy statement

Quick Reference

Complete examples in common-questions.md.

Task Primary Method Example

Show S-1 filings from date range get_filings(year, quarter, form="S-1", filing_date="...")

See example

Get today's filings get_current_filings()

See example

Get company revenue trend company.income_statement(periods=3)

See example

Get quarterly financials company.income_statement(periods=4, annual=False)

See example

Get statement from specific filing filing.xbrl().statements.income_statement()

See example

Compare multiple companies compare_companies_revenue(["AAPL", "MSFT"])

See example

Get latest quarterly balance sheet company.get_filings(form="10-Q")[0].xbrl()

See example

Get insider transactions (Form 4) company.get_filings(form="4")

See example

Filter filings efficiently filings.filter(ticker="AAPL", filing_date="2024-01-01:")

See example

Look up form types describe_form("C") or see form-types-reference.md See example

Pattern: For any question, check common-questions.md for full working examples.

Advanced Topics

Advanced patterns, helpers, error handling, skill exportation: advanced-guide.md.

Includes:

• Filtering and pagination

• Multi-company analysis

• Error handling patterns

• Working with filing documents

• Helper functions reference

• Exporting skills for Claude Desktop

• Creating custom external skills

Troubleshooting

"User-Agent identity is not set"

Error:

RuntimeError: User-Agent identity is not set. Please call set_identity() first.

Cause: Missing set_identity() call (SEC requirement)

Solution:

from edgar import set_identity set_identity("Your Name your@email.com") # Must call before any API operations

AttributeError on Company object

Error:

AttributeError: 'Company' object has no attribute 'sic_code'

Cause: Incorrect attribute name

Solution: Check the API reference in objects.md for correct attribute names (e.g., use company.sic instead of company.sic_code )

Using too many tokens?

Cause: Not using .to_context() method

Solution: Always call .to_context() before printing full objects:

Instead of:

print(company) # 200+ tokens

Use:

print(company.to_context()) # ~88 tokens

Empty filings result

Problem: get_filings() returns empty list

Possible causes: No filings match criteria (try broader search), wrong quarter/year combination, or form type doesn't exist for that period

Solution:

filings = get_filings(2024, 1, form="10-K") if len(filings) == 0: print("No filings found - try different criteria") # Try broader search all_filings = get_filings(2024, 1) print(f"Found {len(all_filings)} total filings in 2024 Q1")

Accessing Documentation Programmatically (For AI Agents)

Use the skill API to read documentation:

from edgar.ai import get_skill

skill = get_skill("EdgarTools") common_questions = skill.get_document_content("common-questions") advanced_guide = skill.get_document_content("advanced-guide")

Available documents: SKILL, common-questions, advanced-guide, quickstart-by-task, objects, workflows, form-types-reference, readme

See readme.md for complete API documentation.

See Also

• Common Questions - Complete examples with full code for common tasks

• Advanced Guide - Advanced patterns, helper functions, and skill exportation

• Quick Start by Task - Fast task routing (< 30 seconds)

• Object Reference - Object representations and token size estimates

• Workflows - End-to-end analysis patterns

• Form Types Reference - Complete SEC form catalog (311 forms)

• README - Installation and package overview

Rate Limiting

EdgarTools automatically handles SEC rate limiting (10 requests/second):

• Built-in rate limiting

• Request caching to reduce API calls

• Large batch operations may take time due to rate limits