EDGAR API Documentation

Quick Start

Make your first request

Use an API key in the query string for simple scripts, or send Authorization: Bearer when you want Swagger, the playground, and modern HTTP clients to share the same auth pattern.

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.edgarparser.com/api/metric?ticker=AAPL&year=2025&quarter=1&metric_name=Revenue&date_type=Q"

Python

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://www.edgarparser.com/api/metric",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "ticker": "AAPL",
        "year": 2025,
        "quarter": 1,
        "metric_name": "Revenue",
        "date_type": "Q",
    },
    timeout=30,
)

print(response.json())

Playground

Run a live request against the public API

The shared demo key is cache-only and intended for quick inspection. Try AAPL, MSFT, or NVDA for the best chance of a warm cache hit.

Playground traffic is authenticated with a shared Bearer token, rate limited per visitor IP, and restricted to pre-cached tickers.

Request Builder

Endpoint

Ticker

Year

Quarter

metric_name

periods

The playground always sends Authorization: Bearer ... so you can copy the same pattern into your own client.

Response

waiting 0 ms

No request sent yet

Authentication

Query param or Bearer header

Both auth styles are supported. If you send both on the same request, the Bearer header wins and the query-string key is ignored.

Query Param

curl "https://www.edgarparser.com/api/financials?ticker=AAPL&year=2025&quarter=1&key=YOUR_API_KEY"

Bearer Header

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.edgarparser.com/api/financials?ticker=AAPL&year=2025&quarter=1"

Empty or whitespace-only Bearer tokens resolve to the public tier. Non-Bearer schemes such as Basic fall back to ?key= if you provide it.

Route families

Parser features exposed by the API

The API now exposes the same layers used by the cached company pages: source-backed XBRL facts, dimensional facts, narrative sections, structured tables, metric search, extraction caches, and cache warming.

Financial facts

Dimensional facts

Financial fact payloads include axis_key, structured dimensions, source, and nested source_ref fields so segment, geography, product-line, instrument, and other XBRL-axis disclosures survive into API responses.

Filing tables

Structured filing tables

Sections can return structured table data with include_tables=true, while /api/tables and /api/tables/search expose table IDs, headers, rows, units, section placement, and xbrl_overlap.

Metrics

Tag equivalence

Metric lookup and series requests support alias and equivalence behavior for common XBRL tag variants, including explicit split-group errors when a former group has been divided into narrower replacements.

Premium

Premium extraction search

Paid and internal clients can query cached langextract spans through /api/extractions/search and /api/extractions/series with schema, class, period-range, source, stale-cache, and attribute filters.

API at a glance

Public tool surface

This matrix is rendered from docs/tool_manifest.yaml. Per-tool parameters, schemas, examples, and error notes live in the full reference.

Full API Reference Open Swagger

XBRL facts 13 tools

Tool	Summary	Tier	HTTP surface	Reference
`get_financials` Financials	Return the full structured XBRL financial fact payload for one filing period.	public	`GET /api/financials`	Reference
`get_metric` Metric	Return one discovered metric or XBRL tag with current, prior, and YoY values.	public	`GET /api/metric`	Reference
`get_metric_series` Metric Series	Return one metric across multiple periods with per-period cache and coverage status.	public	`GET /api/metric/series`	Reference
`list_metrics` List Metrics	List exact metric candidates available in one filing period.	public	`GET /api/financials/list_metrics`	Reference
`search_metrics` Search Metrics	Search filing metrics by natural-language query and return ranked exact candidates.	public	`GET /api/financials/search_metrics`	Reference
`get_statement` Statement	Return a template-backed income statement, balance sheet, or cash flow statement from cached concepts.	public	`GET /api/statement`	Reference
`get_concept` Concept	Resolve one registry-backed financial concept from cached filing facts.	public	`GET /api/concept`	Reference
`compare_concept` Compare Concept	Compare one registry-backed concept across a caller-provided ticker set.	public	`POST /api/concept/compare`	Reference
`concept_trend` Concept Trend	Return a cache-only concept time series across a requested period range.	public	`GET /api/concept/trend`	Reference
`cite_concept` Cite Concept	Join a registry-backed concept value to filing prose and optional extraction evidence.	paid	`POST /api/concept/cite`	Reference
`warm_metric_cache` Warm Metric Cache	Queue paid-tier background warming for metric periods before follow-up reads.	paid	`POST /api/warm`	Reference
`warm_metric_cache_status` Warm Metric Cache Status	Poll a background cache-warming job returned by warm_metric_cache.	paid	`GET /api/warm/{job_id}`	Reference
`get_tag_equivalence_registry` Tag Equivalence Registry	Return registry-backed XBRL tag equivalence groups for client taxonomy alignment.	public	`GET /api/tag_equivalence`	Reference

Filings 7 tools

Tool	Summary	Tier	HTTP surface	Reference
`get_filings` Filings	Return filing metadata and SEC accession details for one ticker period.	public	`GET /api/filings`	Reference
`get_event_filings` Event Filings	Discover event filings by ticker, CIK, date range, form type, or query.	public	`GET /api/filings/events`	Reference
`describe_filing` Describe Filing	Show cached availability for financials, sections, tables, markdown, and extractions for one filing.	public	`GET /api/filing/describe`	Reference
`get_filing_document` Filing Document	Return a readable markdown filing document with section filtering and pagination.	registered	`GET /api/filing/document`	Reference
`get_filing_sections` Filing Sections	Extract selected qualitative filing sections and optional embedded tables.	public	`GET /api/sections`	Reference
`get_filing_cover_facts` Filing Cover Facts	Return exact DEI cover-page facts such as shares outstanding with citations.	registered	`GET /api/filing/cover-facts`	Reference
`get_filing_evidence` Filing Evidence	Plan and retrieve citation-ready filing evidence for qualitative SEC questions.	paid	`POST /api/filing/evidence`	Reference

Tables 3 tools

Tool	Summary	Tier	HTTP surface	Reference
`get_filing_tables` Filing Tables	Return filing table metadata or one hydrated structured table.	public	`GET /api/tables`	Reference
`search_filing_tables` Search Filing Tables	Search cached filing table metadata across a ticker and period range.	public	`GET /api/tables/search`	Reference
`compare_filing_tables` Compare Filing Tables	Compare matching filing tables across multiple tickers.	public	`POST /api/tables/compare`	Reference

Text search 1 tools

Tool	Summary	Tier	HTTP surface	Reference
`search_filing_text` Search Filing Text	Search cached markdown within one filing and return matching spans.	registered	`GET /api/filing/text/search`	Reference

Langextract 5 tools

Tool	Summary	Tier	HTTP surface	Reference
`get_filing_extractions` Filing Extractions	Return cached langextract spans for one filing or run paid extraction on cache miss.	paid	`POST /api/extractions`	Reference
`search_extractions` Search Extractions	Search cached langextract spans across filings with structured filters.	paid	`GET /api/extractions/search`	Reference
`get_extraction_series` Extraction Series	Return periodized counts and optional hits for cached langextract spans.	paid	`GET /api/extractions/series`	Reference
`extract_filing_file` Extract Filing File	Ingest a trusted local markdown filing and run a selected extraction schema.	internal	`MCP only`	Reference
`list_extraction_schemas` List Extraction Schemas	List document extraction schemas available to the internal document API.	internal	`GET /api/documents/schemas`	Reference

Operational KPIs 1 tools

Tool	Summary	Tier	HTTP surface	Reference
`get_operational_kpi_drivers` Operational KPI Drivers	Extract non-XBRL operational KPI values and driver growth rates from filing narrative.	paid	`GET /api/operational-kpis/drivers`	Reference

Rate Limits

Tier behavior

Playground traffic is intentionally constrained. Production tiers are meant for direct client use; the shared demo key is for read-only cache inspection. MCP calls use the same API key pool and tier bucket as direct HTTP calls.

Tier	Limit	Bucket	Notes
Public	5 per 7 days	Per IP	No key required.
Registered	20 per 7 days	Per key	Free signup tier.
Paid	500 per 7 days	Per key	Paid tools, extraction caches, and warm workflows.
Playground	30 per hour	Per visitor IP	Shared demo key, cache-only for warm tickers.

MCP traffic is not a separate quota. Agents authenticate with the same key, receive the same tier permissions, and draw from the same rate-limit bucket as API requests.

MCP Server

Use the same API through MCP

The edgar-mcp package wraps the deployed API for agent workflows in Claude Code and other MCP clients.

Install

pip install edgar-mcp

Claude Code config

"edgar-financials": {
  "type": "stdio",
  "command": "python3",
  "args": [
    "/Users/henrychien/Documents/Jupyter/Edgar_updater/mcp_server.py"
  ],
  "env": {
    "EDGAR_API_KEY": "YOUR_KEY_HERE"
  }
}

GitHub: henrysouchien/edgar-mcp

Tool inventory

MCP exposes the same manifest-backed tool set shown in the matrix above, including XBRL facts, filing evidence, tables, text search, extraction caches, and operational KPI tools. MCP calls use the same API key pool as direct API requests.

MCP Setup Tool Matrix

OpenAPI

Swagger UI and ReDoc

Use the generated schema for client generation, or test requests directly in Swagger UI with the Authorize button. Both the query-param key and Bearer auth are registered in the schema.

Open Swagger UI Open ReDoc

Swagger UI exposes both ApiKeyQuery and BearerAuth, so the same schema works for copy-paste curl usage and the interactive Authorize flow.

EDGAR API documentation for source-backed filing data.

Production endpoint