> ## 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 Sheets
> Get balance sheet data for any US stock ticker. Assets, liabilities, and equity with 30+ years of history.
### Overview
The balance sheets API provides balance sheet data for a given stock ticker.
Balance sheets are financial statements that summarize a company's assets, liabilities, and shareholders' equity at a specific point in time.
You can filter the data by `ticker`, `period`, `limit`, and `cik`.
The `period` parameter can be set to `annual`, `quarterly`, or `ttm` (trailing twelve months). The `limit` parameter is used to specify the number of statements to return.
To get started, please create an account and grab your API key at [financialdatasets.ai](https://financialdatasets.ai).
You will use the API key to authenticate your API requests.
### Coverage
| Tickers | Years of Coverage | Updated |
| ------- | ----------------- | --------------- |
| 19,000+ | 30+ 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/tickers/](https://api.financialdatasets.ai/financials/balance-sheets/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`, `quarterly`, or `ttm` (trailing twelve months). 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`
### Normalized vs. As-Reported
We support two views of the balance sheet:
* **Normalized** (this endpoint, `GET /financials/balance-sheets`): every filer mapped onto a single canonical schema (`total_assets`, `total_liabilities`, `shareholders_equity`, etc.). Consistent across companies and ideal for cross-company comparison and time-series analysis. Available from the 1990s onward.
* **As-Reported** (`GET /financials/balance-sheets/as-reported`): the balance sheet exactly as filed in the 10-K or 10-Q, with original labels and parent-child line item hierarchy. Ideal when you need the exact wording, ordering, or subtotal structure from the filing. Available from 2010 onward, when XBRL became standard for SEC filings and companies started to report more granular data.
### Examples
```python Normalized 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 = 'NVDA' # stock ticker
period = 'annual' # possible values are 'annual', 'quarterly', or 'ttm'
limit = 30 # number of statements to return
# create the URL
url = (
f'https://api.financialdatasets.ai/financials/balance-sheets'
f'?ticker={ticker}'
f'&period={period}'
f'&limit={limit}'
)
# make API request
response = requests.get(url, headers=headers)
# parse balance_sheets from the response
balance_sheets = response.json().get('balance_sheets')
```
```python As-Reported 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 = 'NVDA' # 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/as-reported'
f'?ticker={ticker}'
f'&period={period}'
f'&limit={limit}'
)
# make API request
response = requests.get(url, headers=headers)
# parse as_reported_balance_sheets from the response
as_reported_balance_sheets = response.json().get('as_reported_balance_sheets')
```
## OpenAPI
````yaml GET /financials/balance-sheets
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: Activist Ownership
description: Activist stakes from SEC Schedule 13D filings, in real time
- name: Beneficial Ownership
description: >-
Holders of more than 5% of a company's shares, from SEC Schedules 13D and
13G
- name: Insider Ownership
description: Insider ownership statements from SEC Forms 3 and 5
- 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:
get:
tags:
- Financial Statements
summary: Get balance sheets
description: Get balance sheets for a ticker.
operationId: getBalanceSheets
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 balance sheets.
required: true
schema:
type: string
enum:
- annual
- quarterly
- ttm
- name: limit
in: query
description: The maximum number of balance sheets 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'
- $ref: '#/components/parameters/FilingDate'
- $ref: '#/components/parameters/FilingDateGte'
- $ref: '#/components/parameters/FilingDateLte'
- $ref: '#/components/parameters/FilingDateGt'
- $ref: '#/components/parameters/FilingDateLt'
responses:
'200':
description: Balance sheets response
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceSheetResponse'
'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
FilingDate:
name: filing_date
in: query
description: >-
Filter by exact SEC filing date in YYYY-MM-DD format. Rows without a
known filing date are excluded.
required: false
schema:
type: string
format: date
FilingDateGte:
name: filing_date_gte
in: query
description: >-
Filter by SEC filing date greater than or equal to date in YYYY-MM-DD
format. Rows without a known filing date are excluded.
required: false
schema:
type: string
format: date
FilingDateLte:
name: filing_date_lte
in: query
description: >-
Filter by SEC filing date less than or equal to date in YYYY-MM-DD
format. Useful for point-in-time queries: returns only data that was
publicly filed by the given date. Rows without a known filing date are
excluded.
required: false
schema:
type: string
format: date
FilingDateGt:
name: filing_date_gt
in: query
description: >-
Filter by SEC filing date greater than date in YYYY-MM-DD format. Rows
without a known filing date are excluded.
required: false
schema:
type: string
format: date
FilingDateLt:
name: filing_date_lt
in: query
description: >-
Filter by SEC filing date less than date in YYYY-MM-DD format. Rows
without a known filing date are excluded.
required: false
schema:
type: string
format: date
schemas:
BalanceSheetResponse:
type: object
properties:
balance_sheets:
type: array
items:
$ref: '#/components/schemas/BalanceSheet'
BalanceSheet:
type: object
properties:
ticker:
type: string
description: The ticker symbol.
report_period:
type: string
format: date
description: The reporting period of the balance sheet.
fiscal_period:
type: string
description: The fiscal period of the balance sheet.
period:
type: string
enum:
- quarterly
- ttm
- annual
description: The time period of the balance sheet.
currency:
type: string
description: The currency in which the financial data is reported.
accession_number:
type: string
nullable: true
description: The SEC accession number of the filing.
filing_url:
type: string
nullable: true
format: uri
description: URL to the SEC filing.
filing_date:
type: string
format: date
nullable: true
description: >-
Calendar day SEC accepted the filing, in Eastern Time (the SEC's
operating timezone). Calendar-day pair to `filing_datetime`. Null
when no dated SEC filing is linked to the row.
filing_datetime:
type: string
format: date-time
nullable: true
description: >-
Sub-day timestamp recording when SEC accepted the filing, in Eastern
Time. Sourced from SEC's `acceptanceDateTime` field on the EDGAR
submissions API. Pairs with `filing_date` (calendar-day precision of
the same event).
total_assets:
type: number
nullable: false
description: The total assets of the company.
current_assets:
type: number
nullable: false
description: The current assets of the company.
cash_and_equivalents:
type: number
nullable: false
description: The cash and equivalents of the company.
inventory:
type: number
nullable: false
description: The inventory of the company.
current_investments:
type: number
nullable: false
description: The current investments of the company.
trade_and_non_trade_receivables:
type: number
nullable: false
description: The trade and non-trade receivables of the company.
non_current_assets:
type: number
nullable: false
description: The non-current assets of the company.
property_plant_and_equipment:
type: number
nullable: false
description: The property, plant, and equipment of the company.
goodwill_and_intangible_assets:
type: number
nullable: false
description: The goodwill and intangible assets of the company.
investments:
type: number
nullable: false
description: The investments of the company.
non_current_investments:
type: number
nullable: false
description: The non-current investments of the company.
outstanding_shares:
type: number
nullable: false
description: The outstanding shares of the company.
tax_assets:
type: number
nullable: false
description: The tax assets of the company.
total_liabilities:
type: number
nullable: false
description: The total liabilities of the company.
current_liabilities:
type: number
nullable: false
description: The current liabilities of the company.
current_debt:
type: number
nullable: false
description: The current debt of the company.
trade_and_non_trade_payables:
type: number
nullable: false
description: The trade and non-trade payables of the company.
deferred_revenue:
type: number
nullable: false
description: The deferred revenue of the company.
deposit_liabilities:
type: number
nullable: false
description: The deposit liabilities of the company.
non_current_liabilities:
type: number
nullable: false
description: The non-current liabilities of the company.
non_current_debt:
type: number
nullable: false
description: The non-current debt of the company.
tax_liabilities:
type: number
nullable: false
description: The tax liabilities of the company.
shareholders_equity:
type: number
nullable: false
description: The shareholders' equity of the company.
retained_earnings:
type: number
nullable: false
description: The retained earnings of the company.
accumulated_other_comprehensive_income:
type: number
nullable: false
description: The accumulated other comprehensive income of the company.
total_debt:
type: number
nullable: false
description: The total debt of the company.
ErrorResponse:
type: object
properties:
error:
type: string
description: A short error message.
message:
type: string
description: A more detailed error message.
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
````