Skip to main content
Pull structured revenue, net income, and other financial metrics directly from 10-K filings without manually parsing XBRL or HTML. This tutorial walks through finding a company’s latest annual filing, retrieving its financial statements, and extracting specific XBRL facts.

​
Prerequisites

  • An SEC API key (set as SECAPI_API_KEY)
  • Basic familiarity with REST APIs
  • (Optional) Python 3.8+ or Node.js 18+ for SDK examples

​
Step 1 — Find the latest 10-K filing

Start by fetching the most recent 10-K for a given ticker. The /v1/filings/latest endpoint returns the newest filing matching your criteria.

​
curl

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/filings/latest?ticker=AAPL&form=10-K"

​
Python

import os

from secapi_client import SecApiClient

client = SecApiClient(api_key=os.environ["SECAPI_API_KEY"])

filing = client.latest_filing(ticker="AAPL", form="10-K")
print(filing["accessionNumber"])
print(filing["filingDate"])

​
JavaScript

import { SecApiClient } from "@secapi/sdk-js";

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY!,
});

const filing = await client.latestFiling({
  ticker: "AAPL",
  form: "10-K",
});
console.log(filing.accessionNumber);
console.log(filing.filingDate);

​
Expected output

{
  "accessionNumber": "0000320193-24-000081",
  "form": "10-K",
  "filingDate": "2024-11-01",
  "companyName": "Apple Inc",
  "cik": "0000320193"
}

​
Step 2 — Retrieve financial statements

With the filing identified, pull the structured income statement using /v1/statements. This returns XBRL-sourced line items already mapped to a normalized schema.

​
curl

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/statements/all?ticker=AAPL&period=annual&limit=1"

​
Python

statements = client.all_statements(
    ticker="AAPL",
    period="annual",
    limit=1,
)

income = statements["income_statement"]
print(f"Revenue: {income['revenue']}")
print(f"Net Income: {income['net_income']}")
print(f"Gross Profit: {income['gross_profit']}")

​
JavaScript

const statements = await client.allStatements({
  ticker: "AAPL",
  period: "annual",
  limit: 1,
});

const income = statements.incomeStatement;
console.log(`Revenue: ${income.revenue}`);
console.log(`Net Income: ${income.netIncome}`);
console.log(`Gross Profit: ${income.grossProfit}`);

​
Expected output

{
  "income_statement": {
    "revenue": 383285000000,
    "cost_of_revenue": 214137000000,
    "gross_profit": 169148000000,
    "net_income": 93736000000,
    "period": "2024-09-28",
    "fiscal_year": 2024
  }
}

​
Step 3 — Extract specific XBRL facts

For granular control, use /v1/facts to pull individual XBRL concepts. This is useful when you need a specific metric that may not appear in the normalized statement schema.

​
curl

curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/facts?ticker=AAPL&tag=Revenues&period=annual&limit=4"

​
Python

facts = client.facts(
    ticker="AAPL",
    tag="Revenues",
    period="annual",
    limit=4,
)

for fact in facts["data"]:
    print(f"{fact['periodEnd']}: ${fact['value']:,.0f}")

​
JavaScript

const facts = await client.facts({
  ticker: "AAPL",
  tag: "Revenues",
  period: "annual",
  limit: 4,
});

for (const fact of facts.data) {
  console.log(`${fact.periodEnd}: $${fact.value.toLocaleString()}`);
}

​
Expected output

2024-09-28: $383,285,000,000
2023-09-30: $383,933,000,000
2022-10-01: $394,328,000,000
2021-09-25: $365,817,000,000

​
Next steps

  • Compare multiple companies: Loop over a list of tickers to build a revenue comparison table.
  • Add quarterly data: Change period=annual to period=quarterly for more granular trends.
  • Explore all statement types: Use /v1/statements/all to retrieve balance sheets and cash flow statements alongside income statements.
  • Build dashboards: Pipe the JSON output into your visualization tool of choice.
See the API Reference for the full list of available endpoints and parameters.