# `POST /data/line-items`

**Purpose:** Return structured facts for **one** filing by **line-item name** (e.g. `revenue`, `net income`, `operating expenses`). Names are resolved through a tiered L0–L3 path; per-line-item credit pricing.

**Filing selection:** supply **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. Giving both, or `form_type` or `quarter` with `filing_id`, returns 422.

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filing_id` | integer | Conditional | 1–10⁹. |
| `ticker` | string | Conditional | Required if `filing_id` omitted. 1–32 characters. |
| `form_type` | string | No | Default `10-K`, max 32. |
| `fiscal_year` | integer | Conditional | Required if `filing_id` omitted. 1990–2100. |
| `quarter` | string | No | Max 4 characters. |
| `line_items` | array of string | Yes | Non-empty; max **50** entries; each entry max **256** characters. A name given twice is charged once. |
| `detail` | string | No | Default `"full"`. `"light"` leaves out each result's `dimensional_breakdowns`. See [Response detail](/documents/responses.md#response-detail). |

**Response:** `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix`, `results`, `credits_used`, `credits_by_line_item` (credits charged per requested line item), optional `_correction` / `_warnings`, optional `amendment_context`. Each entry in `results` carries `metric`, `concept`, `value`, `raw_value`, `unit`, `period`, `dimensions`, `dimensional_breakdowns`, `restated` / `prior` (same meaning as on **[`POST /data/facts`](/documents/post-datafacts.md)**; `null` when the fact was not touched by an amendment), **`_resolution_level`** (`"L0"`, `"L1"`, `"L2"`, or `"L3"`), and **one of**:

- **`fact_id`** (string) + **`source_locator`** (string) — the number appears at exactly one position in the source filing.
- **`fact_ids`** (list of `{fact_id, source_locator}` objects) — the same logical fact (matching concept, value, period, dimensions, and breakdowns) is reported at multiple positions in the source filing (e.g. income statement + equity statement + cash flow). All positions are listed equal-rank.

The two fields are mutually exclusive; each result row carries exactly one of them.

When one line-item name matches more than one concept, `results` come ordered by Akkru smart ranking and a `_warnings` entry gives the number of matched concepts. Review all returned results and judge which one you need.

Results are consolidated totals. Slice values (a product line, segment, or region) are read with `POST /data/facts/dimensional-breakdown` / `POST /data/line-items/dimensional-breakdown` from the total's `fact_id`, or with `POST /data/statement` for the full statement table.

`is_consolidated_total` is a string: `"true"` (the source filing explicitly tags the value as a consolidated total), `"equivalent"` (the source filing does not explicitly tag the value as a consolidated total; the value is presented as an equivalent consolidated total; see `_warnings`), or `"false"`.

`revenue` follows each filing's own reported top line; for financial-sector companies (banks, brokers, insurers) that top line is a net figure (e.g. net interest income plus net fee income, or insurance revenue).

Per-share items that a filing tags only per share class or dividend type are read from the statements and notes via `POST /data/filing-statements` + `POST /data/statement`.

**Credits:** tiered L0=10 … L3=50 per line item, partial-credit billing. Zero balance → **HTTP 402**.

**Errors:** `400 DATA_FILING_QUARTER_REQUIRED`, `404 DATA_FILING_NOT_FOUND`, `403 PLAN_TIER_INSUFFICIENT_HISTORY` / `PLAN_TIER_INSUFFICIENT` / `PLAN_TIER_INSUFFICIENT_COVERAGE` (not charged), `402 CREDITS_INSUFFICIENT`, `422` validation.

**Example Request:**

```json
{
  "filing_id": 12345,
  "line_items": ["revenue", "net income"],
  "detail": "light"
}
```

**Example response excerpt** (one single-position row + one multi-position row):

```json
{
  "results": [
    {
      "metric": "depreciation",
      "concept": "us-gaap_Depreciation",
      "fact_id": "f-665",
      "source_locator": "aapl-20250927.htm#fact-identifier-780",
      "value": 8000000000.0,
      "raw_value": "8.0",
      "unit": "usd",
      "period": "2024-09-29 ~ 2025-09-27",
      "is_consolidated_total": "true",
      "_resolution_level": "L1"
    },
    {
      "metric": "revenue",
      "concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax",
      "fact_ids": [
        { "fact_id": "f-78",   "source_locator": "aapl-20250927.htm#fact-identifier-95"  },
        { "fact_id": "f-392",  "source_locator": "aapl-20250927.htm#fact-identifier-113" },
        { "fact_id": "f-1021", "source_locator": "aapl-20250927.htm#fact-identifier-121" },
        { "fact_id": "f-1113", "source_locator": "aapl-20250927.htm#fact-identifier-143" }
      ],
      "value": 416161000000.0,
      "raw_value": "416,161",
      "unit": "usd",
      "period": "2024-09-29 ~ 2025-09-27",
      "is_consolidated_total": "true",
      "_resolution_level": "L1"
    }
  ],
  "credits_used": 40
}
```