# Response conventions

The `/metric/*` endpoints require the **Starter plan or higher**; Free callers receive `403 PLAN_TIER_INSUFFICIENT` (see [API key, account, and plan errors](/documents/errors.md#api-key-account-and-plan-errors)). The `formula_override` request field is additionally gated to the **Pro plan or higher** — Starter callers must omit `formula_override`.

Every metric returned by `/metric/*` endpoints carries a `status` field and a `derivation` field. The rest of the object's contents depend on these two.

## `status`

| Value | Meaning |
|---|---|
| `ok` | Metric was computed; `value` is set. |
| `not_applicable` | Metric does not apply to this filing. Carries a `reason` string; `value` is `null`. |
| `missing_input` | A required XBRL fact is missing. Carries a `missing_symbols` list; `value` is `null`. |
| `needs_price_data` | Price-sensitive metric called without `current_price`. `value` is `null`; pass `current_price` to upgrade to `ok`. |
| `needs_user_formula` | The filing uses a non-standard concept combination. Pass `accept_suggested_formula=true` or supply `formula_override` to compute. `value` is `null`; a `suggested_formula` field is included. |
| `needs_history` | A prior-period value is required (e.g. growth rates) but is not available for this filing. `value` is `null`. |
| `divide_by_zero` | Denominator was zero. `value` is `null`. |
| `eval_error` | Formula execution failed. `value` is `null`. |

`not_applicable` takes precedence over every other status — once an NA rule fires for a metric, the response will be `not_applicable` regardless of what would otherwise apply.

## `derivation`

| Value | Meaning |
|---|---|
| `derived` | Computed from multiple XBRL facts via the standard formula. |
| `as_reported` | Single XBRL fact taken at face value, no formula run. |
| `composite` | Built from multiple non-standard concepts (e.g. REIT CapEx = REInvestment + Maintenance). |
| `segment_sum` | No consolidated total in the filing; summed across segment members. |
| `class_sum` | Summed across asset / liability class members. |
| `company_override` | A company-specific override rule produced the value. |
| `proxy_substituted` | A proxy fact was used in place of the primary one (most often on ADR / foreign-issuer price-sensitive metrics). |
| `TTM_rollforward` | A trailing-12-month value for a quarterly filing. Comparable to annual filings of the same metric without further adjustment. |
| `user_formula_accepted` | Result of `accept_suggested_formula=true` — the returned `suggested_formula` was applied. |
| `user_formula_custom` | Result of a caller-supplied `formula_override`. |
| `user_must_compute` | Companion to `status="needs_user_formula"`. A caller-provided calculation is required. |
| `not_applicable` | Companion to `status="not_applicable"`. |

When a metric cannot be computed, `derivation` repeats its `status` (for example `missing_input` or `needs_price_data`). Branch on `status` first.

## `editable`

| Value | Meaning |
|---|---|
| `true` | `formula_override` applies to this metric. |
| `false` | `formula_override` does not apply to this metric. |

## Currency and FX

A metric object may carry these three currency-related fields:

| Field | Meaning |
|---|---|
| `unit` | Display unit. Either a currency code (`usd`, `eur`, `twd`, …) for absolute monetary metrics, or `ratio` / `percent` / `days` / `shares` etc. for non-monetary metrics. |
| `currency` | Source currency for absolute monetary metrics. Absent on ratio / percent / unitless metrics. |
| `fx_required` | `true` when the metric is denominated in a non-USD currency (caller may want to convert to USD before using the value). `false` when no conversion is needed (already USD, or unitless). |

For price-sensitive metrics on foreign-issuer filings (20-F / 40-F whose `reporting_currency` is not USD), the metric object also carries a `price_used` block:

| Subfield | Meaning |
|---|---|
| `close` | The price actually used in the formula (in the filer's reporting currency). |
| `date` | Date of `close`. |
| `source` | Identifier for the source of the price used. |
| `original_adr_price_usd` | The USD ADR price supplied (or filing-date USD price). |
| `adr_ratio` | ADR ratio (number of common shares per ADR). |
| `fx_rate_local_per_usd` | Conversion factor used for the period (filing-date price blocks). |
| `reporting_ccy` | Filer's reporting currency (e.g. `EUR`, `TWD`, `CAD`). |

To convert a foreign-issuer absolute metric to USD:

```text title="Formula"
value_usd = value / fx_rate_local_per_usd
```

For USD-reporting filings, `fx_required` is `false`, `currency` (when present) is `usd`, and `price_used` contains only `close`, `date`, `source`.

## Light and minimal views

Every `/metric/*` endpoint except `POST /metric/filings` accepts `detail` ([Response detail](/documents/responses.md#response-detail)).

- `"light"` leaves out each metric's `components`, and the `valuation_context` (`query_context` on `POST /metric/historical`) echo.
- `"minimal"` keeps each metric's `value`, `unit`, `currency`, `period_basis`, `adjusted_value` and `concept_variant`; `status`, `reason` and `error` when `status` is not `ok`; `missing_symbols` when `status` is `missing_input`; `derivation` when `status` is `ok` and it is not `as_reported` or `derived`; and the `date` of `price_used`.