Skip to content
Thesma docs

Fetch 5 years of annual financials

Get a 5-year annual income-statement history for a single US public company. Apple (AAPL) as the worked example because its coverage is dense and the numbers are universally recognisable.

Problem

Section titled “Problem”

You want a 5-year revenue, operating income, and net income trend for a public company. Traditionally that’s scraping 10-Ks or wrangling XBRL. With Thesma, it’s one endpoint call per year (or a single time-series call per canonical metric).

curl — annual history

Section titled “curl — annual history”

per_page=5 gets the five most recent annual periods in one call:

Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL/financials?statement=income&period=annual&per_page=5" \
  | jq '.data[] | {fiscal_year, line_items: {revenue: .line_items.revenue, operating_income: .line_items.operating_income, net_income: .line_items.net_income}}'

Python SDK

Section titled “Python SDK”
from thesma import ThesmaClient


client = ThesmaClient()


financials = client.sec.companies("AAPL").financials(
    period="annual",
    limit=5,
)


for row in financials.data:
    print(f"FY{row.fiscal_year}  revenue=${row.revenue:,}  net_income=${row.net_income:,}")

Expected response shape

Section titled “Expected response shape”

Structurally exact at publication. Value-level numbers illustrative — exact figures drift as new filings land; field names and types are stable.

{
  "data": [
    {
      "company": {
        "cik": "0000320193",
        "ticker": "AAPL",
        "name": "Apple Inc."
      },
      "statement": "income",
      "period": "annual",
      "fiscal_year": 2025,
      "fiscal_quarter": null,
      "fiscal_year_end": "2025-09-27",
      "filing_accession": "0000320193-25-000079",
      "taxonomy": "us-gaap",
      "currency": "USD",
      "line_items": {
        "revenue": 416161000000.0,
        "cost_of_revenue": 220960000000.0,
        "gross_profit": 195201000000.0,
        "operating_income": 133050000000.0,
        "pre_tax_income": 132729000000.0,
        "net_income": 112010000000.0,
        "eps_basic": 7.49,
        "eps_diluted": 7.46
      },
      "metadata": {
        "source": "ixbrl",
        "data_completeness": 14,
        "expected_fields": 23
      }
    }
    /* ... 4 more elements for FY2024, FY2023, FY2022, FY2021 with the same shape ... */
  ]
}

Note: data is an array even when you ask for one period — iterate or index data[0]. The 8 line_items shown above (revenue → eps_diluted) are the same fields surfaced on the Quickstart; the full response includes additional line items per XBRL mapping.

Alternative — single-metric time series

Section titled “Alternative — single-metric time series”

If you only need one metric (say, revenue) across all available years, use the per-metric endpoint. It returns a longer history in one call:

Terminal window
curl -H "X-API-Key: $THESMA_API_KEY" \
  "https://api.thesma.dev/v1/us/sec/companies/AAPL/financials/revenue?period=annual" \
  | jq '.data[] | {fiscal_year, value}'

Returns every annual revenue value on record — typically 10+ years for mature filers.

Gotchas

Section titled “Gotchas”
  • fiscal_year is the year the period ends, not the filing calendar year. Apple’s FY2024 ended September 2024 and was filed November 2024. See XBRL mapping → Period-end date alignment if this bites.
  • Values are always reported in the filer’s presentation currency. US issuers report in USD. IFRS 20-F filers report in their native currency (Spotify in EUR, Nu Holdings in USD, Birkenstock in EUR, and others) with no USD conversion in v1. See the IFRS filer recipe for a worked example and XBRL mapping → IFRS 20-F for the six comparability caveats.
  • Quarterly has a different shape. Swap period=annual for period=quarterly for 10-Q data. Quarterly fiscal quarters are labeled by fiscal year + quarter (2024-Q4, 2025-Q1), not calendar quarter.

Stable example targets

Section titled “Stable example targets”

Apple (AAPL) and Microsoft (MSFT) are recommended for US-GAAP examples — universally recognised and dense coverage. For IFRS examples, use Spotify (CIK 1639920), Nu Holdings (CIK 1691493), or any of the other Thesma-verified IFRS anchors listed on XBRL mapping — IFRS 20-F. The IFRS filer recipe is the sibling of this recipe using Spotify.

See also

Section titled “See also”