# `POST /data/compare/line-items`

**Purpose:** Compare a list of **line-item names** (e.g. `revenue`, `net income`) across **up to 25 filings**. Names are resolved through the same L0–L3 tiered path as **[`POST /data/line-items`](/documents/post-dataline-items.md)**; per-line-item × per-filing pricing applies. Results are consolidated totals, as in [`POST /data/line-items`](/documents/post-dataline-items.md).

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filings` | array | Yes | 1–25 rows. Each row: `filing_id` **or** (`ticker` + `fiscal_year` + optional `form_type` and `quarter`), same rules as **`POST /data/facts`**. |
| `line_items` | array of string | Yes | Non-empty; max **50** strings; each max **256** 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:**

| Field | Meaning |
|-------|---------|
| `amendment_contexts` | Array parallel to `results`; each entry is an object or **`null`**. |
| `results` | Each element: `ticker`, `form_type`, `fiscal_year`, `quarter`, **`source_url_prefix`** (filing-level SEC URL base, may be `null`), optional **`caveat`** (per-row; see [Filing caveats](/documents/responses.md#filing-caveats)), **`unresolved`** (resolved line items with no consolidated-total fact in that filing), **`facts`** (array of fact objects; each fact carries either `fact_id` + `source_locator` or `fact_ids`, as in **`POST /data/line-items`**, plus **`_resolution_level`** = `"L0"` … `"L3"` indicating which tier matched that line item), and — for **Pro+** callers — a per-row **`classification`** block (see [Industry classification (Pro+)](/documents/coverage.md#industry-classification-pro)). |
| `failed_filings` | Optional. Rows that could not be compared, each `{index, error_code, message}` with the error that row alone would return; these rows are not charged. |
| `credits_used` | Per credit rules in [Credit summary](/documents/credits-rate-limits.md#credit-summary). |
| `credits_by_line_item` | Credits charged per requested line item, summed over the compared filings. |
| `_correction`, `_warnings` | Optional; same general meaning as **`POST /data/line-items`**. Multi-concept line items are ordered by Akkru smart ranking within each row's `facts`, same as `POST /data/line-items` (a recommendation only — review all results). A `_warnings` entry is appended when the compared filings' fiscal period end dates differ by more than 45 days. The dimensional-breakdown notice is aggregated into a single string listing affected filings + fact ids. Per-row caveats are also aggregated into top-level `_warnings` (deduplicated; see [Filing caveats](/documents/responses.md#filing-caveats)). When rows fail, a `_warnings` entry reads `{n} of {m} filings could not be compared; see failed_filings.` |

**Partial-credit behavior:** This endpoint charges per line item × per filing with partial-credit billing. When your balance cannot cover the full request, the remaining line items return as **unresolved**; `_warnings` / `_correction` show which, so you can top up and re-issue for the rest.

**Errors:** a row that cannot be resolved (`DATA_FILING_QUARTER_REQUIRED`, `DATA_FILING_NOT_FOUND`, a `PLAN_TIER_*` 403) is 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` | Zero balance. |
| 422 | — | Limits, missing line_items, a row without `filing_id` or `ticker` + `fiscal_year`, unknown row keys, or other validation. |

**Example Request:**

```json
{
  "filings": [
    { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2024 },
    { "ticker": "AAPL", "form_type": "10-K", "fiscal_year": 2023 }
  ],
  "line_items": ["revenue"]
}
```

**Example Response:**

```json
{
  "amendment_contexts": [null, null],
  "results": [
    {
      "ticker": "AAPL",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "quarter": "FY",
      "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20240928.htm",
      "facts": [
        {
          "metric": "revenue",
          "concept": "us-gaap_Revenue...",
          "fact_id": "f-1",
          "source_locator": "#fact-identifier-f-1",
          "value": 383285000000.0
        }
      ]
    },
    {
      "ticker": "AAPL",
      "form_type": "10-K",
      "fiscal_year": 2023,
      "quarter": "FY",
      "source_url_prefix": "https://www.sec.gov/ix?doc=/Archives/edgar/data/.../aapl-20230930.htm",
      "facts": [
        {
          "metric": "revenue",
          "concept": "us-gaap_Revenue...",
          "fact_id": "f-1",
          "source_locator": "#fact-identifier-f-1",
          "value": 394328000000.0
        }
      ]
    }
  ],
  "credits_used": 40
}
```