edgartools — SEC EDGAR Data

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

When to Use This Skill

• Retrieving specific filings (10-K, 10-Q, 8-K, DEF 14A, S-1, 13F, Form 4, SC 13D/G, Form D) for a company or period
• Extracting financial statements or XBRL facts exactly as filed, including multi-period stitching
• Insider-trading, institutional-holdings, or proxy/compensation data at the filer level
• Company metadata from EDGAR (CIK, SIC, fiscal year end, filer status)

Does NOT Trigger

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]".

edgartools sends this identity as the HTTP User-Agent the SEC asks for ("Sample Company Name AdminContact@<domain>.com") and throttles itself to 9 requests/second by default (EDGAR_RATE_LIMIT_PER_SEC), under the SEC's 10 requests/second fair-access ceiling — keep that default for sec.gov, because the SEC may block IP addresses that exceed it.

Installation

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

API examples here are checked against edgartools 5.58.0 (current as of 2026-09). To run a one-off without a venv: uv run --with edgartools python .... In 5.x, cashflow_statement() is a deprecated alias (removed in 6.0) — use cash_flow_statement().

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.cash_flow_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.get_ticker()             # "AAPL" (primary); company.tickers -> list
company.industry                 # "ELECTRONIC COMPUTERS"
company.sic                      # "3571"
company.shares_outstanding       # 15115785000.0
company.public_float             # 2899948348000.0
company.fiscal_year_end          # "0930"
company.get_exchanges()          # ["Nasdaq"]

Form → Object Mapping

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

Cite the filing (company, form, accession number, filing date) for every figure you report.

Part of the AlterLab Academic Skills suite.