Paragraph-offset citations inside a token budget

Read a section you can quote

What does Apple's latest 10-K say about economic conditions, and where exactly does it say it?

Three calls. The first finds the filing, the second says what is inside it and how big each part is, and the third reads one part in chunks that fit a budget you set. Every chunk comes back with the accession, the section, the paragraph index and the character range it was taken from, so a quote can be checked against EDGAR without trusting us.

Recorded Apple Inc., 10-K filed 2025-10-31, on 23 October 2026 against parser version 3. Responses are trimmed to the fields the example is about; elisions are marked.

1. list_filings

Resolve a ticker to accession numbers. Every filing question starts here.

Request

{
  "tool": "list_filings",
  "arguments": {
    "ticker": "AAPL",
    "form": [
      "10-K"
    ],
    "limit": 3
  }
}

Response

{
  "data": [
    { "accession": "0000320193-25-000079", "form": "10-K",
      "filed_at": "2025-10-31", "period": "2025-09-27",
      "primary_document": "aapl-20250927.htm" },
    { "accession": "0000320193-24-000123", "form": "10-K",
      "filed_at": "2024-11-01", "period": "2024-09-28" },
    { "accession": "0000320193-23-000106", "form": "10-K",
      "filed_at": "2023-11-03", "period": "2023-09-30" }
  ],
  "meta": {
    "company": { "cik": "320193", "name": "Apple Inc.",
                 "sic": "3571", "sicDescription": "Electronic Computers" },
    "returned": 3, "truncated": true, "oldest_available": "2015-10-02"
  }
}

truncated says the limit cut the list, and oldest_available says how far back the filer goes, so an agent knows the difference between the end of the history and the end of the page.

2. list_sections

Decide what to read before spending tokens reading it.

Request

{
  "tool": "list_sections",
  "arguments": {
    "accession": "0000320193-25-000079",
    "ticker": "AAPL"
  }
}

Response

{
  "data": [
    { "section_name": "item_1_business", "label": "Business",
      "char_length": 15901, "paragraph_count": 52, "is_stub": false },
    { "section_name": "item_1a_risk_factors", "label": "Risk Factors",
      "char_length": 67734, "paragraph_count": 106, "is_stub": false },
    { "section_name": "item_1b_unresolved_staff_comments",
      "label": "Unresolved Staff Comments",
      "char_length": 5, "paragraph_count": 1, "is_stub": true },
    { "section_name": "item_1c_cybersecurity", "label": "Cybersecurity",
      "char_length": 2678, "paragraph_count": 4, "is_stub": false }
    // ... 18 more
  ],
  "meta": { "parser_version": 3, "normalized_char_length": 205411,
            "returned": 22, "missing_sections": [] }
}

22 sections for a 10-K, and is_stub marks the ones that only say "None" or "Not applicable". A reader that skips the stubs saves a call per stub; a reader that does not know they are stubs spends a call to learn nothing.

3. get_filing_section

Read the section without spending the whole context window on it.

Request

{
  "tool": "get_filing_section",
  "arguments": {
    "accession": "0000320193-25-000079",
    "section": "item_1a_risk_factors",
    "max_tokens": 1500,
    "ticker": "AAPL"
  }
}

Response

{
  "data": [
    {
      "text": "The following summarizes factors that could have a material
               adverse effect on the Company's business, reputation, results
               of operations, financial condition and stock price. ...",
      "para_idx": 0, "char_start": 24556, "char_end": 25267,
      "token_count": 120,
      "citation": "0000320193-25-000079 item_1a_risk_factors para 0 chars 24556-25267 parser v3"
    }
    // ... 12 more chunks
  ],
  "meta": {
    "section_token_count": 11411, "paragraph_count": 106,
    "max_tokens": 1500, "returned": 13, "returned_tokens": 1468,
    "tokenizer": "o200k_base",
    "next_page_token": "eyJ2IjoxLCJwdiI6MywicyI6Iml0ZW1fMWFfcmlza19mYWN0b3JzIiwicCI6MTMsImMiOjMzMTQyfQ"
  }
}

The section is 11,411 tokens. You asked for 1,500 and got 1,468 in 13 chunks, plus a token for the next page. Pass it back as page_token to continue; it encodes the parser version, so a page token from before a parser change is refused rather than silently resuming in the wrong place.

What to take from this

  • A citation names the accession, the section, the paragraph and the character range. Those offsets are into the normalized filing text, and the parser version that produced them travels inside the citation, because an offset without one cannot be reproduced.
  • You set the token budget. The server never returns more than you asked for and never splits a paragraph to hit the number exactly. One chunk always comes back even when it alone exceeds the budget, so a caller paging through cannot stall.
  • section_token_count arrives in the first response, so an agent can decide whether to page, to narrow, or to give up before spending anything.

Next: See what changed since last year. Or run these tools against a filer of your own in the filing explorer, or read the full argument reference under the filings API.