> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Finance Statements
> Returns canonical combined income, balance-sheet and cash-flow statements for US-listed companies with recent USD US-GAAP reports. Google Finance line items are matched to exact SEC fiscal closing dates and corroborated against reported revenue. Annual and quarterly responses normally cover five periods; trailing responses calculate rolling totals from four contiguous quarters. Each delta is a fractional change from the adjacent returned period; missing or zero denominators remain null. Restatements replace prior values, so this is not point-in-time data. Currency and the price-to-book, return-on-assets and return-on-capital fields remain null.
Coverage is limited to US-listed companies with recent USD US-GAAP filings. Statement values come from Google Finance; SEC filings supply exact fiscal closing dates and corroborating revenue. Rows that cannot be matched reliably are omitted.
The response contains `items[].financial_statement`, with income, balance-sheet and cash-flow fields together for each period. `type` supports annual (default), quarterly and trailing. The current source normally provides five annual and five quarterly periods.
Trailing values require four contiguous quarters. Flow fields and earnings per share are summed; balance-sheet fields use the latest quarter. Profit margin is calculated from the summed income and revenue. The trailing effective tax rate remains null because the source does not supply the components needed to weight it.
Deltas compare adjacent periods as `(current - prior) / abs(prior)`. A missing or zero prior value produces null, as does the earliest available period. Profit margins and tax rates use percent units. Currency, price-to-book, return-on-assets and return-on-capital remain null on this surface.
Period ends are reporting dates, not filing dates. Restatements can replace older figures. This endpoint does not reconstruct the information available at a historical date. Google Finance cash-flow and EBITDA definitions may differ from issuer-defined measures.
## OpenAPI
````yaml GET /finance/statements
openapi: 3.1.0
info:
title: SocialQuery API
version: '2026-10-09'
description: >-
Documented requests for public-source records. Inspect accepted inputs and
credit amounts, then verify the selected operation before integrating
preview coverage.
servers:
- url: https://socialquery.dev/v1
security:
- apiKey: []
paths:
/finance/statements:
get:
tags:
- Finance
summary: Finance Statements
description: >-
Returns canonical combined income, balance-sheet and cash-flow
statements for US-listed companies with recent USD US-GAAP reports.
Google Finance line items are matched to exact SEC fiscal closing dates
and corroborated against reported revenue. Annual and quarterly
responses normally cover five periods; trailing responses calculate
rolling totals from four contiguous quarters. Each delta is a fractional
change from the adjacent returned period; missing or zero denominators
remain null. Restatements replace prior values, so this is not
point-in-time data. Currency and the price-to-book, return-on-assets and
return-on-capital fields remain null.
operationId: get_finance_statements
parameters:
- name: keyword
in: query
required: true
example: AAPL
schema:
type: string
description: >-
US-listed ticker, optionally followed by :EXCHANGE. SEC dates
require recent USD US-GAAP filings.
- name: type
in: query
required: false
example: quarterly
schema:
type: string
enum:
- annual
- quarterly
- trailing
description: >-
annual (default), quarterly, or trailing. Trailing sums four
contiguous quarters; stock balances come from the latest quarter.
- name: Cache-Control
in: header
required: false
example: no-cache
schema:
type: string
- name: Idempotency-Key
in: header
required: false
example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
schema:
type: string
- name: X-Max-Credits
in: header
required: false
description: >-
Optional nonnegative integer cap on the maximum request hold. A live
request whose hold exceeds this cap returns 422
CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
requested limit; cache hits and successful idempotent replays cost
zero.
schema:
type: integer
minimum: 0
responses:
'200':
description: >-
Request completed. Interpret data using the selected resource
contract.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
type: object
required:
- success
- platform
- endpoint
- credits_used
- credits_remaining
- request_id
- cached
- data
properties:
success:
type: boolean
const: true
platform:
type: string
endpoint:
type: string
credits_used:
type: integer
minimum: 0
credits_remaining:
type:
- integer
- 'null'
request_id:
type: string
cached:
type: boolean
data:
type: object
required:
- items
- total
- next_cursor
- dropped
properties:
items:
type: array
items:
type: object
required:
- financial_statement
properties:
financial_statement:
$ref: '#/components/schemas/FinancialStatement'
total:
type: integer
next_cursor:
type:
- string
- 'null'
dropped:
type: integer
sources:
type: array
items:
type: string
_warnings:
type: array
items:
type: string
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'402':
$ref: '#/components/responses/Error402'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'405':
$ref: '#/components/responses/Error405'
'409':
$ref: '#/components/responses/Error409'
'422':
$ref: '#/components/responses/Error422'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'502':
$ref: '#/components/responses/Error502'
'503':
$ref: '#/components/responses/Error503'
'504':
$ref: '#/components/responses/Error504'
components:
schemas:
FinancialStatement:
type: object
required:
- revenue
- operating_expense
- net_income
- net_profit_margin
- earnings_per_share
- ebitda
- effective_tax_rate
- cash_and_short_term_investments
- total_assets
- total_liabilities
- total_equity
- shares_outstanding
- cash_from_operations
- cash_from_investing
- cash_from_financing
- net_change_in_cash
- free_cash_flow
- revenue_delta
- operating_expense_delta
- net_income_delta
- net_profit_margin_delta
- earnings_per_share_delta
- ebitda_delta
- cash_and_short_term_investments_delta
- total_assets_delta
- total_liabilities_delta
- cash_from_operations_delta
- cash_from_investing_delta
- cash_from_financing_delta
- net_change_in_cash_delta
- free_cash_flow_delta
- price_to_book
- return_on_assets
- return_on_capital
- id
- symbol
- statement
- period_type
- period_end
- currency
properties:
revenue:
type:
- number
- 'null'
operating_expense:
type:
- number
- 'null'
net_income:
type:
- number
- 'null'
net_profit_margin:
type:
- number
- 'null'
earnings_per_share:
type:
- number
- 'null'
ebitda:
type:
- number
- 'null'
effective_tax_rate:
type:
- number
- 'null'
cash_and_short_term_investments:
type:
- number
- 'null'
total_assets:
type:
- number
- 'null'
total_liabilities:
type:
- number
- 'null'
total_equity:
type:
- number
- 'null'
shares_outstanding:
type:
- number
- 'null'
cash_from_operations:
type:
- number
- 'null'
cash_from_investing:
type:
- number
- 'null'
cash_from_financing:
type:
- number
- 'null'
net_change_in_cash:
type:
- number
- 'null'
free_cash_flow:
type:
- number
- 'null'
revenue_delta:
type:
- number
- 'null'
operating_expense_delta:
type:
- number
- 'null'
net_income_delta:
type:
- number
- 'null'
net_profit_margin_delta:
type:
- number
- 'null'
earnings_per_share_delta:
type:
- number
- 'null'
ebitda_delta:
type:
- number
- 'null'
cash_and_short_term_investments_delta:
type:
- number
- 'null'
total_assets_delta:
type:
- number
- 'null'
total_liabilities_delta:
type:
- number
- 'null'
cash_from_operations_delta:
type:
- number
- 'null'
cash_from_investing_delta:
type:
- number
- 'null'
cash_from_financing_delta:
type:
- number
- 'null'
net_change_in_cash_delta:
type:
- number
- 'null'
free_cash_flow_delta:
type:
- number
- 'null'
price_to_book:
type:
- number
- 'null'
return_on_assets:
type:
- number
- 'null'
return_on_capital:
type:
- number
- 'null'
id:
type: string
symbol:
type: string
statement:
type: string
enum:
- combined
period_type:
type: string
enum:
- annual
- quarterly
- ttm
period_end:
type: string
format: date-time
currency:
type:
- string
- 'null'
SocialQueryError:
type: object
required:
- success
- platform
- endpoint
- credits_used
- credits_remaining
- request_id
- cached
- error
properties:
success:
type: boolean
const: false
platform:
type: string
endpoint:
type: string
credits_used:
type: integer
minimum: 0
credits_remaining:
type:
- integer
- 'null'
request_id:
type: string
cached:
type: boolean
error:
type: object
required:
- code
- type
- message
- status
- doc_url
properties:
code:
type: string
type:
type: string
message:
type: string
status:
type: integer
doc_url:
type: string
format: uri
responses:
Error400:
description: Upstream rejected the request.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error401:
description: Missing, expired, invalid, or revoked API key.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error402:
description: Insufficient SocialQuery credits.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error403:
description: Key scope or provider policy denied access.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error404:
description: Endpoint or upstream resource not found.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error405:
description: HTTP method is not supported.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error409:
description: Idempotency conflict or request in progress.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error422:
description: Invalid parameters.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error429:
description: Request limit reached.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error500:
description: Request processing failed.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error502:
description: Upstream service failed.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error503:
description: Provider or required service is unavailable.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
Error504:
description: Upstream service timed out.
headers:
X-Request-Id:
schema:
type: string
X-Credits-Used:
schema:
type: integer
X-Credits-Remaining:
schema:
type: string
X-Cache:
schema:
type: string
enum:
- HIT
- MISS
- BYPASS
content:
application/json:
schema:
$ref: '#/components/schemas/SocialQueryError'
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.