> ## 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.

# Balance Sheet

> Get balance sheet segment breakdowns (assets, goodwill, long-lived assets) by business segment for any US public company.

### Overview

The balance sheet segments API provides as-reported segment breakdowns from SEC filings (10-Ks and 10-Qs) for a given stock ticker.

This includes segment data for metrics like:

* **Assets** — by business segment
* **Goodwill** — by business segment
* **Long-Lived Assets** — by business segment

These breakdowns are essential for sum-of-the-parts valuation, where analysts value each business segment independently.

The API returns this data in a clean, structured format:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "segmented_financials": [
    {
      "ticker": "AAPL",
      "report_period": "2025-12-27",
      "period": "quarterly",
      "assets": {
        "segment": [
          {"label": "Americas", "value": 50000000000.0},
          {"label": "Europe", "value": 35000000000.0},
          {"label": "Greater China", "value": 20000000000.0}
        ]
      },
      "goodwill": {
        "segment": [
          {"label": "Americas", "value": 5000000000.0},
          {"label": "Europe", "value": 3000000000.0}
        ]
      }
    }
  ]
}
```

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,200+  | 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/balance-sheets/segments/tickers/](https://api.financialdatasets.ai/financials/balance-sheets/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 Balance Sheet Segments 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/balance-sheets/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')
```

### Example (with report\_period)

```python Balance Sheet Segments 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/balance-sheets/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/balance-sheets/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/balance-sheets/segments:
    get:
      tags:
        - Financial Statements
      summary: Get balance sheet segments
      description: >-
        Get balance sheet segment breakdowns (assets, goodwill, long-lived
        assets) by business segment.
      operationId: getBalanceSheetSegments
      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: Balance sheet segments response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSheetSegmentsResponse'
        '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:
    BalanceSheetSegmentsResponse:
      type: object
      properties:
        segmented_financials:
          type: array
          items:
            $ref: '#/components/schemas/BalanceSheetSegments'
    BalanceSheetSegments:
      allOf:
        - $ref: '#/components/schemas/SegmentMetadata'
        - type: object
          properties:
            assets:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Assets broken down by segment.
            goodwill:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Goodwill broken down by segment.
            long_lived_assets:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/SegmentCategory'
              description: Long-lived assets broken down by segment.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A short error message.
        message:
          type: string
          description: A more detailed error message.
    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'
    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

````