name	EdgarTools
description	Query and analyze SEC filings and financial statements using EdgarTools. Get company data, filings, XBRL financials, and perform multi-company analysis.

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.

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

EdgarTools

Install Skill

SKILL.md

EdgarTools

Overview

Prerequisites & Setup

⚡ Token-Efficient API Usage

Company.to_context()

Filings.to_context()

Filing.to_context()

XBRL.to_context()

Quick Start

Get a Company

Get Recent Filings

Get Financial Statements

Core API Reference

Getting Filings (3 Approaches)

1. Published Filings - Discovery & Bulk Analysis

2. Current Filings - Real-time Monitoring

3. Company Filings - Known Entity Analysis

Getting Financials (2 Approaches)

1. Entity Facts API - Multi-Period Comparison

2. Filing XBRL - Single Period Detail

Searching Filing Content

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

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

Quick Reference

Quick Reference

Advanced Topics

Troubleshooting

"User-Agent identity is not set"

AttributeError on Company object

Using too many tokens?

Empty filings result

Accessing Documentation Programmatically (For AI Agents)

See Also

Rate Limiting

Install Skill

SKILL.md

EdgarTools

Overview

Prerequisites & Setup

⚡ Token-Efficient API Usage

Company.to_context()

Filings.to_context()

Filing.to_context()

XBRL.to_context()

Quick Start

Get a Company

Get Recent Filings

Get Financial Statements

Core API Reference

Getting Filings (3 Approaches)

1. Published Filings - Discovery & Bulk Analysis

2. Current Filings - Real-time Monitoring

3. Company Filings - Known Entity Analysis

Getting Financials (2 Approaches)

1. Entity Facts API - Multi-Period Comparison

2. Filing XBRL - Single Period Detail

Searching Filing Content

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

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

Quick Reference

Quick Reference

Advanced Topics

Troubleshooting

"User-Agent identity is not set"

AttributeError on Company object

Using too many tokens?

Empty filings result

Accessing Documentation Programmatically (For AI Agents)

See Also

Rate Limiting

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

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