sec-edgar-json

What questions it answers

• Which CIK is this ticker or company name? (edgar_lookup_company)
• What did this company file recently: 10-K, 10-Q, 8-K, with dates and document links? (edgar_recent_filings)
• What are its latest headline XBRL numbers: assets, revenue, net income and so on? (edgar_key_facts)
• Which filings mention this phrase? (edgar_full_text_search)
• What did every company report for one tag and period? (edgar_xbrl_frames)
• How has one tag moved over time for one company? (edgar_company_concept)
• Who filed insider Forms 3, 4 and 5, and what were the Form 4 transactions? (edgar_insider_forms)
• What 8-K item codes were filed, in words? (edgar_8k_items)

When to use it

An agent needs SEC filing data in a stable shape without learning EDGAR's columnar JSON and XML.

When not to

• Not investment advice or a data-quality guarantee. It relays what companies filed.
• edgar_key_facts returns one "latest" number per tag. Known issue: it can pick a year-to-date total instead of the quarter, and it can return an old value when a company stopped using a tag. Check end, fp and frame in the output, or use edgar_company_concept for the full series.
• Full-text search uses an SEC endpoint that SEC does not document as an API. It can change or fail.
• It returns links to filing documents, not the documents' text.
• Only the filings in SEC's "recent" list for a company are covered by filings, 8-K and insider calls (not the full history).

Example (CLI; the MCP tools take the same inputs)

npx tsx src/cli.ts filings MSFT 5 10-K

Trimmed output (shape from samples/filings-MSFT-10K.json):

{
  "tool": "sec-edgar-json",
  "version": "0.2.0",
  "cik": "0000789019",
  "name": "MICROSOFT CORP",
  "tickers": ["MSFT"],
  "sicDescription": "Services-Prepackaged Software",
  "filings": [
    {
      "form": "10-K",
      "filingDate": "2026-07-29",
      "reportDate": "2026-06-30",
      "accessionNumber": "0001193125-26-323660",
      "primaryDocument": "msft-20260630.htm",
      "items": "",
      "url": "https://www.sec.gov/Archives/edgar/data/789019/000119312526323660/msft-20260630.htm"
    }
  ],
  "cached": false,
  "source": "https://data.sec.gov/submissions/CIK0000789019.json",
  "billing": { "sku": "edgar_filings", "plannedPriceUsd": 0.03, "x402Enabled": false }
}

Key facts entry (shape): facts.Revenues = { label, unit, latest, end, form, filed, period, fp, frame, points, taxonomy }. 8-K rows carry itemsRaw and items: [{code, label}]. Frames return data: [{cik, entityName, loc, start, end, val, accessionNumber}].

Data source and licence

SEC EDGAR (sec.gov, data.sec.gov, efts.sec.gov). SEC filings are US government public records and are generally public domain; check SEC's terms and fair access policy for your use. Cite the SEC as the source. The tool adds no data of its own.

Freshness and limits

• Cached: ticker map 24 h, filings, 8-K items and submissions 1 h, key facts, concept and frames 6 h, full-text search 15 min, Form 4 parse 24 h. New filings can take up to the TTL to appear.
• Client rate: about 5 requests per second to SEC, with retry on 429/503.
• Result limits: filings 50, search 100, frames and concept 200 rows.
• Form 4 transactions are parsed from SEC XML for the filings returned (up to the limit); one extra SEC request per filing.

Errors are not charged

Payment settles only on a successful answer. Any response with status 400 or higher (bad input, not found, upstream failure) is never settled.