# `POST /data/line-items/dimensional-breakdown`

**Purpose:** Resolve a line-item name (e.g. `revenue`, `net income`) and return the dimensional breakdown of every consolidated fact that matches. Each match is one root with its axis-grouped slice facts. When the name matches more than one concept, matches come pre-ordered by Akkru smart ranking (same ordering as `POST /data/line-items`); the order is a recommendation only — review all matches and judge which one you need.

**Filing selection:** standard (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`).

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filing_id` | integer | Conditional | |
| `ticker` | string | Conditional | |
| `form_type` | string | No | Default `10-K`. |
| `fiscal_year` | integer | Conditional | |
| `quarter` | string | No | |
| `line_item` | string | **Yes** | A single line-item name (e.g. `"revenue"`). |
| `recursive` | boolean | No | Default `true`. |
| `detail` | string | No | Default `"full"`. Full and minimal views only: `"light"` returns the minimal view. See [Response detail](/documents/responses.md#response-detail). |

**Response:**

| Field | Meaning |
|-------|---------|
| `ticker`, `form_type`, `fiscal_year`, `quarter`, `source_url_prefix` | Filing identity. |
| `matches` | Array of `{root, groups, duplicate_root_fact_ids?}` entries. |
| `matches[].root` | Same shape as `root` in **[`POST /data/facts/dimensional-breakdown`](/documents/post-datafactsdimensional-breakdown.md)**, plus `metric` (echoes the request `line_item`) and `_resolution_level` (`"L0"`–`"L3"`). |
| `matches[].groups` | Same shape and ordering as `groups` in **[`POST /data/facts/dimensional-breakdown`](/documents/post-datafactsdimensional-breakdown.md)**. Each fact also carries `metric` and `_resolution_level`. |
| `matches[].duplicate_root_fact_ids` | Optional. Other `fact_id` values that resolved to the same logical fact as `root`. |
| `_correction` | Optional. Same shape as on **[`POST /data/line-items`](/documents/post-dataline-items.md)**. |
| `_warnings` | Optional. |
| `credits_used` | Resolver tier credit + `ceil(N_total / 5) × 10`, where `N_total` is the slice facts returned across all roots. |

**Member granularity within a group:** Same as **[`POST /data/facts/dimensional-breakdown`](/documents/post-datafactsdimensional-breakdown.md)** — summary members and their detail components may coexist; summing all facts in one group can double-count.

**Credits:** Tiered resolution credit (**L0=10 … L3=50**) + `ceil(N_total / 5) × 10`. Partial billing applies.

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings. |
| 404 | `DATA_FILING_NOT_FOUND` | Filing not found. |
| 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan. Not charged. |
| 402 | `CREDITS_INSUFFICIENT` | Zero balance. |
| 422 | — | Validation. |

**Example Request:**

```json
{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2025,
  "line_item": "revenue"
}
```

**Example Response (abridged):**

```json
{
  "ticker": "AAPL", "form_type": "10-K",
  "fiscal_year": 2025, "quarter": "FY",
  "source_url_prefix": "...",
  "matches": [
    {
      "root": {
        "metric": "revenue",
        "concept": "us-gaap_RevenueFromContractWithCustomerExcludingAssessedTax",
        "fact_id": "f-78",
        "value": 416161000000.0,
        "period": "2024-09-29 ~ 2025-09-27",
        "is_consolidated_total": "true",
        "dimensions": [],
        "_resolution_level": "L1"
      },
      "duplicate_root_fact_ids": ["f-392","f-1021","f-1113"],
      "groups": [ /* ... */ ]
    },
    {
      "root": { "metric": "revenue", "fact_id": "f-79",
                "value": 391035000000.0, "period": "2023-10-01 ~ 2024-09-28", "_resolution_level": "L1", "..." : "..." },
      "duplicate_root_fact_ids": ["f-393","f-1050","f-1114"],
      "groups": [ /* ... */ ]
    },
    {
      "root": { "metric": "revenue", "fact_id": "f-80",
                "value": 383285000000.0, "period": "2022-09-25 ~ 2023-09-30", "_resolution_level": "L1", "..." : "..." },
      "duplicate_root_fact_ids": ["f-394","f-1079","f-1115"],
      "groups": [ /* ... */ ]
    }
  ],
  "credits_used": 110
}
```