---
title: "Annual or quarterly income statement, balance sheet or cash flow with normalized line items. Returns a FinancialStatement page, most recent period first."
method: POST
path: "/v2/ops/finance.financials"
tags: ["finance"]
---

# Annual or quarterly income statement, balance sheet or cash flow with normalized line items. Returns a FinancialStatement page, most recent period first.

`POST /v2/ops/finance.financials`

## Request

- Base URL: `https://api.agentkey.app`
- URL: `https://api.agentkey.app/v2/ops/finance.financials`
- Auth: HTTP bearer

One statement per call (statement=income|balance|cashflow), annual or quarterly. Line items are normalized to a fixed vocabulary (revenue, net_income, total_assets, operating_cash_flow …); a line the vendor does not report is null. A-shares come from Tushare (CNY), US filers from Finnhub (SEC XBRL facts; quarterly rows are 10-Q year-to-date figures) and AlphaVantage (single quarters).

Fixed price: 0.1 credits per successful call, whichever provider serves it.

## Request body

- object
  - `fields` string[]: Projection: keep only these dotted paths of data, e.g. ["items.id", "items.text"].
  - `include_raw` boolean: Attach the raw upstream payload as `raw` (not a stable contract; truncated above 256 KB).
  - `limit` integer: Maximum number of periods to return.
  - `period` 'annual' | 'quarterly': Reporting frequency (quarterly = single-quarter figures where the vendor distinguishes them, year-to-date where it does not).
  - `provider` string: Shorthand for routing.only = [provider].
  - `routing` Routing: Provider routing override. order: try these providers first; only: restrict to these (equivalent to pinning); allow_fallbacks: false tries only the first eligible provider.
    - `allow_fallbacks` boolean: false = try only the first eligible provider.
    - `only` string[]: Restrict to these providers.
    - `order` string[]: Providers to try first, in order.
    - `strategy` 'auto': How eligible providers are ordered. auto = the method's curated order. fastest / stable / popular are specified but not implemented yet (400 until then). The price is fixed whatever the strategy; mutually exclusive with order.
  - `statement` 'income' | 'balance' | 'cashflow': Which statement to return.
  - `symbol` string, required: Ticker: AAPL, 600519.SH.

## Response `200`

Success envelope

- FinancialStatementPageEnvelope: Success envelope whose data is a FinancialStatementPage.
  - `attempts` Attempt[], required
    - `error_type` string: validation | not_found | rate_limit | timeout | upstream_unauthorized | upstream_unavailable | provider_error
    - `provider` string, required: Provider slug.
    - `refunded` boolean: true when the reservation for this attempt was refunded.
    - `status` integer, required: HTTP status AgentKey mapped this attempt to (200 on success).
    - `took_ms` integer, required
    - `tool` string, required: Registry tool name (Provider/operation) that was called.
    - `upstream_status` integer: The provider's real HTTP status; absent when nothing was received.
  - `credits_charged` number, required: Credits charged for this call (the method's fixed price).
  - `data` object, required: One page of statement periods, most recent first.
    - `items` FinancialStatement[], required
      - `currency` string, nullable, required: ISO 4217 currency the amounts are reported in.
      - `fiscal_date` string, date, nullable, required: Fiscal period end, YYYY-MM-DD.
      - `lines` object, required: Normalized line items in `currency` major units (EPS in currency per share). A line the statement does not carry is null.
        - `capital_expenditure` number, nullable, required: Capital expenditure, as the vendor signs it (cashflow).
        - `cash_and_equivalents` number, nullable, required: Cash and cash equivalents (balance).
        - `cost_of_revenue` number, nullable, required: Cost of revenue / cost of goods sold (income).
        - `current_assets` number, nullable, required: Total current assets (balance).
        - `current_liabilities` number, nullable, required: Total current liabilities (balance).
        - `dividends_paid` number, nullable, required: Dividends paid, as the vendor signs it (cashflow).
        - `ebitda` number, nullable, required: EBITDA when the vendor reports it (income).
        - `eps_basic` number, nullable, required: Basic earnings per share (income).
        - `eps_diluted` number, nullable, required: Diluted earnings per share (income).
        - `financing_cash_flow` number, nullable, required: Net cash from financing activities (cashflow).
        - `free_cash_flow` number, nullable, required: Free cash flow when the vendor reports it (cashflow).
        - `gross_profit` number, nullable, required: Gross profit (income).
        - `income_tax` number, nullable, required: Income tax expense (income).
        - `interest_expense` number, nullable, required: Interest expense (income).
        - `investing_cash_flow` number, nullable, required: Net cash from investing activities (cashflow).
        - `long_term_debt` number, nullable, required: Long-term debt / borrowings (balance).
        - `net_income` number, nullable, required: Net income attributable to the company (income).
        - `operating_cash_flow` number, nullable, required: Net cash from operating activities (cashflow).
        - `operating_expenses` number, nullable, required: Total operating expenses (income).
        - `operating_income` number, nullable, required: Operating income / profit (income).
        - `pretax_income` number, nullable, required: Income before tax (income).
        - `revenue` number, nullable, required: Total revenue (income).
        - `total_assets` number, nullable, required: Total assets (balance).
        - `total_equity` number, nullable, required: Total shareholders' equity (balance).
        - `total_liabilities` number, nullable, required: Total liabilities (balance).
      - `period` 'annual' | 'quarterly', required: Reporting frequency of this record.
      - `report_date` string, date, nullable, required: Announcement / filing date when the vendor reports one, YYYY-MM-DD.
      - `statement` 'income' | 'balance' | 'cashflow', required: Which statement this record is.
      - `symbol` string, required: Ticker as requested.
    - `next_cursor` string, nullable, required: Opaque cursor for the next page; null when exhausted or the provider cannot page.
  - `op` string, required: Method name.
  - `op_version` integer, required: Method version that served the call.
  - `provider` string, required: Provider that actually served the call.
  - `raw` unknown
  - `raw_truncated` boolean
  - `request_id` string, required: Correlation id; quote it in support requests.
  - `took_ms` integer, required
  - `unsupported_fields` string[], required: Output paths this provider structurally does not supply; such fields are null for a different reason than 'missing on this record'.

## Other responses

- `400`: Validation error (unknown field, bad cursor, bad routing)
- `402`: Insufficient credits
- `404`: Not found (method, or upstream object)
- `429`: Rate limited upstream
- `502`: All providers failed
- `504`: Timed out

---

[API](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods.md) - [All operations](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/llms.txt) - [OpenAPI document](https://skmtc.dev/agentkey/apis/agentkey-scenario-methods/revisions/a7cf5b682fdd?raw)