foryourhealth111-pixel/Vibe-Skills / bundled/skills/edgartools
edgartools
VerifiedPython library for accessing, analyzing, and extracting data from SEC EDGAR filings. Use when working with SEC filings, financial statements (income statement, balance sheet, cash flow), XBRL financial data, insider trading (Form 4), institutional holdings (13F), company financials, annual/quarterly reports (10-K, 10-Q), proxy statements (DEF 14A), 8-K current events, company screening by ticker/CIK/industry, multi-period financial analysis, or any SEC regulatory filings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/ai-integration.md | markdown | 6.7 KB |
| references/companies.md | markdown | 6.0 KB |
| references/data-objects.md | markdown | 5.4 KB |
| references/entity-facts.md | markdown | 8.1 KB |
| references/filings.md | markdown | 8.9 KB |
| references/financial-data.md | markdown | 6.9 KB |
| references/xbrl.md | markdown | 9.2 KB |
references/filings.md
View on GitHub# edgartools — Filings Reference
## Table of Contents
- [Getting a Filing](#getting-a-filing)
- [Filing Properties](#filing-properties)
- [Accessing Content](#accessing-content)
- [Structured Data](#structured-data)
- [Attachments & Exhibits](#attachments--exhibits)
- [Search Within a Filing](#search-within-a-filing)
- [Viewing & Display](#viewing--display)
- [Save, Load & Export](#save-load--export)
- [Filings Collection API](#filings-collection-api)
- [Filtering & Navigation](#filtering--navigation)
---
## Getting a Filing
```python
from edgar import Company, get_filings, get_by_accession_number, Filing
# From a company
company = Company("AAPL")
filing = company.get_filings(form="10-K").latest()
# Global search
filings = get_filings(2024, 1, form="10-K")
filing = filings[0]
filing = filings.latest()
# By accession number
filing = get_by_accession_number("0000320193-23-000106")
# Direct construction (rarely needed)
filing = Filing(
form='10-Q',
filing_date='2024-06-30',
company='Tesla Inc.',
cik=1318605,
accession_no='0001628280-24-028839'
)
```
---
## Filing Properties
### Basic Properties
```python
filing.cik # 320193
filing.company # "Apple Inc."
filing.form # "10-K"
filing.filing_date # "2023-11-03"
filing.period_of_report # "2023-09-30"
filing.accession_no # "0000320193-23-000106"
filing.accession_number # alias for accession_no
```
### EntityFiling Extra Properties (from company.get_filings())
```python
filing.acceptance_datetime # datetime
filing.file_number # "001-36743"
filing.size # bytes
filing.primary_document # filename
filing.is_xbrl # bool
filing.is_inline_xbrl # bool
```
### URL Properties
```python
filing.homepage_url # SEC index page URL
filing.filing_url # primary document URL
filing.text_url # text version URL
filing.base_dir # base directory for all files
```
---
## Accessing Content
```python
html = filing.html() # HTML string or None
text = filing.text() # plain text (clean)
md = filing.markdown() # markdown string
xml = filing.xml() # XML string or None (ownership forms)
full = filing.full_text_submission() # complete SGML submission
# Markdown with page breaks (good for LLM processing)
md = filing.markdown(include_page_breaks=True, start_page_number=1)
```
---
## Structured Data
### Get Form-Specific Object (Primary Method)
```python
obj = filing.obj() # or filing.data_object()
# Returns: TenK, TenQ, EightK, Form4, ThirteenF, ProxyStatement, etc.
```
**IMPORTANT:** The base `Filing` class has NO `financials` property.
```python
# WRONG:
filing.financials # AttributeError!
# CORRECT:
tenk = filing.obj()
if tenk and tenk.financials:
income = tenk.financials.income_statement
```
### Form → Class Mapping
| Form | Class | Module |
|------|-------|--------|
| 10-K | TenK | edgar.company_reports |
| 10-Q | TenQ | edgar.company_reports |
| 8-K | EightK | edgar.company_reports |
| 20-F | TwentyF | edgar.company_reports |
| 4 | Form4 | edgar.ownership |
| 3 | Form3 | edgar.ownership |
| 5 | Form5 | edgar.ownership |
| DEF 14A | ProxyStatement | edgar.proxy |
| 13F-HR | ThirteenF | edgar.holdings |
| SC 13D/G | Schedule13 | edgar.ownership |
| NPORT-P | NportFiling | edgar.nport |
| 144 | Form144 | edgar.ownership |
### Get XBRL Data
```python
xbrl = filing.xbrl() # Returns XBRL object or None
if xbrl:
income = xbrl.statements.income_statement()
balance = xbrl.statements.balance_sheet()
cashflow = xbrl.statements.cash_flow_statement()
```
---
## Attachments & Exhibits
### List Attachments
```python
attachments = filing.attachments
print(f"Total: {len(attachments)}")
for att in attachments:
print(f"{att.sequence}: {att.description}")
print(f" Type: {att.document_type}")
print(f" File: {att.document}")
```
### Primary Document
```python
primary = filing.document
```
### Access by Index or Name
```python
first = filing.attachments[0]
specific = filing.attachments["ex-10_1.htm"]
```
### Download Attachments
```python
filing.attachments[0].download("./downloads/")
filing.attachments.download("./downloads/") # all
```
### Work with Exhibits
```python
exhibits = filing.exhibits
for exhibit in exhibits:
print(f"Exhibit {exhibit.exhibit_number}: {exhibit.description}")
if exhibit.exhibit_number == "10.1":
exhibit.download("./exhibits/")
```
---
## Search Within a Filing
```python
# Simple text search
results = filing.search("artificial intelligence")
print(f"Found {len(results)} mentions")
# Regex search
emails = filing.search(
r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
regex=True
)
# Financial terms
revenue_mentions = filing.search("revenue")
risk_factors = filing.search("risk factor")
critical = filing.search(r'\b(material weakness|restatement)\b', regex=True)
```
### Document Sections
```python
sections = filing.sections() # list of section names
doc = filing.parse() # parse to Document for advanced ops
```
---
## Viewing & Display
```python
filing.view() # display in console/Jupyter with Rich
filing.open() # open primary doc in browser
filing.open_homepage() # open SEC index page
filing.serve(port=8080) # serve locally at http://localhost:8080
```
---
## Save, Load & Export
```python
# Save
filing.save("./data/filings/") # auto-generates filename
filing.save("./data/apple_10k.pkl") # specific file
# Load
filing = Filing.load("./data/apple_10k.pkl")
# Export
data = filing.to_dict()
summary_df = filing.summary()
# Download raw
filing.download(data_directory="./raw_filings/", compress=False)
```
---
## Filings Collection API
### get_filings() — Global Search
```python
from edgar import get_filings
filings = get_filings(2024, 1, form="10-K") # Q1 2024 10-Ks
filings = get_filings(2023, form="10-K") # all 2023 10-Ks
filings = get_filings([2022, 2023, 2024]) # multiple years
filings = get_filings(2024, [1, 2], form="10-Q")
filings = get_filings(2024, 1, amendments=False)
```
**Note:** `get_filings()` has NO `limit` parameter. Use `.head(n)` after.
### Collection Properties
```python
len(filings) # count
filings.empty # bool
filings.date_range # (start_date, end_date)
filings.start_date # earliest
filings.end_date # latest
```
### Access & Iteration
```python
first = filings[0]
last = filings[-1]
for filing in filings:
print(f"{filing.form}: {filing.company}")
# By accession number
filing = filings.get("0001234567-24-000001")
```
### Subset Operations
```python
filings.latest() # most recent (single Filing)
filings.latest(10) # 10 most recent (Filings)
filings.head(20) # first 20
filings.tail(20) # last 20
filings.sample(10) # random 10
```
---
## Filtering & Navigation
### filter()
```python
# Form type
annual = filings.filter(form="10-K")
multi = filings.filter(form=["10-K", "10-Q"])
original = filings.filter(form="10-K", amendments=False)
# Date
jan = filings.filter(date="2024-01-01")
q1 = filings.filter(date="2024-01-01:2024-03-31")
recent = filings.filter(date="2024-01-01:")
# Company
apple = filings.filter(ticker="AAPL")
apple = filings.filter(cik=320193)
faang = filings.filter(ticker=["AAPL", "MSFT", "GOOGL"])
# Exchange
nasdaq = filings.filter(exchange="NASDAQ")
major = filings.filter(exchange=["NASDAQ", "NYSE"])
```
### Chain Filters
```python
result = (filings
.filter(form="10-K")
.filter(exchange="NASDAQ")
.filter(date="2024-01-01:")
.latest(50))
```
### Find by Company Name
```python
tech = filings.find("Technology")
apple = filings.find("Apple")
```
### Pagination
```python
next_page = filings.next()
prev_page = filings.previous()
current = filings.current()
```
---
## Export & Persistence
```python
df = filings.to_pandas()
df = filings.to_pandas('form', 'company', 'filing_date', 'cik')
filings.save_parquet("filings.parquet") # or .save()
filings.download(data_directory="./raw_data/", compress=True)
```
---
## Common Recipes
### Extract Revenue from Latest 10-K
```python
company = Company("MSFT")
filing = company.get_filings(form="10-K").latest()
tenk = filing.obj()
if tenk.financials:
income = tenk.financials.income_statement
print(income)
```
### Convert to Markdown for LLM Analysis
```python
company = Company("NVDA")
filing = company.get_filings(form="10-K").latest()
md = filing.markdown(include_page_breaks=True)
with open("nvidia_10k.md", "w") as f:
f.write(md)
```
### Search Across Recent 8-K Filings
```python
filings = get_filings(2024, 1, form="8-K").head(50)
for filing in filings:
if filing.search("earnings"):
print(f"{filing.company} ({filing.filing_date})")
```
### Batch Process with Pagination
```python
def process_all(filings):
current = filings
results = []
while current and not current.empty:
for filing in current:
results.append(filing.to_dict())
current = current.next()
return results
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |