# SEC Filing Sections

> "Give me Item 1A (Risk Factors) of Apple's latest 10-K as text," or "list the tables in Microsoft's latest 10-Q," or "give me the tagged numbers (inline XBRL) in this filing."

- Status: MCP package (hosted access coming soon)

## The question it answers

"Give me Item 1A (Risk Factors) of Apple's latest 10-K as text," or "list the tables in Microsoft's latest 10-Q," or "give me the tagged numbers (inline XBRL) in this filing."

## Tools

| Tool | What you get | Planned price |
|---|---|---|
| `filing_resolve` | the filing's accession number, dates and primary document URL | $0.02 |
| `filing_list_sections` | the Items found, with title and size | $0.05 |
| `filing_get_section` | the text of one Item (optionally Markdown-ish) | $0.04 |
| `filing_extract_tables` | the filing's HTML tables as headers + rows | $0.04 |
| `filing_ixbrl_facts` | inline XBRL numeric facts: concept, value, unit, period | $0.05 |

## Use it when

- An agent needs a specific narrative section of a 10-K, 10-Q or 8-K without parsing the HTML itself.
- You need the numbers tagged in a filing, with the period and unit.

## Do not use it when

- You want clean financial time series. Use the SEC's `companyfacts` API for that; this tool reads one filing's document.
- You need a concept filter you can trust today. **Known bug in this version:** if the concept you ask for is not in the filing, the tool can return up to 400 unrelated facts (unsigned and unscaled) instead of none. Check each returned `concept`.
- You need tables limited to one Item (the `item` option on tables is ignored).

## Example call

There is no public HTTP route yet, so no curl example. Locally:
```bash
npx tsx src/cli.ts sections --ticker AAPL --form 10-K
```
MCP: `filing_list_sections {"ticker_or_cik":"AAPL","form":"10-K"}`, then `filing_get_section {"ticker_or_cik":"AAPL","form":"10-K","item":"1A","max_chars":20000}`.

Params shared by all: `ticker_or_cik` (ticker like `AAPL`, or a CIK number), `form` (default `10-K`; `10-K/A` also matches), `accession` (needs `ticker_or_cik` too). The newest filing of that form in the SEC "recent filings" list is used.

## Example response (`filing_list_sections`; trimmed; from the package's own AAPL sample)

```json
{
  "tool": "sec-filing-sections",
  "version": "0.1.0",
  "filing": {
    "cik": "0000320193", "name": "Apple Inc.", "tickers": ["AAPL"], "form": "10-K",
    "filingDate": "2025-10-31", "accessionNumber": "0000320193-25-000079",
    "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm"
  },
  "sectionCount": 23,
  "sections": [
    { "item": "1",  "title": "Business", "charCount": 16011 },
    { "item": "1A", "title": "Risk Factors", "charCount": 68059 }
  ],
  "cached": false,
  "billing": { "sku": "filing_list_sections", "plannedPriceUsd": 0.05, "x402Enabled": false }
}
```
The real response also has `textChars` (length of the flattened filing text).

`filing_ixbrl_facts` returns `facts[]` like `{ "concept": "RevenueFromContractWithCustomerExcludingAssessedTax", "name": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "value": "307003000000", "unit": "usd", "period": "2024-09-29/2025-09-27", "decimals": "-6", "scale": "6", "contextRef": "c-12" }`. The `value` already has the scale applied.

## Data sources and licence

SEC EDGAR: `sec.gov/files/company_tickers.json`, `data.sec.gov/submissions`, and the filing document under `sec.gov/Archives`. SEC filings are US public records. Check sec.gov's current terms and fair-access policy. Filings may include third-party material.

## Freshness and caching

The filing list is cached 1 hour, the ticker map 24 hours, and the filing HTML 15 minutes. Newly filed documents can take up to an hour to show as "latest".

## Honest limits

- Section boundaries are found with text patterns on the flattened document. Unusual layouts can miss or merge sections. One section per Item number, so a 10-Q's Part I and Part II items that share a number collapse into one.
- Only the SEC "recent" filing list is searched, not older archive pages.
- Markdown output is approximate.
- Tables are the first row as headers plus the remaining rows; merged cells are not resolved. Max 200 rows per table.
- iXBRL: numeric facts only (`ix:nonFraction`). The scale is applied in floating point, and European decimal-comma formats are read wrongly.
- Rate: about 5 requests per second to the SEC; a big call can take several seconds. Max 8 MB per fetched document.
- Not investment or legal advice.