# `POST /metric/historical`

**Purpose:** Return metrics for **many periods** (quarterly or annual) for one ticker, **paginated**. Price-sensitive values use **filing-date figures only** (no live market refresh).

**Request:**

| Field | Type | Default | Notes |
|-------|------|---------|--------|
| `ticker` | string | — | **Required.** 1–32 characters. |
| `period_type` | string | `quarterly` | Either **`quarterly`** or **`annual`**. `annual` covers `10-K` plus the foreign-issuer annual reports `20-F` and `40-F`; `quarterly` covers `10-Q` only (foreign issuers have no quarterly counterpart). |
| `start_period_start` | string | `null` | Optional filter: period start **ISO date** (`YYYY-MM-DD`). |
| `end_period_end` | string | `null` | Optional filter: same date rules. |
| `metric_names` | array | `null` | If omitted or null, **all** metrics returned for each period; if set, only those names from the [catalog](/documents/supported-metric-catalog.md). Max **100** names. |
| `as_of_date` | string | `null` | Same meaning as **`/metric/all`**. |
| `accept_suggested_formula` | boolean | `false` | |
| `formula_override` | object | `null` | Same structure rules as **`/metric/all`** (including **≤ 50** `concepts` per metric). |
| `sort` | string | `period_end_asc` | **`period_end_asc`** or **`period_end_desc`**. |
| `page` | integer | `1` | Page index, 1–10⁶. |
| `page_size` | integer | `3` | 1–**5** (maximum page size). |
| `detail` | string | `"full"` | Same as **`POST /metric/all`**, applied to every `periods[*]`. See [Light and minimal views](/documents/response-conventions.md#light-and-minimal-views). |

**Credits:** **55** (base) **+ 148 × (number of filing rows on the current page)**. If the base debit succeeds but the per-row debit fails, you receive **`402`** with `credits_used: 55`, every matching filing in `metric_groups` (same shape as [`POST /metric/filings`](/documents/post-metricfilings.md), not paged) and `company`.

**Response:**

| Field | Meaning |
|-------|---------|
| `page`, `page_size`, `total_items`, `has_more`, `next_page` | Paging; `next_page` is `null` on the last page. |
| `credits_used` | Number of credits deducted for this request. |
| `ticker` | The company's symbol. |
| `query_context` | Echo of the request parameters used for the query. |
| `periods` | Array of period objects. Each includes filing metadata (including **`source_url_prefix`** per period, may be `null`), `price_insensitive_metrics`, `price_sensitive_metrics` (each a map of metric name to metric object, at the filing-date price), and optional root meta fields. Within each metric object, `fact_refs` / `components` entries that expose `fact_id` also expose **`source_locator`** (may be `null`). Each period may carry its own **`corporate_actions`** field, an **`amended`** flag (`true` when that period's filing had a merged amendment), and per-metric split variants as described in [`POST /metric/all`](/documents/post-metricall.md); when comparing a per-share metric across periods that straddle a split, use `adjusted_value` instead of raw `value`. |
| `_warnings` | Optional; warnings about amendments or formulas. |

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `METRIC_INVALID_METRIC_NAME` | A name in `metric_names` is outside the catalog; `detail` lists every supported name in `_supported_metric_names`. Not charged. |
| 400 | `METRIC_INVALID_METRIC_NAME` | A returned period lacks a requested name. **Charged** (`detail.credits_used`). |
| 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | The ticker is a Korean, Japanese, European or China A-share company (not charged). |
| 403 | `PLAN_TIER_INSUFFICIENT_FORMULA_OVERRIDE` | `formula_override` below the Pro plan (not charged). |
| 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope (not charged). |
| 402 | `CREDITS_INSUFFICIENT` | Insufficient credits for base or per-row charges. |
| 404 | `METRIC_SUMMARY_OBJECT_MISSING` | The metrics summary could not be retrieved. **Charged** (`detail.credits_used`). |
| 500 | `METRIC_SUMMARY_INVALID_FORMAT` | The metrics summary data is invalid. **Charged** (`detail.credits_used`). |
| 409 | `METRIC_FORMULA_OVERRIDE_INVALID` | Invalid `formula_override`. **Charged** (`detail.credits_used`). |
| 422 | `METRIC_FORMULA_APPLY_FAILED` | Formula application failed. **Charged** (`detail.credits_used`). |
| 422 | `VALIDATION_ERROR` | Validation (`period_type`, `sort`, limits). |

**Example Request:**

```json
{
  "ticker": "AAPL",
  "period_type": "quarterly",
  "page": 1,
  "page_size": 2
}
```

**Example Response:**

```json
{
  "page": 1,
  "page_size": 2,
  "total_items": 10,
  "has_more": true,
  "next_page": 2,
  "credits_used": 351,
  "ticker": "AAPL",
  "query_context": {
    "period_type": "quarterly",
    "start_period_start": null,
    "end_period_end": null,
    "as_of_date": null,    "accept_suggested_formula": false,
    "formula_override": null,
    "metric_names": null,
    "sort": "period_end_asc"
  },
  "periods": [
    {
      "metric_group_id": 9876,
      "period_start": "2024-07-01",
      "period_end": "2024-09-28",
      "filing_date": "2024-11-01",
      "ticker": "AAPL",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "quarter": "Q4",
      "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": 94930000000.0, "unit": "USD" }
      },
      "price_sensitive_metrics": {
        "market_cap": { "value": 3300000000000.0, "unit": "USD" }
      }
    }
  ]
}
```