SEC EDGAR Downloader

secfetcher Documentation

Modern Python library for SEC filing downloads with two workflows: direct file download and tar-source download with automatic extraction and cleanup.

Quickstart Choose Mode API PyPI

Install

Install from PyPI:

pip install secfetcher

Imports:

from secfetch import download_quarter, download_quarter_tar
# compatibility module
from secfetcher import download_quarter_tar

Quickstart

Simple Download

from secfetch import download_quarter

results = download_quarter(
    year=2024,
    quarter=1,
    forms=["10-Q"],
    ticker="AAPL",
    data_dir="data",
)

Tar Download + Extract

from secfetcher import download_quarter_tar

results = download_quarter_tar(
    year=2024,
    quarter=1,
    forms=["10-Q"],
    ticker="AAPL",
    data_dir="data",
)

Choose Mode

Simple (non-tar)

Functions: download_quarter, download_year

  • Downloads selected files directly from SEC folder listing.
  • Best for straightforward per-filing file retrieval.
  • Supports ticker and cik filtering.

Tar workflow

Functions: download_quarter_tar, download_year_tar

  • Downloads filing tar source from DataMule tar endpoint.
  • By default extracts into accession folders and deletes tar artifacts.
  • Supports limit and higher default concurrency.

Ticker and CIK Filtering

Both simple and tar workflows support filters. You can pass one value or a list.

# ticker
download_quarter(year=2024, quarter=1, forms=["8-K"], ticker="AMD")

# cik
download_quarter_tar(year=2024, quarter=1, forms=["10-Q"], cik="320193")

# list
download_year_tar(year=2024, forms=["10-Q"], ticker=["AMD", "NVDA"])

Ticker mapping uses packaged listed_filer_metadata.csv.

Latest Single Filing Mode

Supported in both download_quarter and download_quarter_tar.

Rules:

  • Omit all three: year, quarter, forms.
  • Provide at least one of: ticker or cik.
# simple latest
download_quarter(ticker="AAPL")
download_quarter(cik="320193")

# tar latest
download_quarter_tar(ticker="AAPL")
download_quarter_tar(cik="320193")

Output Layout

data/
  filings/
    10-Q/
      0000320193/
        0000320193-24-000069/
          ...documents...
  _state/
    manifest.json

If you pass a single ticker/cik, folder grouping can use that identifier under the form folder.

CLI

secfetch quarter --year 2024 --quarter 1 --forms 10-Q --ticker AAPL
secfetch year --year 2024 --forms 8-K --cik 320193
python -m secfetch --help

API Parameters

Common

  • year, quarter, forms
  • ticker, cik
  • data_dir, concurrency, show_progress
  • user_agent, manifest_path

Tar-specific

  • limit (cap number of filings)
  • extract=True (default; extracts and removes tar files)
  • tar_provider="datamule" (default)
  • datamule_api_key (optional)

Detailed Examples

Quarter by ticker, simple

download_quarter(
    year=2024,
    quarter=2,
    forms=["8-K", "10-Q"],
    ticker="MSFT",
    data_dir="data",
    show_progress=True,
)

Year by CIK, tar, limited

download_year_tar(
    year=2024,
    forms=["10-Q"],
    cik="320193",
    limit=30,
    data_dir="data",
)

Latest single filing, tar

download_quarter_tar(
    ticker="AAPL",
    data_dir="data",
)

Troubleshooting

  • No results: verify form type and ticker/cik mapping.
  • SEC errors: set valid SEC_USER_AGENT with contact email.
  • Slow download: tune concurrency and use limit for testing.
  • Latest mode error: provide ticker or cik when omitting year/quarter/forms.