/api/v1/xbrl/companies/{id}/valuationThe 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
Common use case
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
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| id | path | required | — | — | Company 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 |
| period | query | optional | A | — | `A` (annual, default) | `Q` (quarterly) | `TTM` (trailing twelve months). Any other value -> 400 INVALID_PARAM. | A |
| years | query | optional | 5 | — | Window depth in years (default 5, capped at 25). Non-numeric or < 1 -> 400 INVALID_PARAM. | 5 |
| as_of | query | optional | — | — | Point-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 |
| basis | query | optional | latest | — | Applies 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
| Field | Type | Nullable | Description |
|---|---|---|---|
| data | array | no | Flat 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[].inputs | array | yes | The 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_date | string | yes | LIVE 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.mode | string | no | `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
| 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
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).