edgartools

Python library for accessing all SEC filings since 1994 with structured data extraction.

Authentication (Required)

The SEC requires identification for API access. Always set identity before any operations:

from edgar import set_identity
set_identity("Your Name [email protected]")

Set via environment variable to avoid hardcoding: EDGAR_IDENTITY="Your Name [email protected]".

Installation

uv pip install edgartools
# For AI/MCP features:
uv pip install "edgartools[ai]"

Core Workflow

Find a Company

from edgar import Company, find

company = Company("AAPL")        # by ticker
company = Company(320193)         # by CIK (fastest)
results = find("Apple")           # by name search

Get Filings

# Company filings
filings = company.get_filings(form="10-K")
filing = filings.latest()

# Global search across all filings
from edgar import get_filings
filings = get_filings(2024, 1, form="10-K")

# By accession number
from edgar import get_by_accession_number
filing = get_by_accession_number("0000320193-23-000106")

Extract Structured Data

# Form-specific object (most common approach)
tenk = filing.obj()              # Returns TenK, EightK, Form4, ThirteenF, etc.

# Financial statements (10-K/10-Q)
financials = company.get_financials()     # annual
financials = company.get_quarterly_financials()  # quarterly
income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement()

# XBRL data
xbrl = filing.xbrl()
income = xbrl.statements.income_statement()

Access Filing Content

text = filing.text()             # plain text
html = filing.html()             # HTML
md = filing.markdown()           # markdown (good for LLM processing)
filing.open()                    # open in browser

Key Company Properties

company.name                     # "Apple Inc."
company.cik                      # 320193
company.ticker                   # "AAPL"
company.industry                 # "ELECTRONIC COMPUTERS"
company.sic                      # "3571"
company.shares_outstanding       # 15115785000.0
company.public_float             # 2899948348000.0
company.fiscal_year_end          # "0930"
company.exchange                 # "Nasdaq"

Form → Object Mapping

Form	Object	Key Properties
10-K	TenK	financials, income_statement, balance_sheet
10-Q	TenQ	financials, income_statement, balance_sheet
8-K	EightK	items, press_releases
Form 4	Form4	reporting_owner, transactions
13F-HR	ThirteenF	infotable, total_value
DEF 14A	ProxyStatement	executive_compensation, proposals
SC 13D/G	Schedule13	total_shares, items
Form D	FormD	offering, recipients

Important: filing.financials does NOT exist. Use filing.obj().financials.

Common Pitfalls

• filing.financials → AttributeError; use filing.obj().financials
• get_filings() has no limit param; use .head(n) or .latest(n)
• Prefer amendments=False for multi-period analysis (amended filings may be incomplete)
• Always check for None before accessing optional data

Reference Files

Load these when you need detailed information:

• companies.md — Finding companies, screening, batch lookups, Company API
• filings.md — Working with filings, attachments, exhibits, Filings collection API
• financial-data.md — Financial statements, convenience methods, DataFrame export, multi-period analysis
• xbrl.md — XBRL parsing, fact querying, multi-period stitching, standardization
• data-objects.md — All supported form types and their structured objects
• entity-facts.md — EntityFacts API, FactQuery, FinancialStatement, FinancialFact
• ai-integration.md — MCP server setup, Skills installation, .docs and .to_context() properties