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

# finance.financials

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



## OpenAPI

````yaml api-reference/openapi/v2.yaml POST /v2/ops/finance.financials
openapi: 3.1.0
info:
  description: >-
    Fixed, versioned, provider-independent methods over AgentKey's upstream
    catalog. Each method has a stable name, input schema and output schema; the
    server picks the upstream provider, fails over, normalizes fields and
    refunds failed attempts. Every response names the provider that served it,
    the credits charged and every attempt made.
  title: AgentKey Scenario Methods
  version: '2'
servers:
  - url: https://api.agentkey.app
security: []
paths:
  /v2/ops/finance.financials:
    post:
      tags:
        - finance
      summary: >-
        Annual or quarterly income statement, balance sheet or cash flow with
        normalized line items. Returns a FinancialStatement page, most recent
        period first.
      description: >-
        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.
      operationId: finance_financials
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                fields:
                  $ref: '#/components/schemas/FieldsProjection'
                include_raw:
                  $ref: '#/components/schemas/IncludeRaw'
                limit:
                  default: 4
                  description: Maximum number of periods to return.
                  maximum: 20
                  minimum: 1
                  type: integer
                period:
                  default: annual
                  description: >-
                    Reporting frequency (quarterly = single-quarter figures
                    where the vendor distinguishes them, year-to-date where it
                    does not).
                  enum:
                    - annual
                    - quarterly
                  type: string
                provider:
                  $ref: '#/components/schemas/ProviderShorthand'
                routing:
                  $ref: '#/components/schemas/Routing'
                statement:
                  default: income
                  description: Which statement to return.
                  enum:
                    - income
                    - balance
                    - cashflow
                  type: string
                symbol:
                  description: 'Ticker: AAPL, 600519.SH.'
                  type: string
              required:
                - symbol
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialStatementPageEnvelope'
          description: Success envelope
        '400':
          $ref: '#/components/responses/ValidationError'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '504':
          $ref: '#/components/responses/Timeout'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FieldsProjection:
      description: >-
        Projection: keep only these dotted paths of data, e.g. ["items.id",
        "items.text"].
      items:
        type: string
      type: array
    IncludeRaw:
      default: false
      description: >-
        Attach the raw upstream payload as `raw` (not a stable contract;
        truncated above 256 KB).
      type: boolean
    ProviderShorthand:
      description: Shorthand for routing.only = [provider].
      type: string
    Routing:
      additionalProperties: false
      description: >-
        Provider routing override. order: try these providers first; only:
        restrict to these (equivalent to pinning); allow_fallbacks: false tries
        only the first eligible provider.
      properties:
        allow_fallbacks:
          default: true
          description: false = try only the first eligible provider.
          type: boolean
        only:
          description: Restrict to these providers.
          items:
            type: string
          type: array
        order:
          description: Providers to try first, in order.
          items:
            type: string
          type: array
        strategy:
          default: auto
          description: >-
            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.
          enum:
            - auto
          type: string
      type: object
    FinancialStatementPageEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - properties:
            data:
              $ref: '#/components/schemas/FinancialStatementPage'
          type: object
      description: Success envelope whose data is a FinancialStatementPage.
    Envelope:
      description: Success envelope. `data` is the method's output object.
      properties:
        attempts:
          items:
            $ref: '#/components/schemas/Attempt'
          type: array
        credits_charged:
          description: Credits charged for this call (the method's fixed price).
          type: number
        data:
          description: Method output (typed per method).
        op:
          description: Method name.
          type: string
        op_version:
          description: Method version that served the call.
          type: integer
        provider:
          description: Provider that actually served the call.
          type: string
        raw:
          description: Upstream payload, only with include_raw=true. Not a stable contract.
        raw_truncated:
          type: boolean
        request_id:
          description: Correlation id; quote it in support requests.
          type: string
        took_ms:
          type: integer
        unsupported_fields:
          description: >-
            Output paths this provider structurally does not supply; such fields
            are null for a different reason than 'missing on this record'.
          items:
            type: string
          type: array
      required:
        - op
        - op_version
        - provider
        - request_id
        - credits_charged
        - took_ms
        - attempts
        - unsupported_fields
        - data
      type: object
    FinancialStatementPage:
      additionalProperties: false
      description: One page of statement periods, most recent first.
      properties:
        items:
          items:
            $ref: '#/components/schemas/FinancialStatement'
          type: array
        next_cursor:
          description: >-
            Opaque cursor for the next page; null when exhausted or the provider
            cannot page.
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
      type: object
    ErrorEnvelope:
      properties:
        attempts:
          items:
            $ref: '#/components/schemas/Attempt'
          type: array
        code:
          type: integer
        error:
          description: Human-readable message.
          type: string
        error_type:
          description: >-
            validation | not_found | rate_limit | timeout | insufficient_credits
            | upstream_unauthorized | upstream_unavailable | provider_error
          type: string
        op:
          description: Method name.
          type: string
        request_id:
          description: Correlation id.
          type: string
      required:
        - error
        - code
        - error_type
      type: object
    Attempt:
      description: >-
        One upstream try. Present on success and failure so a failover is never
        invisible.
      properties:
        error_type:
          description: >-
            validation | not_found | rate_limit | timeout |
            upstream_unauthorized | upstream_unavailable | provider_error
          type: string
        provider:
          description: Provider slug.
          type: string
        refunded:
          description: true when the reservation for this attempt was refunded.
          type: boolean
        status:
          description: HTTP status AgentKey mapped this attempt to (200 on success).
          type: integer
        took_ms:
          type: integer
        tool:
          description: Registry tool name (Provider/operation) that was called.
          type: string
        upstream_status:
          description: The provider's real HTTP status; absent when nothing was received.
          type: integer
      required:
        - provider
        - tool
        - status
        - took_ms
      type: object
    FinancialStatement:
      additionalProperties: false
      description: >-
        One reporting period of one statement, with the normalized core line
        items. Items that belong to another statement are null.
      properties:
        currency:
          description: ISO 4217 currency the amounts are reported in.
          type:
            - string
            - 'null'
        fiscal_date:
          description: Fiscal period end, YYYY-MM-DD.
          format: date
          type:
            - string
            - 'null'
        lines:
          description: >-
            Normalized line items in `currency` major units (EPS in currency per
            share). A line the statement does not carry is null.
          properties:
            capital_expenditure:
              description: Capital expenditure, as the vendor signs it (cashflow).
              type:
                - number
                - 'null'
            cash_and_equivalents:
              description: Cash and cash equivalents (balance).
              type:
                - number
                - 'null'
            cost_of_revenue:
              description: Cost of revenue / cost of goods sold (income).
              type:
                - number
                - 'null'
            current_assets:
              description: Total current assets (balance).
              type:
                - number
                - 'null'
            current_liabilities:
              description: Total current liabilities (balance).
              type:
                - number
                - 'null'
            dividends_paid:
              description: Dividends paid, as the vendor signs it (cashflow).
              type:
                - number
                - 'null'
            ebitda:
              description: EBITDA when the vendor reports it (income).
              type:
                - number
                - 'null'
            eps_basic:
              description: Basic earnings per share (income).
              type:
                - number
                - 'null'
            eps_diluted:
              description: Diluted earnings per share (income).
              type:
                - number
                - 'null'
            financing_cash_flow:
              description: Net cash from financing activities (cashflow).
              type:
                - number
                - 'null'
            free_cash_flow:
              description: Free cash flow when the vendor reports it (cashflow).
              type:
                - number
                - 'null'
            gross_profit:
              description: Gross profit (income).
              type:
                - number
                - 'null'
            income_tax:
              description: Income tax expense (income).
              type:
                - number
                - 'null'
            interest_expense:
              description: Interest expense (income).
              type:
                - number
                - 'null'
            investing_cash_flow:
              description: Net cash from investing activities (cashflow).
              type:
                - number
                - 'null'
            long_term_debt:
              description: Long-term debt / borrowings (balance).
              type:
                - number
                - 'null'
            net_income:
              description: Net income attributable to the company (income).
              type:
                - number
                - 'null'
            operating_cash_flow:
              description: Net cash from operating activities (cashflow).
              type:
                - number
                - 'null'
            operating_expenses:
              description: Total operating expenses (income).
              type:
                - number
                - 'null'
            operating_income:
              description: Operating income / profit (income).
              type:
                - number
                - 'null'
            pretax_income:
              description: Income before tax (income).
              type:
                - number
                - 'null'
            revenue:
              description: Total revenue (income).
              type:
                - number
                - 'null'
            total_assets:
              description: Total assets (balance).
              type:
                - number
                - 'null'
            total_equity:
              description: Total shareholders' equity (balance).
              type:
                - number
                - 'null'
            total_liabilities:
              description: Total liabilities (balance).
              type:
                - number
                - 'null'
          required:
            - revenue
            - cost_of_revenue
            - gross_profit
            - operating_expenses
            - operating_income
            - interest_expense
            - pretax_income
            - income_tax
            - net_income
            - eps_basic
            - eps_diluted
            - ebitda
            - total_assets
            - current_assets
            - cash_and_equivalents
            - total_liabilities
            - current_liabilities
            - long_term_debt
            - total_equity
            - operating_cash_flow
            - investing_cash_flow
            - financing_cash_flow
            - capital_expenditure
            - free_cash_flow
            - dividends_paid
          type: object
        period:
          description: Reporting frequency of this record.
          enum:
            - annual
            - quarterly
          type: string
        report_date:
          description: Announcement / filing date when the vendor reports one, YYYY-MM-DD.
          format: date
          type:
            - string
            - 'null'
        statement:
          description: Which statement this record is.
          enum:
            - income
            - balance
            - cashflow
          type: string
        symbol:
          description: Ticker as requested.
          type: string
      required:
        - symbol
        - statement
        - period
        - fiscal_date
        - report_date
        - currency
        - lines
      type: object
  responses:
    ValidationError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Validation error (unknown field, bad cursor, bad routing)
    InsufficientCredits:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Insufficient credits
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Not found (method, or upstream object)
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Rate limited upstream
    UpstreamFailed:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: All providers failed
    Timeout:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: Timed out
  securitySchemes:
    ApiKeyAuth:
      description: AgentKey API key (ak_…).
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.