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

# All Segmented Financials

> Get all segment breakdowns (income statement, balance sheet, cash flow) for any US stock in a single API call.

### Overview

This endpoint aggregates segment breakdowns from all three financial statement types into a single API call.

So, instead of calling 3 endpoints to get income statement segments, balance sheet segments, and cash flow statement segments, you can call this endpoint once and get all segment data in one go.

The endpoint returns segment breakdowns for:

* [Income Statement Segments](/api/financials/income-statement-segments) — revenue, operating income, depreciation
* [Balance Sheet Segments](/api/financials/balance-sheet-segments) — assets, goodwill, long-lived assets
* [Cash Flow Statement Segments](/api/financials/cash-flow-statement-segments) — capital expenditure

To get started, please create an account and grab your <b>API key</b> at [financialdatasets.ai](https://financialdatasets.ai).

You will use the API key to authenticate your API requests.

### Coverage

| Tickers | Years of Coverage | Updated         |
| ------- | ----------------- | --------------- |
| 6,400+  | 15+ years         | Within 1 second |

### Available Tickers

You can fetch a list of available tickers with a `GET` request to:
[https://api.financialdatasets.ai/financials/segments/tickers/](https://api.financialdatasets.ai/financials/segments/tickers/)

### Getting Started

There are only 3 steps for making a successful API call:

1. Add your API key to the header of the request as `X-API-KEY`.
2. Add query params like `ticker`, `period` and `limit` to filter the data.
3. Execute the API request.

### Filtering the Data

You can filter the data by `ticker`, `period`, `limit`, and `report_period`.

**Note**: `ticker` and `period` are required. Alternatively, you can use `cik` instead of `ticker` as a company identifier in your request.

By default, `period` is `annual`, `limit` is `4`, and `report_period` is `null`.

The `period` parameter can be set to `annual` or `quarterly`. The `limit` parameter is used to specify the number of periods to return.

The `report_period` parameter is used to specify the date of the statement.  For example, you can include filters like `report_period_lte=2024-09-30` and `report_period_gte=2024-01-01` to get statements between January 1, 2024 and September 30, 2024.

The available `report_period` operations are:

* `report_period_lte`
* `report_period_lt`
* `report_period_gte`
* `report_period_gt`
* `report_period`

### Example

```python All Segmented Financials theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests

# add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here"
}

# set your query params
ticker = 'AAPL'       # stock ticker
period = 'annual'     # possible values are 'annual' or 'quarterly'
limit = 5             # number of periods to return

# create the URL
url = (
    f'https://api.financialdatasets.ai/financials/segments'
    f'?ticker={ticker}'
    f'&period={period}'
    f'&limit={limit}'
)

# make API request
response = requests.get(url, headers=headers)

# parse segmented_financials from the response
segmented_financials = response.json().get('segmented_financials')

# each element is a per-period snapshot with all three statement types
for period_data in segmented_financials:
    income_statement = period_data.get('income_statement')    # dict or None
    balance_sheet = period_data.get('balance_sheet')          # dict or None
    cash_flow_statement = period_data.get('cash_flow_statement')  # dict or None
```

### Example (with report\_period)

```python All Segmented Financials theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests

# add your API key to the headers
headers = {
    "X-API-KEY": "your_api_key_here"
}

# set your query params
ticker = 'AAPL'
period = 'annual'
limit = 100
report_period_lte = '2024-01-01' # end date
report_period_gte = '2020-01-01' # start date

# create the URL
url = (
    f'https://api.financialdatasets.ai/financials/segments'
    f'?ticker={ticker}'
    f'&period={period}'
    f'&limit={limit}'
    f'&report_period_lte={report_period_lte}'
    f'&report_period_gte={report_period_gte}'
)

# make API request
response = requests.get(url, headers=headers)

# parse segmented_financials from the response
segmented_financials = response.json().get('segmented_financials')
```


## OpenAPI

````yaml GET /financials/segments
openapi: 3.0.1
info:
  title: Financial Datasets API
  description: >-
    Stock market API with real-time and historical financial data for 27,000+
    tickers over 30+ years. Financial statements, equity prices, insider trades,
    SEC filings, and more.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: API Support
    url: mailto:support@financialdatasets.ai
    email: support@financialdatasets.ai
  termsOfService: https://financialdatasets.ai/terms-of-use
servers:
  - url: https://api.financialdatasets.ai/
    description: Production server
security:
  - X-API-KEY: []
tags:
  - name: Financial Statements
    description: Access to income statements, balance sheets, and cash flow statements
  - name: Market Data
    description: Real-time and historical price data
  - name: Company Information
    description: Company facts like ticker, name, and description
  - name: Earnings
    description: Earnings data and related information
  - name: News
    description: Real-time and historical news articles
  - name: SEC Filings
    description: SEC filings and regulatory documents
  - name: Insider Trades
    description: Insider trading activity and transactions
  - name: Institutional Holdings
    description: SEC-direct 13F equity holdings of institutional investment managers
  - name: Index Funds
    description: >-
      ETF and index-fund holdings, weights, and the funds that hold a given
      security
  - name: Financial Metrics
    description: Financial ratios, metrics, and key performance indicators
  - name: Macroeconomics
    description: Real-time and historical macroeconomic data like interest rates
  - name: KPIs
    description: Sector-specific operational KPIs extracted from earnings releases.
paths:
  /financials/segments:
    get:
      tags:
        - Financial Statements
      summary: Get all segmented financials
      description: >-
        Get segment breakdowns from all three financial statement types (income
        statement, balance sheet, cash flow) in a single API call.
      operationId: getAllSegmentedFinancials
      parameters:
        - name: ticker
          in: query
          description: The ticker symbol. Required if cik is not provided.
          required: false
          schema:
            type: string
        - name: period
          in: query
          description: The time period of the data.
          required: true
          schema:
            type: string
            enum:
              - annual
              - quarterly
        - name: limit
          in: query
          description: The maximum number of periods to return.
          schema:
            type: integer
            format: int32
        - name: cik
          in: query
          description: The Central Index Key (CIK) of the company.
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ReportPeriod'
        - $ref: '#/components/parameters/ReportPeriodGte'
        - $ref: '#/components/parameters/ReportPeriodLte'
        - $ref: '#/components/parameters/ReportPeriodGt'
        - $ref: '#/components/parameters/ReportPeriodLt'
      responses:
        '200':
          description: All segmented financials response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentedFinancialsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  parameters:
    ReportPeriod:
      name: report_period
      in: query
      description: Filter by exact report period date in YYYY-MM-DD format.
      required: false
      schema:
        type: string
        format: date
    ReportPeriodGte:
      name: report_period_gte
      in: query
      description: >-
        Filter by report period greater than or equal to date in YYYY-MM-DD
        format.
      required: false
      schema:
        type: string
        format: date
    ReportPeriodLte:
      name: report_period_lte
      in: query
      description: Filter by report period less than or equal to date in YYYY-MM-DD format.
      required: false
      schema:
        type: string
        format: date
    ReportPeriodGt:
      name: report_period_gt
      in: query
      description: Filter by report period greater than date in YYYY-MM-DD format.
      required: false
      schema:
        type: string
        format: date
    ReportPeriodLt:
      name: report_period_lt
      in: query
      description: Filter by report period less than date in YYYY-MM-DD format.
      required: false
      schema:
        type: string
        format: date
  schemas:
    SegmentedFinancialsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/SegmentMetadata'
              - type: object
                properties:
                  income_statement:
                    type: object
                    nullable: true
                    description: Income statement segment breakdowns for this period.
                    properties:
                      revenue:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      operating_income:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      depreciation:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                  balance_sheet:
                    type: object
                    nullable: true
                    description: Balance sheet segment breakdowns for this period.
                    properties:
                      assets:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      goodwill:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                      long_lived_assets:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
                  cash_flow_statement:
                    type: object
                    nullable: true
                    description: Cash flow statement segment breakdowns for this period.
                    properties:
                      capital_expenditure:
                        nullable: true
                        allOf:
                          - $ref: '#/components/schemas/SegmentCategory'
    SegmentMetadata:
      type: object
      description: Common metadata fields for all segment responses.
      properties:
        ticker:
          type: string
          description: The ticker symbol.
        report_period:
          type: string
          format: date
          description: The reporting period.
        fiscal_period:
          type: string
          description: The fiscal period (e.g., Q1, Q2, Q3, Q4, FY).
        period:
          type: string
          enum:
            - quarterly
            - annual
          description: The time period.
        currency:
          type: string
          description: The reporting currency (e.g., USD, EUR, GBP).
        accession_number:
          type: string
          description: The SEC filing accession number.
        filing_url:
          type: string
          description: URL to the SEC filing.
    SegmentCategory:
      type: object
      description: Segment breakdowns grouped by category.
      properties:
        product:
          type: array
          description: Breakdowns by product line.
          items:
            $ref: '#/components/schemas/SegmentBreakdown'
        segment:
          type: array
          description: Breakdowns by business or operating segment.
          items:
            $ref: '#/components/schemas/SegmentBreakdown'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A short error message.
        message:
          type: string
          description: A more detailed error message.
    SegmentBreakdown:
      type: object
      properties:
        label:
          type: string
          description: The label for the segment (e.g., 'iPhone', 'Americas').
        value:
          type: number
          description: The value for the segment.
  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Bad Request
            message: Invalid request parameters
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
            message: Invalid API key provided
    PaymentRequiredError:
      description: The request requires a paid subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Payment Required
            message: >-
              This endpoint requires a paid subscription. Please upgrade your
              plan.
    NotFoundError:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Not Found
            message: Ticker XXXX not found
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      description: API key for authentication.
      in: header

````