# Company Financials (XBRL) — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 79b7dbdf
> Fetch this file at: https://uat.finradarapi.com/llms/company-financials-xbrl.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Company Financials (XBRL)

Standardized financial data from SEC EDGAR XBRL filings. Covers ~7,000+ publicly traded companies with quarterly/annual income statement, balance sheet, cash flow metrics, and 29 derived financial ratios. Data sourced from SEC companyfacts bulk download, updated daily.

### GET /api/v1/financials/metrics

Get standardized financial metrics for a company over time.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): 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): 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): 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): 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): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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 (nullable)): 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).

**Since:** v3.4.0

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

**Use case:** Building financial data tables, charting revenue/earnings trends, comparing financial performance across periods.

**Parameters:**
- `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.
- `period` (query, optional, default: 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).
- `years` (query, optional, default: 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.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "period_type": "Q",
    "data": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "revenue": 94930000000,
        "cost_of_revenue": 51260000000,
        "gross_profit": 43670000000,
        "operating_income": 29610000000,
        "net_income": 24470000000,
        "eps_basic": 1.65,
        "eps_diluted": 1.64,
        "shares_outstanding": 14840000000,
        "total_assets": 364980000000,
        "total_equity": 56950000000,
        "total_debt": 101700000000,
        "cash_and_equivalents": 28160000000,
        "operating_cash_flow": 26810000000,
        "capex": -3130000000,
        "free_cash_flow": 23680000000
      }
    ],
    "note": "Use /ratios endpoint for calculated financial ratios"
  }
}
```

### GET /api/v1/financials/ratios

Get derived financial ratios (margins, returns, growth, leverage) over time.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.period_type` (string): Echoed back: `Q`, `Y`, or `TTM`. TTM rows are computed by summing the most-recent 4 quarterly DURATION facts (revenue, net_income, OCF, capex) and using the latest INSTANT fact for balance-sheet denominators.
- `data.category` (string): Echoed-back filter: `profitability` / `leverage` / `liquidity` / `efficiency` / `per_share` / `runway` / `growth` / `all`. When `all` is selected, every ratio in the response carries the same shape regardless of category.
- `data.data[]` (array): Array of period rows, sorted by `period_end DESC` (most recent first). Empty array on tickers without parsed XBRL data.
- `data.data[].period_end` (string): ISO `YYYY-MM-DD` fiscal-period-end date. NOT calendar-aligned for non-calendar fiscal years.
- `data.data[].gross_margin` (number (nullable)): Gross margin (UNIT: ratio, decimal — `0.473` = 47.3%). Computed as `gross_profit / revenue`. Null when either input is null. Profitability category.
- `data.data[].operating_margin` (number (nullable)): Operating margin (decimal). `operating_income / revenue`. Negative for operating-loss companies. Profitability category.
- `data.data[].net_margin` (number (nullable)): Net margin (decimal). `net_income / revenue`. Negative for loss-makers. Profitability category.
- `data.data[].roe` (number (nullable)): Return on Equity (decimal). For TTM uses AVERAGED denominator: `ttm_net_income / avg_book_equity` (per the v3.7.2 DO-parity fix — non-averaged denominators inflate ROE on rapidly-changing equity). Null when book equity is negative or one of the inputs is missing. Profitability category.
- `data.data[].roa` (number (nullable)): Return on Assets (decimal). `ttm_net_income / avg_total_assets` (averaged denominator for TTM). Profitability category.
- `data.data[].roic` (number (nullable)): Return on Invested Capital (decimal). v3.5.0 DO-parity formula: `ttm_nopat / (avg_equity + avg_total_debt - avg_cash)` where `nopat = ebit × (1 - 0.25 fixed tax)`. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15. Profitability category.
- `data.data[].debt_to_equity` (number (nullable)): Total debt / book equity (ratio). INSTANT-on-INSTANT (point-in-time at period_end). Null when equity is zero or negative. Below 0.5 = conservative; above 2.0 = leveraged. Leverage category.
- `data.data[].current_ratio` (number (nullable)): Current assets / current liabilities (ratio). Liquidity category. Below 1.0 indicates short-term-funding gap (note: AAPL routinely runs <1.0 with no liquidity issue — interpret in context). Liquidity category.
- `data.data[].quick_ratio` (number (nullable)): (Current assets - inventory) / current liabilities (ratio). Strict-liquidity test excluding inventory. Liquidity category.
- `data.data[].eps_diluted_ttm` (number (nullable)): Trailing-twelve-month diluted EPS (USD per share). Sum of last 4 quarterly `eps_diluted` values. NOT split-adjusted server-side — for split-adjusted EPS history use `/api/v1/tickers/{ticker}/overview`. Per-share category.
- `data.data[].book_value_per_share` (number (nullable)): Book value per share (USD). `total_equity / shares_outstanding`. Negative for issuers with negative book equity. Per-share category.
- `data.data[].free_cash_flow_per_share` (number (nullable)): TTM Free Cash Flow per share (USD). `ttm_free_cash_flow / shares_outstanding`. Negative for FCF-burning companies. Per-share category.
- `data.data[].revenue_growth_yoy` (number (nullable)): Year-over-year revenue growth (decimal — `0.061` = 6.1% growth). Computed as `(period_revenue / prior_year_same_period_revenue) - 1`. Null on the first year of coverage (no prior baseline). Growth category.
- `data.data[].eps_growth_yoy` (number (nullable)): Year-over-year diluted EPS growth (decimal). Same formula shape as revenue_growth_yoy. Negative when EPS shrank YoY. Null when prior-year EPS is zero/negative (division undefined). Growth category.
- `data.data[].cash_runway_status` (string (nullable)): Tiered cash-runway label (added v3.6.0). Values: `cash_generating` (FCF-positive, no runway concept), `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens. Runway category.

**Since:** v3.4.0

**Utility:** Retrieve calculated financial ratios separated from raw metrics.

**Use case:** Trend analysis of profitability, leverage, liquidity, and growth metrics. Filter by ratio category.

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 on tickers without XBRL coverage; gate via `/api/v1/financials/tickers`.
- `period` (query, optional, default: Q): Period type: `Q` (quarterly point-in-time ratios), `Y` (annual), or `TTM` (trailing-twelve-month rolling — most useful for cross-issuer comparison since it smooths quarterly seasonality). For most fundamental-screener UIs, default to `TTM`.
- `years` (query, optional, default: 5): Years of history (1-20). With `period=Q` returns up to `years × 4` rows; with `period=Y` or `period=TTM` returns up to `years` rows. TTM rolls the 4-quarter window forward by one quarter per row.
- `category` (query, optional, default: all): Filter to one ratio category: `profitability` (margins + ROE/ROA/ROIC), `leverage` (debt-to-equity, interest coverage), `liquidity` (current/quick ratios), `efficiency` (asset/inventory turnover), `per_share` (EPS, BVPS, FCFPS), `runway` (cash-runway-status tier), `growth` (YoY/QoQ revenue + EPS), or `all` (everything). Use `category=profitability` for margin-trend charts; `category=leverage` for credit-risk dashboards.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "period_type": "TTM",
    "category": "all",
    "data": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "gross_margin": 0.473,
        "operating_margin": 0.319,
        "net_margin": 0.27,
        "roe": 1.455,
        "roa": 0.323,
        "roic": 0.498,
        "debt_to_equity": 1.785,
        "current_ratio": 0.974,
        "quick_ratio": 0.825,
        "eps_diluted_ttm": 7.14,
        "book_value_per_share": 3.84,
        "free_cash_flow_per_share": 6.62,
        "revenue_growth_yoy": 0.061,
        "eps_growth_yoy": 0.103,
        "cash_runway_status": "cash_generating"
      }
    ]
  }
}
```

### GET /api/v1/financials/snapshot

Get snapshot with all metrics and ratios grouped by category. Supports TTM (default) or latest quarter.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`). Useful as join key against the SEC ownership endpoints (13D/G/F surface) and Insider Form 4 transactions.
- `data.period` (string): Echoed back: `TTM` or `Q`.
- `data.period_end` (string): ISO `YYYY-MM-DD` fiscal-period-end date for the most-recent fiscal quarter (the right boundary of the TTM window when `period=TTM`). Non-calendar fiscal-year-end-aware.
- `data.sector` (string (nullable)): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when ticker is unmapped in Sharadar (private CUSIPs, recent IPOs, foreign issuers without ADRs).
- `data.industry` (string (nullable)): Sharadar industry classification (more specific than sector). Null when unmapped. Em-dash characters preserved verbatim from Sharadar.
- `data.cash_runway_status` (string (nullable)): Tiered cash-runway label. Values: `cash_generating` (FCF-positive — no runway concept), `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Surfaced at top-level for company-overview-card prominence.
- `data.metrics` (object): Income-statement + balance-sheet + cash-flow primitives — TTM totals (sum of last 4 quarterly DURATION facts) for income/cash-flow items; INSTANT (point-in-time at `period_end`) for balance-sheet items. Includes: `revenue`, `net_income`, `operating_income`, `free_cash_flow`, `total_assets`, `total_equity`, `total_debt`, `cash_and_equivalents`, `shares_outstanding`. All USD. See [/financials/metrics](/docs/company-data/company-financials-xbrl/get-financials-metrics) for full per-period time series.
- `data.ratios` (object): Derived ratios grouped by category. Sub-objects: `profitability` (gross/operating/net margins + ROE/ROA/ROIC), `leverage` (debt-to-equity, debt-to-assets, interest_coverage), `liquidity` (current/quick ratios), `per_share` (eps_diluted_ttm, book_value_per_share, free_cash_flow_per_share), `growth` (revenue_growth_yoy, eps_growth_yoy). All ratios are decimals (`0.473` = 47.3%). Per-share metrics are USD/share. NOT split-adjusted server-side.
- `data.ratios.profitability` (object): Profitability sub-object: `gross_margin`, `operating_margin`, `net_margin` (each = matching DURATION-on-DURATION ratio), `roe`, `roa`, `roic` (each computed with AVERAGED balance-sheet denominators per v3.7.2 DO-parity fix). Decimal values.
- `data.ratios.leverage` (object): Leverage sub-object: `debt_to_equity`, `debt_to_assets` (both INSTANT-on-INSTANT at `period_end`), `interest_coverage` (TTM EBIT / TTM interest expense — null when interest expense is zero). Decimals.
- `data.ratios.liquidity` (object): Liquidity sub-object: `current_ratio` (current assets / current liabilities), `quick_ratio` ((current assets - inventory) / current liabilities). Both INSTANT-on-INSTANT. AAPL routinely runs current_ratio < 1.0 with no liquidity issue — interpret in context (mature large-caps with negative working-capital cycles can run sub-1.0 indefinitely).
- `data.ratios.per_share` (object): Per-share sub-object (USD/share): `eps_diluted_ttm` (sum of last 4 quarters' diluted EPS), `book_value_per_share` (total_equity / shares_outstanding), `free_cash_flow_per_share` (TTM FCF / shares_outstanding). NOT split-adjusted server-side — for split-adjusted historical view use [/api/v1/tickers/{ticker}/overview](/docs/company-data/ticker-research/get-tickers-ticker-overview).
- `data.ratios.growth` (object): Growth sub-object (decimals): `revenue_growth_yoy` (YoY revenue growth = `(current_period_rev / prior_year_same_period_rev) - 1`), `eps_growth_yoy` (same shape on diluted EPS). Null when prior-year baseline is zero/negative (division undefined).

**Since:** v3.4.0

**Utility:** Single-call summary of a company's current financial position.

**Use case:** Company overview cards, financial health dashboards, screening criteria.

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 on tickers without XBRL coverage; gate via `/api/v1/financials/tickers`.
- `period` (query, optional, default: TTM): Period basis: `TTM` (trailing-twelve-month rolling — default; smooths quarterly seasonality, comparable across issuers) or `Q` (latest quarterly point-in-time — useful when you specifically want the most-recent fiscal quarter's results, not a smoothed view). For company-overview cards default to `TTM`; for earnings-watch dashboards use `Q`.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "company": "Apple Inc.",
    "ticker": "AAPL",
    "cik": "0000320193",
    "period": "TTM",
    "period_end": "2025-09-27",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "cash_runway_status": "cash_generating",
    "metrics": {
      "revenue": 401450000000,
      "net_income": 105320000000,
      "operating_income": 128190000000,
      "free_cash_flow": 105820000000,
      "total_assets": 364980000000,
      "total_equity": 56950000000,
      "total_debt": 101700000000,
      "cash_and_equivalents": 28160000000,
      "shares_outstanding": 14840000000
    },
    "ratios": {
      "profitability": {
        "gross_margin": 0.473,
        "operating_margin": 0.319,
        "net_margin": 0.27,
        "roe": 1.455,
        "roa": 0.323,
        "roic": 0.498
      },
      "leverage": {
        "debt_to_equity": 1.785,
        "debt_to_assets": 0.279,
        "interest_coverage": 28.4
      },
      "liquidity": {
        "current_ratio": 0.974,
        "quick_ratio": 0.825
      },
      "per_share": {
        "eps_diluted_ttm": 7.1,
        "book_value_per_share": 3.84,
        "free_cash_flow_per_share": 7.13
      },
      "growth": {
        "revenue_growth_yoy": 0.061,
        "eps_growth_yoy": 0.103
      }
    }
  }
}
```

### GET /api/v1/financials/tickers

Search or list companies with financial data available.

**Token cost:** 10 tokens per call

**Response fields:**
- `tickers` (array): Array of matching tickers, sorted by `fact_count DESC` (data-richest tickers first) when `q` is empty, OR by exact-match relevance + `fact_count DESC` when `q` is provided. Empty array on no match.
- `tickers[].ticker` (string): Canonical ticker (hyphen form). Use as input to `/financials/metrics`, `/financials/snapshot`, `/financials/ratios` etc. Multi-class issuers preserve the requested class.
- `tickers[].cik` (string): Issuer CIK in 10-char zero-padded form. Useful as join key against the SEC ownership endpoints (13D/G/F surface).
- `tickers[].company_name` (string): Company name from EDGAR's company-tickers.json file (typically Title Case — NOT all-caps EDGAR convention because this comes from the SEC's curated list). Use for human-readable autocomplete labels.
- `tickers[].latest_period_end` (string (nullable)): ISO `YYYY-MM-DD` end-date of the most-recent fiscal period for which we have parsed XBRL facts. Null only for tickers that have CIK but no XBRL data yet (rare; mostly very recent IPOs). Use to detect filing-staleness — values older than ~6 months on an active filer indicate either delayed XBRL parsing or an actual 10-K/10-Q skip.
- `tickers[].fact_count` (integer): Total parsed XBRL facts across all quarters for this ticker. Mature large-caps: 8000-20000 (multi-decade history × 1500 facts per filing). Small-caps: 500-3000. Recent IPOs: 100-500. Use as a data-richness gauge.
- `tickers[].sector` (string (nullable)): Sharadar sector classification (e.g. `Technology`, `Healthcare`, `Financial Services`). Null when the ticker is unmapped in Sharadar (private CUSIPs, recently-listed issuers, foreign issuers without ADRs). Useful for sector-filtered autocomplete.
- `tickers[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Null when unmapped. Em-dash characters preserved verbatim from Sharadar.
- `meta` (object): Result metadata block: `{ total: integer, limit: integer }`. `total` reflects full-corpus match count for the search; `limit` is the effective server-side-capped limit.

**Since:** v3.4.0

**Utility:** Discovery + autocomplete endpoint for the XBRL company-financials universe — lists tickers for which FinRadar has parsed and standardized at least one quarter of SEC company-facts data (~7,000+ companies, sourced from EDGAR's XBRL companyfacts daily bulk download). Use as the gating layer for financial-screener UIs: query this first to know which tickers can be queried via `/financials/metrics`, `/financials/snapshot`, `/financials/ratios`. Returns the latest available period plus total parsed fact count per ticker — useful for surfacing data-completeness signals (a ticker with only 200 facts is a recent-IPO with thin history; one with 12,000+ has a full multi-decade book). Sharadar sector/industry classifications are joined-in to support sector-specific autocomplete filters.

**Use case:** Building ticker search/autocomplete UI for the financials page.

**Parameters:**
- `q` (query, optional): Free-text search across (1) ticker (exact match boost) and (2) company name (partial match `ILIKE '%name%'`). Case-insensitive. Empty `q` returns the full list ordered by `fact_count DESC` (most-data-rich tickers first) — useful for default-state autocomplete dropdowns.
- `limit` (query, optional, default: 50): Maximum tickers returned (capped at 200 server-side). For typical autocomplete dropdowns, 10-20 is enough; for full-list preload (all 7000 tickers for offline indexing) use 200 + paginated walks.

**Sample response:**
```json
{
  "tickers": [
    {
      "ticker": "AAPL",
      "cik": "0000320193",
      "company_name": "APPLE INC",
      "latest_period_end": "2025-09-28",
      "fact_count": 12480,
      "sector": "Technology",
      "industry": "Consumer Electronics"
    }
  ],
  "meta": {
    "total": 7000,
    "limit": 100
  }
}
```

### GET /api/v1/financials/changes

Get recently updated companies (filing changes detected).

**Token cost:** 5 tokens per call

**Response fields:**
- `data.since` (string): ISO-8601 UTC timestamp echoed back — the lower-bound used for the query (defaults to 7 days ago when not specified).
- `data.count` (integer): Total number of tickers updated since `since`. May exceed `limit` (response is capped at `limit` rows; `count` reflects the full match set).
- `data.tickers[]` (array): Array of changed-ticker rows, sorted by `last_updated_at DESC` (most-recently-updated first). Empty array when no XBRL data has been loaded since `since`.
- `data.tickers[].ticker` (string): Issuer ticker (canonical hyphen form). Pass to `/api/v1/financials/changes/{ticker}` for per-ticker change details (which periods + which metrics).
- `data.tickers[].cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`).
- `data.tickers[].company_name` (string): Company name from EDGAR's company-tickers.json.
- `data.tickers[].last_updated_at` (string): ISO-8601 UTC timestamp of when FinRadar's XBRL ETL last loaded data for this ticker (NOT the SEC filing time — that's earlier; the gap reflects the daily company-facts ETL cadence + Phase 49+ standardization step). Use as the `since` cursor for incremental polling.
- `data.tickers[].periods_updated` (array): Array of fiscal periods (`YYYYQq` format like `2025Q4` for quarterly, `2024Y` for annual) that received new or updated metrics in this load. Most loads update one period (the freshly-filed quarter); restatements update multiple historical periods.
- `data.tickers[].metrics_count` (integer): Total count of standardized metrics affected across `periods_updated`. Typical 10-Q load: 30-40 metrics; 10-K load: 40-60; restatement: variable.
- `data.tickers[].trigger` (string (nullable)): Human-readable cause of the update. Values: `10-Q filing`, `10-K filing`, `8-K/A restatement`, `XBRL re-parse`, `Backfill load`. Null when the trigger isn't classifiable (rare).
- `data.tickers[].latest_period_end` (string): ISO `YYYY-MM-DD` end-date of the most-recent fiscal period now available for this ticker. Useful for staleness detection (compare against today's date).

**Since:** v3.4.0

**Utility:** Track which companies had new XBRL data loaded.

**Use case:** Delta feeds for downstream consumers, monitoring data freshness.

**Parameters:**
- `since` (query, optional, default: 7d-ago): ISO-8601 UTC timestamp lower-bound on `last_updated_at`. Default = 7 days ago. Pass the most-recent `last_updated_at` from your last poll to receive only newly-updated tickers (incremental delta-feed pattern).
- `limit` (query, optional, default: 50): Maximum tickers returned (capped at 200 server-side). For typical delta-feed cadence (every 6-24 hours) 50-100 is plenty; for rare large-batch backfill catch-ups use 200 + paginated walks.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "since": "2026-04-25T00:00:00Z",
    "count": 48,
    "tickers": [
      {
        "ticker": "AAPL",
        "cik": "0000320193",
        "company_name": "APPLE INC",
        "last_updated_at": "2026-04-30T01:42:13Z",
        "periods_updated": [
          "2025Q4"
        ],
        "metrics_count": 36,
        "trigger": "10-Q filing",
        "latest_period_end": "2025-09-27"
      },
      {
        "ticker": "MSFT",
        "cik": "0000789019",
        "company_name": "MICROSOFT CORP",
        "last_updated_at": "2026-04-29T08:14:50Z",
        "periods_updated": [
          "2026Q1"
        ],
        "metrics_count": 38,
        "trigger": "10-Q filing",
        "latest_period_end": "2025-12-31"
      }
    ]
  }
}
```

### GET /api/v1/financials/screen

Screen stocks by financial ratio criteria. Supports greater-than and less-than filters on 20+ financial metrics.

**Token cost:** 10 tokens per call

**Response fields:**
- `rows` (array): Array of screen-result rows — each ticker that satisfies ALL filters (AND-combined). Sorted by ticker alphabetically by default; pass `sort_by` parameter to sort by ratio (e.g. `sort_by=roe&sort_order=desc` for ROE-ranked output). Empty array on overly-narrow filter combinations.
- `rows[].ticker` (string): Issuer ticker (canonical hyphen form). Pass to `/financials/snapshot` or `/financials/metrics` for per-ticker drill-downs.
- `rows[].company_name` (string): Company name from EDGAR's company-tickers.json (typically Title Case). Use for human-readable labels in screener UIs.
- `rows[].pe_ratio` (number (nullable)): TTM (trailing 12 months) Price / Earnings ratio. Computed as `current_price / ttm_eps_diluted`. Null when EPS is negative (earnings-loss companies) — interpret null as 'P/E undefined for loss-makers'. Use `pe_lt=20` to filter to value names; combine with `pe_gt=0` to exclude loss-makers.
- `rows[].pb_ratio` (number (nullable)): TTM Price / Book ratio. Computed as `current_price / book_value_per_share`. Null when book value is negative (rare; some heavily-distressed companies). `pb_lt=1` is the classic deep-value Graham filter; `pb_gt=10` typical for high-quality compounders.
- `rows[].roe` (number (nullable)): TTM Return on Equity, computed using AVERAGED denominator (`ttm_net_income / avg_book_equity`) per the v3.7.2 DO-parity fix. Decimal value (`0.15` = 15%). Null when book equity is negative or when one of the inputs is missing. ROE > 0.20 indicates high-quality compounder territory.
- `rows[].roic` (number (nullable)): TTM Return on Invested Capital using the v3.5.0 DO-formula (`ttm_nopat / (avg_equity + avg_total_debt - avg_cash)`, with NOPAT = EBIT × (1 - 0.25 fixed tax)). Decimal value. The classic compounder-quality metric — Buffett-style screens use ROIC > 0.15.
- `rows[].ebitda_margin` (number (nullable)): TTM EBITDA / TTM Revenue. Decimal value (`0.30` = 30% margin). Null when revenue is zero or near-zero (rare). Useful for capital-intensity / scale-quality screens — software companies typically 25-40%; commodity producers 10-20%.
- `rows[].debt_to_equity` (number (nullable)): Total debt (short + long) / book equity, point-in-time at the latest fiscal-period end. Null when book equity is negative or zero. Below 0.5 indicates conservative balance sheet; above 2.0 indicates leveraged. Banks and insurers are excluded from typical screens (their structural leverage skews comparison).
- `rows[].cash_runway_status` (string (nullable)): Tiered cash-runway label (added v3.6.0): `healthy` (>24 months runway at current burn), `moderate` (12-24 months), `caution` (6-12 months), `critical` (<6 months). Null for profitable companies (no runway concept). Useful for filtering distressed-equity candidates and biotech/clinical-stage screens.
- `rows[].sector` (string (nullable)): Sharadar sector classification. Null when ticker is unmapped in Sharadar. Pre-filter screens with `sector` parameter to avoid sector-bias in cross-industry-incomparable ratios (e.g. ROE comparisons across Banks vs Tech).
- `rows[].industry` (string (nullable)): Sharadar industry classification (more specific than `sector`). Em-dash characters preserved verbatim from Sharadar.
- `meta` (object): Result metadata: `{ total: integer, applied_filters: array<string>, ... }`. `applied_filters` echoes the parsed `_gt`/`_lt` filters as human-readable strings (e.g. `["roe > 0.15", "debt_to_equity < 1.0"]`) — useful for dashboards rendering 'currently filtered by:' breadcrumbs.

**Since:** v3.5.0

**Utility:** The XBRL-driven stock screener — filter the ~7,000-company financials universe by 20+ derived ratio criteria (profitability, leverage, liquidity, efficiency, growth) using composable greater-than / less-than filters. Built on the same standardized XBRL ratio engine as `/financials/ratios` so the math is consistent across endpoints. Each result row carries the full ratio block (P/E, P/B, ROE, ROIC, EBITDA margin, debt-to-equity, cash-runway-status, sector/industry) so dashboards can render results without follow-up per-ticker calls. The right entry point for fundamental-screener UIs and quant pre-screens (e.g. 'find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin'). For per-ticker drill-downs use `/financials/metrics` (line items) or `/financials/snapshot` (TTM summary).

**Use case:** Stock screener: find all companies with ROE > 15%, debt-to-equity < 1, and positive FCF margin. Chain with /snapshot for details.

**Parameters:**
- `gross_margin_gt` (query, optional): Keep only companies whose gross margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `gross_margin_lt` (query, optional): Keep only companies whose gross margin is less than this value (decimal, e.g. 0.15 = 15%).
- `operating_margin_gt` (query, optional): Keep only companies whose operating margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `operating_margin_lt` (query, optional): Keep only companies whose operating margin is less than this value (decimal, e.g. 0.15 = 15%).
- `net_margin_gt` (query, optional): Keep only companies whose net margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `net_margin_lt` (query, optional): Keep only companies whose net margin is less than this value (decimal, e.g. 0.15 = 15%).
- `fcf_margin_gt` (query, optional): Keep only companies whose free-cash-flow margin is greater than this value (decimal, e.g. 0.15 = 15%).
- `fcf_margin_lt` (query, optional): Keep only companies whose free-cash-flow margin is less than this value (decimal, e.g. 0.15 = 15%).
- `roe_gt` (query, optional): Keep only companies whose ROE is greater than this value (decimal, e.g. 0.15 = 15%).
- `roe_lt` (query, optional): Keep only companies whose ROE is less than this value (decimal, e.g. 0.15 = 15%).
- `roa_gt` (query, optional): Keep only companies whose ROA is greater than this value (decimal, e.g. 0.15 = 15%).
- `roa_lt` (query, optional): Keep only companies whose ROA is less than this value (decimal, e.g. 0.15 = 15%).
- `roic_gt` (query, optional): Keep only companies whose ROIC is greater than this value (decimal, e.g. 0.15 = 15%).
- `roic_lt` (query, optional): Keep only companies whose ROIC is less than this value (decimal, e.g. 0.15 = 15%).
- `debt_to_equity_gt` (query, optional): Keep only companies whose debt-to-equity ratio is greater than this value (ratio).
- `debt_to_equity_lt` (query, optional): Keep only companies whose debt-to-equity ratio is less than this value (ratio).
- `debt_to_assets_gt` (query, optional): Keep only companies whose debt-to-assets ratio is greater than this value (ratio).
- `debt_to_assets_lt` (query, optional): Keep only companies whose debt-to-assets ratio is less than this value (ratio).
- `current_ratio_gt` (query, optional): Keep only companies whose current ratio is greater than this value (ratio).
- `current_ratio_lt` (query, optional): Keep only companies whose current ratio is less than this value (ratio).
- `quick_ratio_gt` (query, optional): Keep only companies whose quick ratio is greater than this value (ratio).
- `quick_ratio_lt` (query, optional): Keep only companies whose quick ratio is less than this value (ratio).
- `asset_turnover_gt` (query, optional): Keep only companies whose asset turnover is greater than this value (ratio).
- `asset_turnover_lt` (query, optional): Keep only companies whose asset turnover is less than this value (ratio).
- `interest_coverage_gt` (query, optional): Keep only companies whose interest coverage is greater than this value (ratio).
- `interest_coverage_lt` (query, optional): Keep only companies whose interest coverage is less than this value (ratio).
- `inventory_turnover_gt` (query, optional): Keep only companies whose inventory turnover is greater than this value (ratio).
- `inventory_turnover_lt` (query, optional): Keep only companies whose inventory turnover is less than this value (ratio).
- `receivables_turnover_gt` (query, optional): Keep only companies whose receivables turnover is greater than this value (ratio).
- `receivables_turnover_lt` (query, optional): Keep only companies whose receivables turnover is less than this value (ratio).
- `revenue_growth_yoy_gt` (query, optional): Keep only companies whose YoY revenue growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_yoy_lt` (query, optional): Keep only companies whose YoY revenue growth is less than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_yoy_gt` (query, optional): Keep only companies whose YoY EPS growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_yoy_lt` (query, optional): Keep only companies whose YoY EPS growth is less than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_qoq_gt` (query, optional): Keep only companies whose QoQ revenue growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `revenue_growth_qoq_lt` (query, optional): Keep only companies whose QoQ revenue growth is less than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_qoq_gt` (query, optional): Keep only companies whose QoQ EPS growth is greater than this value (decimal, e.g. 0.15 = 15%).
- `eps_growth_qoq_lt` (query, optional): Keep only companies whose QoQ EPS growth is less than this value (decimal, e.g. 0.15 = 15%).

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "filters": [
      "roe > 0.15",
      "debt_to_equity < 1.0"
    ],
    "count": 847,
    "results": [
      {
        "ticker": "AAPL",
        "company": "Apple Inc."
      },
      {
        "ticker": "MSFT",
        "company": "Microsoft Corp"
      }
    ]
  }
}
```

### GET /api/v1/financials/changes/{ticker}

Get details of what changed for a specific company in the last 7 days.

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Issuer ticker echoed back (canonical hyphen form).
- `data.company` (string): Company name (Title Case from EDGAR's company-tickers.json).
- `data.cik` (string): Issuer CIK in 10-char zero-padded form (e.g. `0000320193`).
- `data.since` (string): ISO-8601 UTC timestamp echoed back — the lower-bound used for the query.
- `data.periods_updated[]` (array): Array of period-update rows, sorted by `updated_at DESC`. Empty array when no updates within `since` window. Restatement events emit multiple rows (one per affected historical period); typical 10-Q/10-K loads emit one row.
- `data.periods_updated[].year` (integer): Fiscal year of the updated period (e.g. `2025`).
- `data.periods_updated[].period` (string): Fiscal period label: `Q1`/`Q2`/`Q3`/`Q4` for quarterly, `FY` for annual.
- `data.periods_updated[].period_end` (string): ISO `YYYY-MM-DD` end-date of the updated fiscal period. Non-calendar fiscal-year-end-aware.
- `data.periods_updated[].metrics_count` (integer): Total count of standardized metrics that were inserted or updated for this period in this load. Typical 10-Q: 30-40; 10-K: 40-60; restatement: variable.
- `data.periods_updated[].updated_at` (string): ISO-8601 UTC timestamp of when the ETL load completed for this period.
- `data.periods_updated[].trigger` (string (nullable)): Human-readable cause: `10-Q filing` / `10-K filing` / `8-K/A restatement` / `XBRL re-parse` / `Backfill load`. Null when uncertain.
- `data.metrics_affected` (array): Deduplicated list of standardized metric names (matches `/financials/metrics` response field names) that changed in any of the `periods_updated` rows. Use to selectively re-fetch only the affected metrics in your downstream sync.
- `data.ratios_affected` (array): Deduplicated list of derived ratio names (matches `/financials/ratios` response field names) that changed because their underlying metrics changed. Useful for cache-invalidation in ratio-driven UIs.

**Since:** v3.4.0

**Utility:** Drill into per-ticker filing changes.

**Use case:** After /changes shows a company was updated, use this to see which periods and metrics changed.

**Parameters:**
- `ticker` (path, required): Stock ticker symbol (canonical hyphen form). Returns 404 if ticker has no XBRL coverage; returns empty `periods_updated[]` if ticker exists but has no recent updates.
- `since` (query, optional, default: 7d-ago): ISO-8601 UTC timestamp lower-bound on `updated_at`. Default = 7 days ago. Pass a wider window to surface restatement events that backfill historical periods.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "ticker": "AAPL",
    "company": "Apple Inc.",
    "cik": "0000320193",
    "since": "2026-04-25T00:00:00Z",
    "periods_updated": [
      {
        "year": 2025,
        "period": "Q4",
        "period_end": "2025-09-27",
        "metrics_count": 36,
        "updated_at": "2026-04-30T01:42:13Z",
        "trigger": "10-Q filing"
      }
    ],
    "metrics_affected": [
      "revenue",
      "net_income",
      "eps_basic",
      "eps_diluted",
      "operating_income",
      "free_cash_flow",
      "total_assets",
      "total_equity"
    ],
    "ratios_affected": [
      "gross_margin",
      "operating_margin",
      "net_margin",
      "roe",
      "roa",
      "roic"
    ]
  }
}
```

### GET /api/v1/financials/status

System status for the XBRL pipeline: table row counts, last sync times, and pipeline health.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `data.database` (object): Row counts for each XBRL pipeline table. Useful for capacity-planning and ETL-completeness checks. Sub-fields: `cf_facts` (raw concept-level facts — typically 40-50M post-Phase-49), `cf_standardized_metrics` (Phase-49 standardized metrics — typically 2-3M), `cf_derived_metrics` (Phase-49 derived ratios — typically 1.5-2M), `cf_companies` (covered ticker count — typically 7000-7300), `cf_concepts` (unique us-gaap + dei concepts seen — typically 20K-25K).
- `data.database.cf_facts` (integer): Total raw concept-level facts in the system (e.g. one row per (cik, concept, period, value) tuple from EDGAR's companyfacts JSON). Grows ~50K rows/day during normal filing cadence.
- `data.database.cf_standardized_metrics` (integer): Total Phase-49-standardized metrics (e.g. `revenue` collapsing across `us-gaap:Revenues` + `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` + `us-gaap:SalesRevenueNet`). One row per (ticker, fiscal-period, metric-name).
- `data.database.cf_derived_metrics` (integer): Total derived ratios (e.g. ROE, debt-to-equity, gross_margin). One row per (ticker, fiscal-period, ratio-name). Computed nightly from `cf_standardized_metrics`.
- `data.database.cf_companies` (integer): Distinct ticker count with at least one parsed XBRL fact. Equals the result count of `/api/v1/financials/tickers` with empty `q`.
- `data.last_update` (string): ISO-8601 UTC timestamp of the most-recent ETL completion (any step). Compare against current time for staleness detection.
- `data.recent_syncs[]` (array): Recent ETL step executions, sorted by `time DESC`. Each row represents one daily-pipeline step run.
- `data.recent_syncs[].step` (string): Pipeline step name. Values: `companyfacts_download` (EDGAR bulk JSON download), `facts_load` (ingest into cf_facts), `standardized_metrics` (Phase-49 standardization pass), `derived_metrics` (Phase-49 ratio computation), `delta_detection` (changes-feed population).
- `data.recent_syncs[].time` (string): ISO-8601 UTC timestamp of step completion.
- `data.recent_syncs[].records` (integer): Records processed in this step run. For incremental loads this is the delta count; for full re-syncs (rare) this is the total table count.
- `data.recent_syncs[].duration_sec` (number): Step duration in seconds. Use as performance baseline (e.g. companyfacts_download typically 400-600 sec; standardized_metrics typically 150-200 sec). Spikes >2x baseline indicate degradation.
- `data.recent_syncs[].status` (string): Step outcome: `success` / `failed` / `partial` / `skipped`. Failed steps surface in `pipeline_health: degraded`.
- `data.pipeline_health` (string): Overall pipeline health summary. Values: `healthy` (last 4 step runs all succeeded, staleness < 24h), `degraded` (any failed step in last 24h OR staleness > 24h but < 48h), `critical` (staleness > 48h OR multiple consecutive failures). For status-page dashboards consume this directly; for deep diagnostics inspect `recent_syncs[]`.
- `data.staleness_hours` (number): Hours since `last_update` (rounded to 1 decimal). Useful for staleness-alert thresholds (e.g. alert if > 30h — XBRL pipeline runs daily ~01:00 UTC, so 24-30h is normal weekend/holiday cycle).

**Since:** v3.4.0

**Utility:** Monitor pipeline health and data freshness.

**Use case:** Admin dashboards, health checks, debugging data staleness issues.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "database": {
      "cf_facts": 45000000,
      "cf_standardized_metrics": 2800000,
      "cf_derived_metrics": 1900000,
      "cf_companies": 7200,
      "cf_concepts": 21500
    },
    "last_update": "2026-05-02T01:45:00Z",
    "recent_syncs": [
      {
        "step": "companyfacts_download",
        "time": "2026-05-02T00:30:00Z",
        "records": 7200,
        "duration_sec": 482.1,
        "status": "success"
      },
      {
        "step": "facts_load",
        "time": "2026-05-02T01:05:00Z",
        "records": 84300,
        "duration_sec": 612.4,
        "status": "success"
      },
      {
        "step": "standardized_metrics",
        "time": "2026-05-02T01:25:00Z",
        "records": 12800,
        "duration_sec": 178.3,
        "status": "success"
      },
      {
        "step": "derived_metrics",
        "time": "2026-05-02T01:40:00Z",
        "records": 8200,
        "duration_sec": 45.2,
        "status": "success"
      }
    ],
    "pipeline_health": "healthy",
    "staleness_hours": 8.5
  }
}
```

### GET /api/v1/financials/stock-overview

Market data snapshot for a ticker from yfinance-sourced daily data. Returns beta, close price, sector, industry, market cap, enterprise value, float shares, short data, first traded date, plus technical indicators (RSI, score, volume, pct_change, pct_from_high, above_200_sma, above_50_sma).

**Token cost:** 5 tokens per call

**Response fields:**
- `data.ticker` (string): Issuer ticker (canonical hyphen form, echoed back).
- `data.company` (string): Company name (Title Case from yfinance).
- `data.date` (string): ISO `YYYY-MM-DD` reference date for the snapshot (latest market close — typically prior trading day during US market hours, current trading day after close). May be 1-2 days stale on weekends/holidays.
- `data.close` (number): Last close price (USD per share). NOT split-adjusted server-side — reflects as-traded price for the reference date. For split-adjusted historical price series use external market-data sources.
- `data.beta` (number (nullable)): 5-year monthly beta vs S&P 500. Decimal (`1.0` = market-neutral, `>1` = higher-volatility, `<1` = lower-volatility). Null for very-recent IPOs (<1 year of price history).
- `data.sector` (string (nullable)): yfinance sector classification (matches Yahoo Finance's sector taxonomy — slightly different from Sharadar's). Null for unmapped tickers.
- `data.industry` (string (nullable)): yfinance industry classification (more specific than sector). Null for unmapped tickers.
- `data.market_cap` (number (nullable)): Market capitalization (USD). Computed as `close × shares_outstanding`. Use for size-based universe filters (e.g. mega-cap > $200B, large-cap $10-200B, mid-cap $2-10B, small-cap $300M-2B, micro-cap <$300M).
- `data.enterprise_value` (number (nullable)): Enterprise value (USD). `market_cap + total_debt - cash_and_equivalents`. The classic 'all-stakeholder' valuation metric — combine with [/financials/snapshot](/docs/company-data/company-financials-xbrl/get-financials-snapshot) EBITDA for EV/EBITDA multiple.
- `data.float_shares` (number (nullable)): Public float (shares freely tradable, excluding insider + institutional restricted holdings). Useful for liquidity-aware position sizing — small-caps with float < 50M shares can have wide bid-ask spreads.
- `data.shares_outstanding` (number (nullable)): Total shares outstanding (point-in-time). Compare against [/financials/metrics](/docs/company-data/company-financials-xbrl/get-financials-metrics) `shares_outstanding` (which is weighted-average for the period); they differ for issuers with active buyback/issuance.
- `data.short_percent_of_float` (number (nullable)): Short interest as fraction of float (decimal — `0.0072` = 0.72%). Updated bi-monthly (NYSE/NASDAQ short-interest publication cadence) so may lag by 2-3 weeks. Above 0.20 flags potentially-squeeze-able names.
- `data.short_ratio` (number (nullable)): Days-to-cover ratio: `short_interest / avg_daily_volume`. Higher = harder for shorts to cover. Above 5 days flags squeeze risk.
- `data.first_traded` (string (nullable)): Unix epoch seconds (as a string) of the ticker's first trading day. Useful for filtering recent IPOs (within 1 year). For human-readable date use the existing `date` semantic on `/api/v1/tickers/{ticker}/overview`.
- `data.rsi_14d` (number (nullable)): 14-day Relative Strength Index (technical momentum indicator). Range `[0, 100]`. Standard interpretation: >70 overbought, <30 oversold. Useful for short-term mean-reversion screens.
- `data.score` (number (nullable)): FinRadar composite technical score (proprietary blend of RSI + SMA-trend + volume signals). Range `[0, 100]`. Higher = stronger technical setup. NOT a buy/sell recommendation — a single technical-flavor signal among many.
- `data.volume` (number (nullable)): Latest trading-day volume (shares). Compare against `avg_volume_30d` for volume-spike detection.
- `data.avg_volume_30d` (number (nullable)): 30-day average daily trading volume. Smoother baseline than spot volume — `volume / avg_volume_30d > 2` flags abnormal-volume sessions.
- `data.pct_change_1d` (number (nullable)): 1-day percent price change (decimal — `0.0048` = +0.48%). Same-day if calling after close; previous-day-vs-day-before-that during market hours.
- `data.pct_change_30d` (number (nullable)): 30-day percent price change (decimal). Useful for medium-term momentum filters.
- `data.pct_from_52w_high` (number (nullable)): Percent from 52-week high (decimal — typically negative since price <= 52w high; `-0.038` = 3.8% below high). Above `-0.05` indicates strong-trend territory; below `-0.30` indicates significant drawdown.
- `data.pct_from_52w_low` (number (nullable)): Percent from 52-week low (decimal — typically positive). Combine with `pct_from_52w_high` for range-position assessment.
- `data.sma_50` (number (nullable)): 50-day simple moving average price (USD). Short-trend reference.
- `data.sma_200` (number (nullable)): 200-day simple moving average price (USD). Long-trend reference. Standard 'golden cross' = sma_50 crossing above sma_200; 'death cross' = below.
- `data.above_200_sma` (boolean (nullable)): Boolean: `true` when `close > sma_200`. The classic long-trend filter — most quant momentum strategies require `above_200_sma=true`.
- `data.above_50_sma` (boolean (nullable)): Boolean: `true` when `close > sma_50`. Short-trend filter.

**Since:** v3.4.0

**Utility:** Get current market data for DCF models and stock research pages.

**Use case:** DCF module (beta + close price), Financials module (sector, industry, market cap, enterprise value, float, short interest).

**Parameters:**
- `ticker` (query, required): Stock ticker symbol (canonical hyphen form). Returns 404 if ticker has no Yahoo Finance / yfinance daily-data coverage. Cache: 24h server-side.

**Sample response:**
```json
{
  "status": "success",
  "data": {
    "ticker": "AAPL",
    "company": "Apple Inc.",
    "date": "2026-05-01",
    "close": 268.5,
    "beta": 1.121,
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "market_cap": 3984500000000,
    "enterprise_value": 4058044000000,
    "float_shares": 14820000000,
    "shares_outstanding": 14840000000,
    "short_percent_of_float": 0.0072,
    "short_ratio": 1.38,
    "first_traded": "345479400",
    "rsi_14d": 58.4,
    "score": 72,
    "volume": 48230000,
    "avg_volume_30d": 52100000,
    "pct_change_1d": 0.0048,
    "pct_change_30d": 0.041,
    "pct_from_52w_high": -0.038,
    "pct_from_52w_low": 0.214,
    "sma_50": 261.2,
    "sma_200": 244.8,
    "above_200_sma": true,
    "above_50_sma": true
  }
}
```