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”

limit=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?period=annual&limit=5" \
  | jq '.data[] | {fiscal_year, revenue, operating_income, 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": [
    {
      "fiscal_year": 2024,
      "period_type": "annual",
      "revenue": 391035000000,
      "cost_of_revenue": 210352000000,
      "gross_profit": 180683000000,
      "research_and_development": 31370000000,
      "selling_general_admin": 26097000000,
      "operating_income": 123216000000,
      "pre_tax_income": 123485000000,
      "income_tax": 29749000000,
      "net_income": 93736000000,
      "eps_basic": 6.11,
      "eps_diluted": 6.08,
      "metadata": {
        "accession_number": "0000320193-24-000123",
        "filed_at": "2024-11-01",
        "currency": "USD",
        "source_tags": {
          "revenue": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
          "net_income": "us-gaap:NetIncomeLoss"
        },
        "mapping_quality": "exact"
      }
    }
    /* ... 4 more rows for FY2023, FY2022, FY2021, FY2020 ... */
  ],
  "pagination": {
    "page": 1,
    "per_page": 5,
    "total": 5,
    "total_pages": 1
  }
}

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 reporting currency. US issuers report in USD. IFRS 20-F foreign filers may report in native currency; Thesma’s canonical fields for those filers are partial until the Q2 2026 IFRS expansion — see XBRL mapping → IFRS 20-F.
  • 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 when you need an example in a blog post or dashboard — universally recognised, dense coverage, no IFRS edge cases. Avoid foreign private issuers (Spotify, Nu Holdings, GlobalFoundries) for canonical-field examples until the Q2 2026 IFRS work lands.

See also

Section titled “See also”