> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial statements

> Structured income, balance-sheet, and cash-flow statements assembled from SEC XBRL filings, annual or quarterly, by ticker or CIK.

Financial Data API serves US company fundamentals as structured, period-keyed statements assembled from public SEC XBRL filings. One call returns three arrays (income statements, balance sheets, and cash-flow statements) for any company in the [scored universe](/apis/companies), with stable line-item keys mapped from XBRL concepts.

<Info>
  All fundamentals are derived from public SEC XBRL filings, so values are official-source and redistribution-safe. The financials endpoint requires the `data:read` scope.
</Info>

## What data is available

`GET /companies/{idOrLookup}/financials` returns three statement arrays, each element a single reporting period, newest first. Line items are mapped from SEC XBRL concepts into stable keys, so the same field name works across companies and periods. A line item is absent when the company did not report that concept for the period.

<Columns cols={3}>
  <Card title="Income statement" icon="chart-line">
    `revenue`, `cost_of_revenue`, `gross_profit`, `operating_expenses`, `research_and_development`, `selling_general_and_administrative`, `operating_income`, `net_income`, `earnings_per_share_diluted`, `weighted_average_shares_diluted`.
  </Card>

  <Card title="Balance sheet" icon="scale-balanced">
    `total_assets`, `current_assets`, `cash_and_equivalents`, `inventory`, `accounts_receivable`, `accounts_payable`, `current_liabilities`, `total_liabilities`, `long_term_debt`, `shareholders_equity`.
  </Card>

  <Card title="Cash flow statement" icon="money-bill-transfer">
    `net_cash_flow_from_operations`.
  </Card>
</Columns>

Statements are available at annual or quarterly frequency. Coverage is the S\&P 500 union Nasdaq-100 scored universe of US issuers; see the [companies endpoint](/apis/companies) for membership and use `GET /coverage` for live breadth.

<Note>
  A missing line-item key means "not reported", not zero. Treat absent keys as no value rather than assuming a value of zero.
</Note>

## Authentication

Send your key as `x-api-key` (or `Authorization: Bearer`) with the `data:read` scope. See [Authentication](/authentication).

## Look up by ticker, CIK, or entity id

The `idOrLookup` path segment accepts a Financial Data API entity id, a ticker, or a CIK. There is no separate resolve step required:

<Columns cols={3}>
  <Card title="By ticker" icon="hashtag">
    `GET /companies/AAPL/financials`
  </Card>

  <Card title="By CIK" icon="building">
    `GET /companies/0000320193/financials`
  </Card>

  <Card title="By entity id" icon="fingerprint">
    `GET /companies/ent_aapl/financials`
  </Card>
</Columns>

<Tip>
  If you want to confirm the entity first, resolve a ticker or CIK with `GET /entities/resolve`. See the [companies endpoint](/apis/companies#resolve-by-ticker-or-cik). It is optional: the path lookup matches ticker and CIK directly.
</Tip>

## Parameters

<Warning>
  Unknown query parameters are rejected with `bad_request`. Only `period` and `limit` are accepted here.
</Warning>

## Example: AAPL annuals

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/companies/AAPL/financials?period=annual&limit=3" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

  const { data: financials } = await client.request(
    "/companies/AAPL/financials",
    { period: "annual", limit: 3 }
  );

  for (const stmt of financials.income_statements) {
    console.log(stmt.periodEnd, stmt.revenue, stmt.net_income);
  }
  ```
</CodeGroup>

```json Response theme={"theme":"css-variables"}
{
  "data": {
    "entity_id": "ent_aapl",
    "ticker": "AAPL",
    "cik": "0000320193",
    "income_statements": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "revenue": 416161000000,
        "cost_of_revenue": 210352000000,
        "gross_profit": 205809000000,
        "operating_income": 132972000000,
        "net_income": 112010000000,
        "earnings_per_share_diluted": 7.39,
        "weighted_average_shares_diluted": 15150000000
      }
    ],
    "balance_sheets": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "total_assets": 364980000000,
        "current_assets": 152987000000,
        "cash_and_equivalents": 30299000000,
        "total_liabilities": 290437000000,
        "long_term_debt": 85750000000,
        "shareholders_equity": 74543000000
      }
    ],
    "cash_flow_statements": [
      {
        "period": "annual",
        "periodEnd": "2025-09-27",
        "currency": "USD",
        "net_cash_flow_from_operations": 118254000000
      }
    ]
  },
  "meta": { "api_version": "v1" },
  "requestId": "..."
}
```

<Note>
  Example figures above are illustrative. Pull live values from the endpoint.
</Note>

## Response shape

Every statement object shares three common fields plus its line items:

### Line items by statement

<AccordionGroup>
  <Accordion title="Income statement" icon="chart-line">
    `revenue`, `cost_of_revenue`, `gross_profit`, `operating_expenses`, `research_and_development`, `selling_general_and_administrative`, `operating_income`, `net_income`, `earnings_per_share_diluted`, `weighted_average_shares_diluted`.
  </Accordion>

  <Accordion title="Balance sheet" icon="scale-balanced">
    `total_assets`, `current_assets`, `cash_and_equivalents`, `inventory`, `accounts_receivable`, `accounts_payable`, `current_liabilities`, `total_liabilities`, `long_term_debt`, `shareholders_equity`.
  </Accordion>

  <Accordion title="Cash flow statement" icon="money-bill-transfer">
    `net_cash_flow_from_operations`.
  </Accordion>
</AccordionGroup>

A line item is absent from a statement object when the company did not report that concept for the period. Treat missing keys as "not reported", not zero.

## Worked example: resolve, then pull

<Steps>
  <Step title="Find the company in the universe">
    List `/companies` (or resolve a ticker) to get the identity and sector, and confirm membership before fetching statements.
  </Step>

  <Step title="Request statements by ticker">
    Call `/companies/{ticker}/financials` with `period=annual` and a `limit`. No separate id lookup is required, because the path accepts ticker and CIK.
  </Step>

  <Step title="Read period-keyed line items">
    Iterate `income_statements`, `balance_sheets`, and `cash_flow_statements`. Each element is one period; line items are stable keys. Missing keys mean the concept was not reported.
  </Step>

  <Step title="Trace any value to its filing">
    Each statement value originates from an observation. Pull the same fundamentals through `GET /entities/{entityId}/observations` and follow `GET /provenance/observations/{id}` to the named SEC source and ingestion run.
  </Step>
</Steps>

## Notes and caveats

<AccordionGroup>
  <Accordion title="Where the data comes from">
    Statements are assembled from individual SEC XBRL fundamentals observations, one per line item per period. The financials endpoint groups them into per-period statement objects so you do not have to.
  </Accordion>

  <Accordion title="Vintages and revisions">
    When a period has multiple reported vintages, the most recent value is used for each line item. The full history, including superseded values, remains queryable through the observations API with the `as_of` and knowledge-time filters. Note that `as_of` currently approximates the ingestion timestamp rather than full provider-vintage reconstruction.
  </Accordion>

  <Accordion title="Coverage breadth">
    The universe is US issuers in the S\&P 500 and Nasdaq-100. Use `GET /coverage` for the current catalog totals and covered categories rather than assuming a fixed count.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Companies" icon="building" href="/apis/companies">
    The scored universe and entity resolution by ticker or CIK.
  </Card>

  <Card title="Economic calendar & events" icon="calendar" href="/apis/economic-calendar">
    Company filings surface as `issuer_filing` events in the unified events feed.
  </Card>

  <Card title="Provenance" icon="route" href="/concepts/provenance">
    Trace any statement value back to its named SEC source and ingestion run.
  </Card>
</CardGroup>