Reading a 10-K as a Developer: The Five Sections That Actually Change a Thesis

A 10-K runs 100 to 200 pages for a mid-cap software company, and most of it is unchanged from the prior year. The legal boilerplate, the property descriptions, the accounting-policy recitals — all carried forward. What actually changes your view of a business is a small subset, and it is easier to find if you stop reading the document linearly and start treating it the way you'd treat any other versioned artifact: pull both revisions, diff them, and read what moved.

That framing is not a metaphor. The SEC publishes filings as structured data with stable identifiers, and you can build the whole workflow with an HTTP client and a diff library.

The filing is already an API

Three endpoints on data.sec.gov cover most of what you need, all keyed by a 10-digit zero-padded CIK:

• https://data.sec.gov/submissions/CIK##########.json — the company's full filing history, including accession numbers, form types, and filing dates. This is how you find the last two 10-Ks without scraping the browse UI.
• https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json — every XBRL-tagged number the company has ever reported, grouped by taxonomy tag (us-gaap:Revenues, us-gaap:ShareBasedCompensation, and so on), each with the fiscal period, form, and accession number it came from.
• https://data.sec.gov/api/xbrl/companyconcept/CIK##########/us-gaap/<Tag>.json — a single tag as a time series, which is the cheap way to chart one line item across a decade without downloading the full facts blob.

EDGAR full-text search covers filings from 2001 onward and is useful for the opposite direction: find every company whose 10-K mentions a term you care about, then pull their CIKs.

Two operational notes. The SEC requires a User-Agent header that identifies you with a real contact email, and its fair-access guidance caps automated traffic at roughly 10 requests per second. Requests without a declared User-Agent get blocked, and that failure mode looks like a generic 403, so check the header first when your scraper stops working.

XBRL gets you the numbers, not the argument. Narrative items — risk factors, MD&A — ship as HTML, not tagged facts, so you diff those as text. And companies extend the taxonomy with custom tags for anything non-standard, which means a naive us-gaap join across two companies can silently miss a segment or a revenue line. Always reconcile a tagged total back to the rendered statement before you build on it.

The five sections that move a thesis

Item 1A, Risk Factors — read the diff, not the list

The list itself is defensive drafting; nearly every risk factor is a lawyer protecting against a future securities claim. The signal is in what changed. A newly added risk factor means someone inside the company decided this year that the exposure was material enough to disclose, and that decision has a paper trail behind it. A removed one means the opposite. Reordering matters too: since the 2020 amendments to Regulation S-K, filers must organize risk factors under headings and add a summary if the section runs past 15 pages, so structural changes are deliberate rather than incidental.

Run a word-level diff of Item 1A across the two most recent 10-Ks. On a typical filing you'll get a handful of substantive additions out of thousands of lines.

Item 7, MD&A — management explaining its own variance

MD&A is where the company tells you why revenue moved. It's the only section where you get an attributed causal claim rather than a number. Since the 2020 amendments, the required baseline is a comparison of the two most recent fiscal years, with the older comparison left in the prior filing — so if you want a three-year narrative, you need the prior 10-K too.

What to extract: the stated drivers of each revenue change (price, volume, mix, FX, acquisitions), and whether those attributions are consistent with what management said last year. A company that attributed growth to "increased seats" one year and "increased price per seat" the next has told you something about the health of its expansion motion.

Item 8's notes — segments, disaggregation, and concentration

The statements themselves are three pages. The notes are 40, and that's where the composition lives.

• Segment note (ASC 280). FASB's ASU 2023-07 took effect for fiscal years beginning after December 15, 2023, which means 10-Ks from fiscal 2024 onward must disclose significant segment expenses that are regularly provided to the chief operating decision maker. That's materially more detail on segment cost structure than filings from a few years earlier.
• Revenue disaggregation (ASC 606). Revenue split by product line, geography, and timing of recognition. Point-in-time versus over-time recognition tells you how much of the top line is recurring.
• Concentration. Any customer over 10% of revenue must be disclosed. One customer at 22% is a different business than the same revenue spread across 400 accounts.
• Share-based compensation. The unrecognized compensation cost and the weighted-average period over which it will be recognized give you a forward schedule of dilution that the income statement alone doesn't show.

Item 9A, Controls and Procedures

Short section, high information density. Management has to assess internal control over financial reporting, and a disclosed material weakness is a direct statement that the numbers elsewhere in the filing may be unreliable. Auditor attestation on those controls is required for accelerated and large accelerated filers; smaller reporting companies below $100 million in revenue were exempted from the attestation requirement in 2020, so for small caps you're often reading management's own assessment with no independent check.

Executive compensation — usually incorporated by reference

Part III is typically a pointer to the proxy statement (DEF 14A) rather than content, so you'll need a second filing. It's worth the extra fetch: the compensation metrics tell you what the board pays management to optimize. If the bonus plan keys on bookings and the thesis depends on free cash flow, you've found a divergence. Pay-versus-performance disclosure, required since fiscal 2022, adds a standardized table for comparing realized pay against total shareholder return.

A workflow that fits in an afternoon

1. Pull submissions for the CIK, filter form == "10-K", take the two most recent accession numbers.
2. Fetch both filing documents, strip to Items 1A and 7 by heading, and diff them.
3. Pull companyfacts and snapshot the tags you care about across five years into a table.
4. Read the segment, disaggregation, and concentration notes by hand. This part does not automate well; the disclosure format varies too much between filers.
5. Write down what would have to be true for the thesis to break, and check whether Item 1A now names it.

Step 5 is the one people skip. The diff tells you what changed; it doesn't tell you whether the change matters to your specific argument, and that judgment has to be written down somewhere durable enough to revisit next year.

Keep one page per company with three fields: the thesis in two sentences, the three numbers that would falsify it, and a dated log of what each new filing changed. When the next 10-K drops, you're comparing against your own prior notes rather than re-deriving the whole picture. This is the difference between following a company and re-researching it every year.

---

Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.