> ## 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.
# Line Items
> Search for specific financial statement line items across all US public companies.
### Overview
This Line Items Search API lets you pull specific line items for a list of tickers by specifying a set of `line_items` in your request.
Line items are financial data points that are found in the income statement, balance sheet, and cash flow statement.
Examples of line items are revenue, net income, total debt, free cash flow, and so on.
The purpose of this API is to let you easily get specific data points for a list of tickers in a single API request.
You can also specify a `start_date` and `end_date` to filter the line items by a specific date range.
Finally, you can specify a `period`, which must be one of `"ttm"`, `"annual"`, or `"quarterly"`.
For example, you can search for `net_income` and `total_debt` for NVDA and AAPL and receive the following response:
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"search_results": [
{
"ticker": "NVDA",
"report_period": "2024-07-28",
"period": "ttm",
"net_income": 53008000000,
"total_debt": 9765000000
},
{
"ticker": "AAPL",
"report_period": "2024-06-29",
"period": "ttm",
"net_income": 101956000000,
"total_debt": 101304000000
}
]
}
```
### Available Line Items
```python Income Statement theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid line_items for the income statement
line_items = [
"consolidated_income",
"cost_of_revenue",
"dividends_per_common_share",
"earnings_per_share",
"earnings_per_share_diluted",
"ebit",
"ebit_usd",
"earnings_per_share_usd",
"gross_profit",
"income_tax_expense",
"interest_expense",
"net_income",
"net_income_common_stock",
"net_income_common_stock_usd",
"net_income_discontinued_operations",
"net_income_non_controlling_interests",
"operating_expense",
"operating_income",
"preferred_dividends_impact",
"research_and_development",
"revenue",
"revenue_usd",
"selling_general_and_administrative_expenses",
"weighted_average_shares",
"weighted_average_shares_diluted",
]
```
```python Balance Sheet theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid line_items for the balance sheet
line_items = [
"accumulated_other_comprehensive_income",
"cash_and_equivalents",
"cash_and_equivalents_usd",
"current_assets",
"current_debt",
"current_investments",
"current_liabilities",
"deferred_revenue",
"deposit_liabilities",
"goodwill_and_intangible_assets",
"inventory",
"investments",
"non_current_assets",
"non_current_debt",
"non_current_investments",
"non_current_liabilities",
"outstanding_shares",
"property_plant_and_equipment",
"retained_earnings",
"shareholders_equity",
"shareholders_equity_usd",
"tax_assets",
"tax_liabilities",
"total_assets",
"total_debt",
"total_debt_usd",
"total_liabilities",
"trade_and_non_trade_payables",
"trade_and_non_trade_receivables",
]
```
```python Cash Flow Statement theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List of valid line line_items for the cash flow statement
line_items = [
"business_acquisitions_and_disposals",
"capital_expenditure",
"change_in_cash_and_equivalents",
"depreciation_and_amortization",
"dividends_and_other_cash_distributions",
"effect_of_exchange_rate_changes",
"investment_acquisitions_and_disposals",
"issuance_or_purchase_of_equity_shares",
"issuance_or_repayment_of_debt_securities",
"net_cash_flow_from_financing",
"net_cash_flow_from_investing",
"net_cash_flow_from_operations",
"share_based_compensation",
]
```
### Code Example
```python Financials Search theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
import json
# Add your API key to the headers
headers = {
"X-API-KEY": "your_api_key_here",
"Content-Type": "application/json"
}
# Prepare the request body
body = {
"period": "ttm",
"tickers": ["NVDA", "AAPL"],
"limit": 1,
"line_items": [
"net_income",
"total_debt"
]
}
# Create the URL
url = 'https://api.financialdatasets.ai/financials/search/line-items'
# Make API request
response = requests.post(url, headers=headers, data=json.dumps(body))
# Parse search results, which are ordered by report period, newest to oldest
search_results = response.json().get('search_results')
# Print the results
for result in search_results:
print(f"Ticker: {result['ticker']}")
print(f"Report Period: {result['report_period']}")
print(f"Revenue: ${result['net_income']:,.0f}")
print(f"Total Debt: ${result['total_debt']:,.0f}")
print("---")
```
## OpenAPI
````yaml POST /financials/search/line-items
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/search/line-items:
post:
tags:
- Financial Statements
summary: Search specific financial metrics
description: >-
Search for specific financial metrics across income statements, balance
sheets, and cash flow statements for a list of tickers.
operationId: searchLineItems
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchLineItemsRequest'
responses:
'200':
description: Successful search response
content:
application/json:
schema:
$ref: '#/components/schemas/FinancialsSearchResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
$ref: '#/components/responses/PaymentRequiredError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
SearchLineItemsRequest:
type: object
required:
- line_items
- tickers
properties:
line_items:
type: array
items:
type: string
description: The financial metric to search for.
minItems: 1
description: An array of line items to apply to the search.
tickers:
type: array
items:
type: string
description: The tickers to search for.
minItems: 1
description: An array of tickers to apply to the search.
period:
type: string
enum:
- annual
- quarterly
- ttm
default: ttm
description: The time period for the financial data.
limit:
type: integer
minimum: 1
default: 1
description: The maximum number of results to return.
FinancialsSearchResponse:
type: object
properties:
search_results:
type: array
items:
type: object
properties:
ticker:
type: string
description: The ticker symbol of the company.
report_period:
type: string
format: date
description: The reporting period of the financial data.
period:
type: string
enum:
- annual
- quarterly
- ttm
description: The time period of the financial data.
currency:
type: string
description: The currency of the financial data.
additionalProperties:
type: string
description: Additional financial metrics based on the search criteria.
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
````