# `POST /metric/items`

**Purpose:** Same sourcing as **`POST /metric/all`**, but returns **only** the metric names you list.

**Request:** Same as **`POST /metric/all`**, plus:

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `metric_names` | array of string | Yes | 1–100 names from the [catalog](/documents/supported-metric-catalog.md); each max **256** characters. |
| `detail` | string | No | Same as **`POST /metric/all`**. See [Light and minimal views](/documents/response-conventions.md#light-and-minimal-views). |

**Credits:** **158**, when at least one name is in the catalog.

**Response:**

| Field | Meaning |
|-------|---------|
| `credits_used` | **158**. |
| `metric_group_id` | The metric group ID actually used. |
| `valuation_context` | Echo of flags, formula inputs, and requested `metric_names`. |
| `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. |
| `price_insensitive_metrics` | Object containing the requested price-insensitive metrics. Nested `fact_refs` / `components` entries with `fact_id` also expose **`source_locator`** (may be `null`). |
| `price_sensitive_metrics` | Object containing a `filing_date_price` + `historical` pair (the requested price-sensitive metrics computed from the filing-date stock price; `historical` is `{}` when none were requested) and, when price-sensitive metrics were requested, a `realtime` sub-object. The `realtime` sub-object follows the same convention as [`POST /metric/all`](/documents/post-metricall.md): metric rows when `current_price` is supplied, `{ "status": "missing", "hint": "..." }` otherwise. Same `source_locator` convention on nested fact references where `fact_id` is present. |
| `price_context` | Present whenever the response would include a `realtime` block (same shape as in [`POST /metric/all`](/documents/post-metricall.md)). |
| `segments` | Array of segment data. |
| `ttm_composite`, `dei_corrected` | Optional root fields, present when the filing has them. |
| `corporate_actions` | Optional root field; same shape and semantics as in [`POST /metric/all`](/documents/post-metricall.md). The same per-metric split variants appear on `pe_ratio` / `dividend_yield` / `eps_growth_yoy` when you request them. |
| `_metric_name_errors`, `_supported_metric_names`, `_supported_metric_names_note` | Present when some requested names are outside the catalog or not in this filing: one line per such name, plus every supported name. |
| `_warnings` | Optional; warnings about amendments or formulas. |

**Errors:** Same as **`POST /metric/all`**, plus:

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `METRIC_INVALID_METRIC_NAME` | No requested name is in the catalog; `detail` lists every supported name in `_supported_metric_names`. Not charged. |

**Example Request:**

```json
{
  "metric_group_id": 12345,
  "metric_names": ["gross_margin", "net_margin"]
}
```

**Example Response:**

```json
{
  "credits_used": 158,
  "metric_group_id": 12345,
  "valuation_context": {    "as_of_date": null,
    "accept_suggested_formula": false,
    "formula_override": null,
    "metric_names": ["gross_margin", "net_margin"]
  },
  "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",
  "price_insensitive_metrics": {
    "gross_margin": { "value": 0.4621, "unit": "ratio" },
    "net_margin": { "value": 0.2397, "unit": "ratio" }
  },
  "price_sensitive_metrics": { "filing_date_price": 259.48, "historical": {} }
}
```