Skip to content
/api/v1/xbrl/companies/{id}/valuation

The valuation family — market capitalization, enterprise value, and the price multiples & yields (P/E, P/S, P/B, P/FCF, EV/EBITDA, EV/Sales, earnings yield, FCF yield, dividend yield) — for a company BY TICKER or CIK, computed at read time either AS OF a past date or LIVE off the latest close.

The valuation family — market capitalization, enterprise value, and the price multiples & yields (P/E, P/S, P/B, P/FCF, EV/EBITDA, EV/Sales, earnings yield, FCF yield, dividend yield) — for a company BY TICKER or CIK, computed at read time either AS OF a past date or LIVE off the latest close. Per-share market prices are never returned — only the multiple and `price_date`.

Why use this

Recompute the price-driven valuation cells at request time instead of reading the price frozen at the last nightly recompute: omit `as_of` for the LIVE current valuation (current-period cells valued off the latest close every request, `meta.price_date` carries that close's trade date); pass `as_of=YYYY-MM-DD` for the point-in-time valuation as it stood on that date; `basis=latest|original` elects the restated vs the as-known-then filing. Per-share prices are never exposed — you get the multiple, the raw quote is redacted.

Common use case

Charting a company's P/E, EV/EBITDA or dividend yield over time by ticker; a live current-valuation snapshot with the price date attached; replaying the valuation as it stood on a past date (fundamentals-in-force x price-then).

The valuation family for a company, computed at READ time — the ONE part of the fundamentals surface whose value moves with market price. The stored ratio cells carry the price frozen at the last nightly recompute; this endpoint recomputes the price-driven cells (market cap, enterprise value, the price multiples and yields) fresh per request. Two modes on ONE route: omit as_of and you get the LIVE current valuation — the current-period cells valued off the latest close every request, with meta.price_date (and the current cell's price_date) telling you the trade date of that close, so you can see whether it is today or a stale trading day. Pass as_of=YYYY-MM-DD and you get the point-in-time valuation as it stood on that date — the fundamentals in force then (capped to filings the market had seen) paired with the price then; basis=latest uses the restated view, basis=original the as-known-then filing. period is A (default) | Q | TTM; years bounds the window (<= 25). Per-share market prices are NEVER exposed: the price is multiplied into market cap and its magnitude is redacted from every receipt (each cell's inputs records market_price with a null, redacted value) — you receive the multiple, never the underlying quote. Errors: 400 INVALID_PARAM (bad period/years/as_of/basis); 404 UNKNOWN_TICKER (the id matches no US filer); 404 NOT_YET_PARSED (a real filer with no standardized data yet). The endpoint is LIVE and serves both the as-of and the live valuation.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
idpathrequiredCompany identifier: a ticker (e.g. `AAPL`; case-insensitive, `.`/`/` fold to `-` so `BRK.A`=`BRK-A`) or an all-digits SEC CIK (bare or zero-padded). Resolves through the same canonical resolver the other XBRL company endpoints use. A ticker that matches no US filer -> 404 `UNKNOWN_TICKER`; a real filer with no standardized data in the engine yet -> 404 `NOT_YET_PARSED` (poll `/api/v1/xbrl/coverage`).AAPL
periodqueryoptionalA`A` (annual, default) | `Q` (quarterly) | `TTM` (trailing twelve months). Any other value -> 400 INVALID_PARAM.A
yearsqueryoptional5Window depth in years (default 5, capped at 25). Non-numeric or < 1 -> 400 INVALID_PARAM.5
as_ofqueryoptionalPoint-in-time: reconstruct the valuation as it stood on this date (`YYYY-MM-DD`) — the fundamentals in force then paired with the market price then. Omit for the LIVE valuation off the latest close. Malformed -> 400 INVALID_PARAM.2024-06-30
basisqueryoptionallatestApplies to the `as_of` (point-in-time) path only. `latest` (default) elects the most recently filed version of each period (restated view); `original` elects the earliest-filed version (as-known-then). Any other value -> 400 INVALID_PARAM.latest

Response schema

FieldTypeNullableDescription
dataarraynoFlat list of valuation cells. Each: `{metric, fiscal_year, fiscal_period, period_end, value, status, reason_code, unit, method_labels, formula_version, inputs}`. `fiscal_year`/`fiscal_period` are the company's own fiscal-year naming, reconciled per company across its filings (a quarter carries the year of the fiscal year it sits in); `period_end` is the date to key on. The LIVE current cell also carries `price_date` (the latest close's trade date).
data[].inputsarrayyesThe cell's computation receipt. The market-price leg is recorded as `{metric:'market_price', value:null, redacted:true, source:'market'}` — the price magnitude is intentionally NOT exposed (you get the multiple, not the raw quote).
data[].price_datestringyesLIVE path only, current cell only: the trade date (ISO) of the latest close used to value it. Absent on historical cells and on every `as_of` (point-in-time) response.
meta.modestringno`live` (no `as_of` — valued off the latest close) or `as_of` (point-in-time). `meta` also carries `ticker`, `cik`, `covered`, `period`, `years`, `as_of`, `basis` (as-of path only), `price_date`, and `valuation_family`.

Sample response

·
  • "request_id": null
  • "timestamp": "2026-09-13T00:00:00Z"
  • "status": "success"
  • "data":
    ]
  • "meta":
    • "ticker": "AAPL"
    • "cik": "320193"
    • "covered": true
    • "period": "A"
    • "years": 5
    • "mode": "live"
    • "as_of": null
    • "basis": null
    • "price_date": "2026-07-15"
    • "valuation_family": true
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/xbrl/companies/AAPL/valuation?api_Token=YOUR_API_KEY&period=A&years=5&as_of=2024-06-30&basis=latest" \
  -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).