# `POST /data/compare/facts`

**Purpose:** Compare XBRL **`fact_ids`** across **up to 25 filings**. Each filing row carries its own `fact_ids` list.

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filings` | array | Yes | 1–25 rows. Each row: `filing_id` **or** (`ticker` + `fiscal_year` + optional `form_type` and `quarter`), **plus** a required non-empty `fact_ids` list (max **500** per row; **2500** total ids across the whole request; each id ≤ **128** chars). |
| `detail` | string | No | Default `"full"`. `"light"` leaves out each fact's `dimensional_breakdowns` and each row's `classification.source.url`. See [Response detail](/documents/responses.md#response-detail). |

**Response:** `results` (per row: `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix`, optional `caveat`, `facts` with the fields of [`POST /data/facts`](/documents/post-datafacts.md), and for **Pro+** callers `classification`), `amendment_contexts`, optional `failed_filings` (as on [`POST /data/compare/line-items`](/documents/post-datacompareline-items.md)), `credits_used` and optional `_warnings`. A `_warnings` entry is appended when the compared filings' fiscal period end dates differ by more than 45 days.

**Partial-credit behavior:** Full request cost is `ceil(total_deduped_fact_ids / 5) × 10` credits over the compared rows. When your balance covers only part of it, you are charged that much and the response serves that many fact_ids (each 10 credits buy up to 5 ids; filings are processed in request order, and once the budget runs out the remaining filings come back with `facts: []`). A `_warnings` entry states how many ids were served of those requested, and `credits_used` is what was spent. A balance below 10 → **HTTP 402**.

**Errors:** as on [`POST /data/compare/line-items`](/documents/post-datacompareline-items.md): failed rows are listed in `failed_filings`; when every row fails, the request returns the first row's error with `failed_filings` in `detail`.

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 / 404 / 403 | the first row's code | Every row failed. |
| 402 | `CREDITS_INSUFFICIENT` | Balance below 10. |
| 422 | — | Limits, missing fact_ids, a row without `filing_id` or `ticker` + `fiscal_year`, unknown row keys, or other validation. |

**Example Request:**

```json
{
  "filings": [
    { "filing_id": 12345, "fact_ids": ["ix_1", "ix_2"] },
    { "filing_id": 12344, "fact_ids": ["ix_1"] }
  ]
}
```