# sec-edgar-json

> SEC EDGAR data as clean JSON

- Status: MCP package (hosted access coming soon)

## 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)

```bash
npx tsx src/cli.ts filings MSFT 5 10-K
```
Trimmed output (shape from `samples/filings-MSFT-10K.json`):
```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.