Financials

Endpoints for financial statements (income, balance sheet, cash flow), concept resolution, and financial screens. Data comes from the pre-computed fund_* mart — no live vendor fetches on the read path.

Coverage: ~25,000 public companies globally. TTM (trailing twelve months) normalized to USD for cross-market comparability.

---

Endpoints

Method	Path	Description
GET	/v1/financials	Financial statements for one or more tickers
GET	/v1/financials/compare	Side-by-side comparison across companies
GET	/v1/financials/find	Resolve a financial concept phrase to a canonical key
POST	/v1/financials/find	Batch concept resolution (up to 25 queries)
GET	/v1/financials/find-pattern	Resolve a temporal pattern phrase
POST	/v1/financials/find-pattern	Batch pattern resolution
GET	/v1/financials/screen	Multi-condition financial screener

---

GET /v1/financials

Financial statements for one or more tickers. Returns ratios, TTM/annual/quarterly income, balance sheet, and cash flow.

Query parameters

Parameter	Type	Required	Description
ticker	string	✅	One ticker or comma-separated list of up to 5 (e.g. AAPL.US or AAPL.US,MSFT.US,2330.TW). Also accepted as tickers.
period	string	—	Time range selector. See period formats. Defaults to recent annual.
fields	string	—	Scope selector: income, balance, cashflow, all. Default is the digest (ratios + top-line metrics).
currency	string	—	Target currency for absolute dollar amounts. Default USD.
format	string	—	text — compact text table (~70% fewer tokens, useful for LLM contexts). Default json.

Get Apple financials (default digest)

GET /v1/financials?ticker=AAPL.US

Full income statement for Toyota (JPY)

GET /v1/financials?ticker=7203.JP&fields=income&currency=JPY

Compare 3 stocks — ratios only

GET /v1/financials?ticker=AAPL.US,MSFT.US,GOOGL.US

Period formats

The period parameter is flexible:

Format	Example	What it returns
Integer (years)	5	Last 5 annual periods
Year range	2022-2024	Annual periods 2022 through 2024
Comma list	2020,2022,2024	Specific years only
Quarterly count	5q	Last 5 quarters
Quarter spec	2024Q2	A specific quarter
Keyword	quarterly	All available quarters

---

GET /v1/financials/compare

Side-by-side comparison across companies. Returns normalized metrics for each company in a table-friendly shape. Pulls from the pre-computed mart — no live fetches.

Parameter	Type	Required	Description
ids	string	✅	Comma-separated tickers or integer head listing ids. Also accepted as tickers.
basis	string	—	A (default) — annual. Q — quarterly.
n	integer	—	Number of periods per company. Default 6.
currency	string	—	Currency for absolute dollar amounts. Default USD.
lang	string	—	Language code for field labels. Default en.

Compare FAANG — last 6 annual periods

GET /v1/financials/compare?ids=AAPL.US,AMZN.US,GOOGL.US,META.US,NFLX.US

---

GET /v1/financials/find

Resolve a financial concept phrase to a canonical field key. Accepts any language or phrasing — "수익성", "利益率", "profit margin", "EBITDA margin". Returns ranked candidates.

This is the field-axis resolver (WHAT metric). For the pattern axis (HOW it changes), use find-pattern.

Parameter	Type	Required	Description
q	string	✅	Concept phrase to resolve.
statement	string	—	Restrict to one statement: income, balance, or cashflow.
limit	integer	—	Max candidates. Default 8.

GET /v1/financials/find?q=gross+profit+margin

:::tip Free resolver GET /v1/financials/find charges 0 credits. Use it to translate natural-language field names before building a screen. :::

---

POST /v1/financials/find

Batch version — resolve many concept phrases in one call. Resolves concurrently server-side.

Request body

{
  "queries": ["gross margin", "debt to equity", "free cash flow yield"],
  "statement": "income",
  "limit": 5
}

Field	Type	Required	Description
queries	string[]	✅	List of phrases. Max 25.
statement	string	—	income, balance, or cashflow.
limit	integer	—	Candidates per query. Default 8.

---

GET /v1/financials/find-pattern

Resolve a temporal pattern phrase to a pattern key. The pattern axis controls the SHAPE of the metric over time — "growing consecutively", "turning profitable", "margin expanding".

Parameter	Type	Required	Description
q	string	✅	Pattern phrase to resolve.
limit	integer	—	Max candidates. Default 8.

GET /v1/financials/find-pattern?q=three+consecutive+years+of+growth

---

POST /v1/financials/find-pattern

Batch pattern resolver. Same structure as POST /v1/financials/find but resolves pattern phrases (shape axis).

{
  "queries": ["consecutive growth", "margin expanding", "turning profitable"],
  "limit": 5
}

---

GET /v1/financials/screen

Multi-condition financial screener. Takes a JSON array of {concept, pattern, ...params} conditions and returns matching stocks.

Parameter	Type	Required	Description
conditions	string	✅	URL-encoded JSON array of condition objects.
filters	string	—	URL-encoded JSON object: {market_cap_min, market_cap_max, sector}.
sort_by	string	—	A metric key to rank results.
sort_dir	string	—	asc or desc.
limit	integer	—	Max results. Default 50.

Condition object shape

[
  { "concept": "gross_margin",  "pattern": "above",              "threshold": 0.40 },
  { "concept": "revenue",       "pattern": "consecutive_growth", "N": 3 },
  { "concept": "net_debt",      "pattern": "is_negative" }
]

Each condition requires:

• concept — a canonical field key (from find or the Field Catalog)
• pattern — the comparison type (above, below, is_positive, is_negative, consecutive_growth, compound_growth, etc.)
• Additional params as needed (threshold, N, min, max)

See the Fundamental Leg docs for the full pattern reference.

:::tip Better via the unified screener For multi-leg screens (TA + fundamentals + options), use POST /v1/screen — it composes all legs with universe filtering and sorting. This endpoint is useful for standalone programmatic queries. :::