# `POST /metric/all`

**Purpose:** Return the **full metrics object** for one filing, including realtime price-sensitive metrics when the caller supplies `current_price`, and optional **formula** overrides.

**Filing selection:** exactly one of **`metric_group_id`** (from **`POST /metric/filings`**), **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**.

**Request:**

| Field | Type | Default | Notes |
|-------|------|---------|--------|
| `metric_group_id` | integer | — | Conditional. 1–10⁹. |
| `filing_id` | integer | — | Conditional. 1–10⁹. |
| `ticker` | string | — | Conditional, with `fiscal_year`. 1–32 characters. |
| `fiscal_year` | integer | — | Conditional, with `ticker`. 1990–2100. |
| `form_type` | string | `10-K` | Only with `ticker` and `fiscal_year`. |
| `quarter` | string | `null` | Only with `ticker` and `fiscal_year`. |
| `as_of_date` | string | `null` | `YYYY-MM-DD`: exclude this filing if its filing date is after this date. |
| `accept_suggested_formula` | boolean | `false` | When `true`, applies suggested formula hints included with the filing’s metrics (if any). |
| `formula_override` | object | `null` | Per-metric overrides. **Keys are metric names** (e.g. `"operating_margin"`). Values are objects containing `"concepts"` (array of strings, **at most 50** entries per metric) and `"operators"` (array of strings, e.g. `["+", "-"]`, length must be exactly `len(concepts) - 1`). A lone top-level `{ "concepts": ... }` object is **invalid**. |
| `current_price` | number | `null` | USD price used to compute realtime price-sensitive metrics (`market_cap`, `pe_ratio`, `enterprise_value`, `price_to_book`, `price_to_sales`, `price_to_cash_flow`, `ev_to_ebitda`, `ev_to_revenue`, `ev_to_fcf`, `fcf_yield`, `dividend_yield`, `buyback_yield`, `owner_earnings_yield`). Must be `> 0`, `≤ 10,000,000`, with at most **4 decimal places**. Pass the USD price as-is for all filings, including foreign-issuer ADRs. Invalid values return **HTTP 422** without charging credits. When omitted, the `realtime` block is replaced by `{ "status": "missing", "hint": "..." }` and the same hint appears in `_warnings`. |
| `current_fx_rate` | number | `null` | Optional fallback FX rate (units of the filing's `reporting_currency` per 1 USD), used only when an up-to-date conversion rate is temporarily unavailable for foreign-issuer ADR filings. Must be `> 0`, `≤ 1,000,000`, with at most **6 decimal places**. Invalid values return **HTTP 422** without charging credits. |
| `detail` | string | `"full"` | `"light"` leaves out each metric's `components`. See [Light and minimal views](/documents/response-conventions.md#light-and-minimal-views). |

**Response:**

| Field | Meaning |
|-------|---------|
| `credits_used` | **158**. |
| `metric_group_id` | The metric group ID actually used (may be `null` if excluded by `as_of_date`). |
| `valuation_context` | Echo of flags and formula inputs. |
| `ticker`, `form_type`, `fiscal_year`, `quarter`, `cik`, `source_accession`, `primary_document`, `source_url_prefix` | Filing identity and SEC base URL. `source_url_prefix` may be `null`; combine it with each fact’s `source_locator` (see below) to build the SEC viewer URL. |
| `segments` | Array of segment data. |
| `price_insensitive_metrics` | Object containing metrics that do not depend on stock price. Within each metric, nested `fact_refs` / `components` entries that expose `fact_id` also expose **`source_locator`** (may be `null`). |
| `price_sensitive_metrics` | Object containing metrics that depend on stock price: a `filing_date_price` + `historical` pair (the metrics computed from the filing-date stock price) and, when the filing has price-sensitive metrics, a `realtime` sub-object (computed from the request's `current_price`; when realtime cannot be computed it is `{ "status": "missing" \| "missing_fx_fallback", "hint": "..." }`). For foreign-issuer ADR filings each computed metric carries a `price_used` block — see [Response conventions](/documents/response-conventions.md). Same `source_locator` convention on nested fact references where `fact_id` is present. **[`POST /metric/all/filing-date`](/documents/post-metricallfiling-date.md)** returns the filing-date block only. |
| `price_context` | Present whenever the response would include a `realtime` block. `status` is `"ok"` (price applied), `"missing"` (no `current_price` supplied), or `"missing_fx_fallback"` (foreign-issuer filing and an up-to-date conversion rate is temporarily unavailable). When `ok`, also includes `price`, `price_date`, `source: "user_supplied"`, and `fx_fallback_used: true` if the caller-supplied `current_fx_rate` was used because an up-to-date rate was unavailable. `mode` is always present; on the two non-`ok` statuses a `message` states what to send. |
| `ttm_composite`, `dei_corrected` | Optional root fields, present when the filing has them. |
| `amended` | Present (`true`) when this filing had a later amendment merged in. The returned metric values are already the amended figures. |
| `corporate_actions` | Optional root field, present when the ticker has corporate action events in the lookback window. Contains `events_in_lookback` and `events_after_period_end` (relative to this filing's period end); each event carries `ex_date`, `ratio`, `type` (`forward` / `reverse`), `event_type` (e.g. `stock_split`, `stock_dividend`), `affects_total_shares`, `affects_holder_share_count`, and `relevant_to_metrics`. Also carries `adjustment_factor_to_today` (factor converting this filing's per-share basis to the current basis), `adjustment_factor_anchor` (the date the factor is anchored on), and `adjustment_factor_anchor_basis` (how the anchor is chosen; `period_end`). When `adjustment_factor_to_today` is not `1`, three per-share metrics — `pe_ratio`, `dividend_yield`, `eps_growth_yoy` — additionally carry `adjusted_value`, `adjustment_factor`, and `comparable_to_current_basis`, so values from this filing can be compared on the current per-share basis; when it is `1` the filing is already on that basis and those three fields are absent. Total values (revenue, market_cap, etc.) are unaffected. Tickers with no events in the window omit the field entirely. |
| `_warnings` | Optional; warnings about amendments or formulas. |

**Errors:**

Errors before the charge (not charged):

| HTTP | `error_code` | When |
|------|----------------|------|
| 404 | `METRIC_GROUP_NOT_FOUND` | Unknown `metric_group_id`. |
| 404 | `DATA_FILING_NOT_FOUND` | No filing for the given `filing_id` or `ticker` + `fiscal_year`. |
| 400 | `DATA_FILING_QUARTER_REQUIRED` | Several filings match without a quarter; message lists available quarters. |
| 404 | `METRIC_SUMMARY_NOT_FOUND` | Filing has no metrics summary. |
| 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | The ticker is a Korean, Japanese, European or China A-share company. |
| 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` | `fiscal_year` is before your plan's history window. |
| 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company, named by `ticker`, is outside your plan's coverage scope. |
| 403 | `PLAN_TIER_INSUFFICIENT` | The filing, named by `metric_group_id` or `filing_id`, is outside your plan. |
| 403 | `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE` | `formula_override` below the Pro plan. |
| 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. |
| 422 | `VALIDATION_ERROR` | Filing selection (`Provide exactly one of: metric_group_id, filing_id, or both ticker and fiscal_year.`, `form_type and quarter can only be used with ticker and fiscal_year.`); `current_price` is non-numeric, non-finite, `≤ 0`, `> 10,000,000`, or has more than 4 decimal places; **or** `current_fx_rate` is non-numeric, non-finite, `≤ 0`, `> 1,000,000`, or has more than 6 decimal places. |

Errors after the charge (**charged 158**, `detail.credits_used`):

| HTTP | `error_code` | When |
|------|----------------|------|
| 404 | `METRIC_SUMMARY_OBJECT_MISSING` | The metrics summary could not be retrieved. |
| 500 | `METRIC_SUMMARY_INVALID_FORMAT` | The metrics summary data is invalid. |
| 409 | `METRIC_FORMULA_OVERRIDE_INVALID` | Invalid `formula_override`. |
| 422 | `METRIC_FORMULA_APPLY_FAILED` | Formula application failed. |

**Example Request:**

```json
{
  "metric_group_id": 12345,
  "current_price": 225.0,
  "formula_override": {
    "operating_margin": {
      "concepts": ["us-gaap_GrossProfit", "us-gaap_SellingGeneralAndAdministrativeExpense"],
      "operators": ["-"]
    }
  }
}
```

**Example Response:**

```json
{
  "credits_used": 158,
  "metric_group_id": 12345,
  "valuation_context": {    "as_of_date": null,
    "accept_suggested_formula": false,
    "formula_override": null
  },
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "quarter": "FY",
  "cik": "0000320193",
  "source_accession": "0000320193-24-000123",
  "primary_document": "aapl-20240928.htm",
  "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm",
  "segments": [],
  "price_insensitive_metrics": {
    "revenue": { "value": 383285000000.0, "unit": "USD" }
  },
  "price_sensitive_metrics": {
    "realtime": {
      "market_cap": { "value": 3404250000000.0, "unit": "USD" }
    }
  },
  "price_context": {
    "mode": "user_supplied",
    "status": "ok",
    "price": 225.0,
    "price_date": "2026-05-18",
    "source": "user_supplied"
  },
  "_warnings": []
}
```

**Example Response (filing affected by a stock split):**

```json
{
  "ticker": "NVDA",
  "fiscal_year": 2025,
  "quarter": "Q1",
  "corporate_actions": {
    "events_after_period_end": [
      { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward", "event_type": "stock_split",
        "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true }
    ],
    "events_in_lookback": [
      { "ex_date": "2021-07-20", "ratio": 4.0,  "type": "forward", "event_type": "stock_split",
        "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true },
      { "ex_date": "2024-06-10", "ratio": 10.0, "type": "forward", "event_type": "stock_split",
        "affects_total_shares": true, "affects_holder_share_count": true, "relevant_to_metrics": true }
    ],
    "adjustment_factor_to_today": 10.0,
    "adjustment_factor_anchor": "2024-04-28",
    "adjustment_factor_anchor_basis": "period_end"
  },
  "price_sensitive_metrics": {
    "realtime": {
      "pe_ratio": {
        "value": 24.25,
        "adjusted_value": 2.43,
        "adjustment_factor": 10.0,
        "comparable_to_current_basis": false
      }
    }
  }
}
```