/api/v1/financials/metrics

Get standardized financial metrics for a company over time.

Why use this

Retrieve income statement, balance sheet, and cash flow data in quarterly or annual series.

Common use case

Building financial data tables, charting revenue/earnings trends, comparing financial performance across periods.

Standardized financial metrics from SEC EDGAR XBRL filings (~7,000 covered tickers). Returns income statement, balance sheet, and cash flow line items as quarterly OR annual time series. Each metric explicitly maps to its underlying us-gaap concept (e.g. revenue ↔ us-gaap:Revenues, net_income ↔ us-gaap:NetIncomeLoss) and tags the temporal basis (DURATION = period-total like revenue/net_income; INSTANT = point-in-time like total_assets/total_equity). Use GET /api/v1/financials/ratios for the 29 derived ratios computed from these primitives, GET /api/v1/financials/snapshot for a single-call TTM summary, GET /api/v1/facts/by-concept for the raw concept-level facts that feed this surface, and GET /api/v1/financials/tickers to gate which tickers have XBRL coverage.

Parameters

Name	In	Required	Default	Allowed	Description	Example
ticker	query	required	—	—	Stock ticker symbol (e.g., AAPL). Canonical hyphen form (`BRK-A`); server normalizes `BRK.A`/`BRK/A`/`BRKA` → `BRK-A`. Returns 404 if no XBRL coverage — gate via `/api/v1/financials/tickers` for the ~7,000-ticker covered universe.	AAPL
period	query	optional	Q	—	Period type: `Q` (quarterly) returns one row per fiscal quarter; `Y` (annual) returns one row per fiscal year (10-K-anchored, fiscal-year-end-aware so non-calendar issuers like AAPL/September-end and ORCL/May-end report against their actual fiscal year boundaries — NOT calendar).	Q
years	query	optional	5	—	Number of years of history (1-20). Quarterly returns up to `years × 4` rows; annual up to `years` rows. FinRadar's XBRL ETL coverage starts ~2013 for most issuers, ~2009 for large-caps that filed early-XBRL voluntarily.	5

Response schema

Field	Type	Nullable	Description
data.company	string	no	Company name as registered with SEC (typically Title Case from EDGAR's company-tickers.json — NOT the all-caps EDGAR-doc-header convention). Use for human-readable financial-table headers.
data.ticker	string	no	Issuer ticker echoed back in canonical hyphen form. Useful for asserting your client passed the ticker you intended after server-side normalization.
data.period_type	string	no	Echoed back: `Q` (quarterly) or `Y` (annual). Quarterly rows are 10-Q derived (with the fiscal-Q4 row backfilled from the 10-K minus first three quarters); annual rows are 10-K derived directly.
data.data[]	array	no	Array of period rows, sorted by `period_end DESC` (most recent first). Empty array on tickers without parsed XBRL data — gate via `/api/v1/financials/tickers` first if you're not sure of coverage.
data.data[].period_end	string	no	ISO `YYYY-MM-DD` fiscal-period-end date. NOT calendar-quarter-aligned for non-calendar issuers — AAPL Q4 2025 ends `2025-09-27` (final Saturday of Sep 2025), not 2025-09-30. Use this field for chart x-axes and time-series joins.
data.data[].revenue	number	yes	Revenue (USD). Concept: `us-gaap:Revenues` or `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` (post-ASC 606). DURATION fact (sum across the fiscal period). For TTM, sum the last 4 quarterly rows. Null when issuer hasn't filed for the period yet (most-recent quarter during 45-day filing window) or when revenue concept isn't tagged in the source XBRL.
data.data[].cost_of_revenue	number	yes	Cost of revenue / cost of goods sold (USD). Concept: `us-gaap:CostOfRevenue` or `us-gaap:CostOfGoodsAndServicesSold`. DURATION fact. Null for non-COGS business models (banks, insurers, asset managers — interpret null as 'not applicable to this issuer's structure', not 'missing data').
data.data[].gross_profit	number	yes	Gross profit (USD). Concept: `us-gaap:GrossProfit`. DURATION fact. Computed as `revenue - cost_of_revenue` when both are available. Null when either input is null. Combine with `revenue` for gross-margin calculation.
data.data[].operating_income	number	yes	Operating income / EBIT (USD). Concept: `us-gaap:OperatingIncomeLoss`. DURATION fact. Negative for operating-loss companies (tech-growth, biotech). Null when issuer doesn't tag the concept (uncommon).
data.data[].net_income	number	yes	Net income attributable to common stockholders (USD). Concept: `us-gaap:NetIncomeLoss`. DURATION fact. Negative for loss-makers. For TTM, sum the last 4 quarterly rows.
data.data[].eps_basic	number	yes	Basic earnings per share (USD per share). Concept: `us-gaap:EarningsPerShareBasic`. DURATION fact. Negative for loss-makers. NOT split-adjusted server-side — corresponds to as-filed share count for the period; for split-adjusted historical EPS use `/api/v1/tickers/{ticker}/overview`.
data.data[].eps_diluted	number	yes	Diluted earnings per share (USD per share). Concept: `us-gaap:EarningsPerShareDiluted`. DURATION fact. Includes dilutive effect of options, RSUs, convertibles. NOT split-adjusted server-side.
data.data[].shares_outstanding	number	yes	Weighted-average diluted shares outstanding for the period (NOT a point-in-time count). Concept: `us-gaap:WeightedAverageNumberOfDilutedSharesOutstanding`. Use for back-computing market cap × period-EPS rather than for current shares-outstanding. NOT split-adjusted.
data.data[].total_assets	number	yes	Total assets (USD). Concept: `us-gaap:Assets`. INSTANT fact — point-in-time at `period_end`. For balance-sheet ratios use this directly; for averaged denominators (e.g. ROA) average current and prior period.
data.data[].total_equity	number	yes	Total stockholders' equity (USD). Concept: `us-gaap:StockholdersEquity`. INSTANT fact — point-in-time at `period_end`. Negative for issuers with accumulated deficit > paid-in capital (common in early-stage tech/biotech and aggressive-buyback names like MMM, MCD, SBUX). Null when issuer doesn't tag the concept.
data.data[].total_debt	number	yes	Total debt (short-term + long-term) (USD). Computed sum across `us-gaap:LongTermDebt` + `us-gaap:ShortTermBorrowings` + `us-gaap:CommercialPaper` etc. INSTANT fact at `period_end`. For debt-to-equity/coverage ratios use this directly.
data.data[].cash_and_equivalents	number	yes	Cash and cash equivalents (USD). Concept: `us-gaap:CashAndCashEquivalentsAtCarryingValue`. INSTANT fact at `period_end`. Excludes marketable securities; for total-liquidity use `cash_and_short_term_investments` if surfaced. Combine with `total_debt` for net-debt computation.
data.data[].operating_cash_flow	number	yes	Cash flow from operations (USD). Concept: `us-gaap:NetCashProvidedByUsedInOperatingActivities`. DURATION fact (period total). For TTM, sum last 4 quarters. Negative for cash-burning growth companies.
data.data[].capex	number	yes	Capital expenditures (USD, NEGATIVE convention — cash outflow). Concept: `us-gaap:PaymentsToAcquirePropertyPlantAndEquipment`. DURATION fact. Reported as negative (cash outflow); use absolute value for capex-to-revenue ratios.
data.data[].free_cash_flow	number	yes	Free cash flow (USD). Computed as `operating_cash_flow + capex` (capex is negative, so this subtracts capex magnitude). DURATION fact (period total). The canonical Buffett-style cash-quality metric. Negative for FCF-burning growth companies (recent IPOs, hyper-growth tech).

Sample response

"status": "success"
"data":
- "company": "Apple Inc."
- "ticker": "AAPL"
- "period_type": "Q"
- "data":
- "note": "Use /ratios endpoint for calculated financial ratios"
}

}

Errors

Status	Label	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query, body, or path parameter.
401	Unauthorized	Missing or invalid Authorization header / api_Token.
402	Payment Required	Insufficient token balance for this call. Top up
429	Too Many Requests	Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500	Server Error	Unexpected server-side failure. Retry with backoff; report if persistent.

Code samples

Reveal credentials

curl "https://api.finradar.ai/api/v1/financials/metrics?api_Token=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).