# `POST /data/statement`

**Purpose:** Return one or more **financial statement block(s)** (JSON) for a filing. Three mutually exclusive lookup modes:

- **`role_label` mode** — the filer's original XBRL role string (varies per filer; e.g. `"CONSOLIDATED STATEMENTS OF OPERATIONS"` for Apple). Returns the one matched block.
- **`statement_type` mode** — the canonical statement name (e.g. `"Income Statement"`, `"Balance Sheet"`, `"Comprehensive Income"`, `"Stockholders Equity"`, `"Cash Flow Statement"`). Call **[`POST /data/filing-statements`](/documents/post-datafiling-statements.md)** for the valid values in a specific filing. Case-insensitive; trailing `(N)` suffix is ignored. Returns every matching block; a block that combines several statements matches each of its names. Available for SEC filings only; use `role_label` mode for other jurisdictions.
- **`block_index` mode** — the block's `block_index` as [`POST /data/filing-statements`](/documents/post-datafiling-statements.md) currently lists it. Returns that block.

The 5 main statements also have their own [statement endpoints](/documents/statement-endpoints-datastatement.md) (`/data/income-statement` etc.) with the same response shape.

**Filing selection:** same pattern as **`POST /data/facts`** (`filing_id` **or** `ticker` + `fiscal_year` + `form_type` + optional `quarter`).

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filing_id` | integer | Conditional | Same rules as facts. |
| `ticker` | string | Conditional | |
| `form_type` | string | No | Default `10-K`. |
| `fiscal_year` | integer | Conditional | |
| `quarter` | string | No | |
| `role_label` | string | **One of `role_label` / `statement_type` / `block_index`** | 1–4000 characters; original filer XBRL role string. |
| `statement_type` | string | **One of `role_label` / `statement_type` / `block_index`** | 1–4000 characters; canonical statement-type label. |
| `block_index` | integer | **One of `role_label` / `statement_type` / `block_index`** | 0–32767; as listed by `POST /data/filing-statements`. |
| `detail` | string | No | Default `"full"`. `"light"` leaves out `concept_ns`, `concept_local`, `item_type`, `decimals`, `sign_attr` and `format` from each fact's `xbrl_fact`. `"minimal"` keeps only `line_items` and, for each fact, its row label, `ix_id`, `concept`, `calculated_value` (`raw_value` when that is empty), `unit`, period and `dimensions` (China A-share filings: also `note_scope`); a fact repeated under `child_components` is listed once. See [Response detail](/documents/responses.md#response-detail). |

**Credits:**

- `role_label` mode: tiered **28 / 48**. **28** is debited before the filing is resolved (balance below 28 → **HTTP 402**); the extra **20** of the higher (48-credit) tier is debited after matching, up to your remaining balance.
- `statement_type` and `block_index` modes: **28** flat, debited before the filing is resolved (balance below 28 → **HTTP 402**).

**Response:**

| Field | Meaning |
|-------|---------|
| `ticker`, `form_type`, `fiscal_year`, `quarter` | Filing identity. |
| `matches` | Array of match objects (length 1 for role_label and block_index mode; length 1+ for statement_type mode). Each has `block_index`, `role_label`, `statement_type` (array of names; more than one when the block combines several statements), `matched_via` (describes how it was selected), and `block` (the statement block content; an entry under `block.child_components` that repeats the `block.parent_xbrl_table.mapped_xbrl_facts` entry with the same `html_locator.ix_id` carries only that `ix_id`). |
| `credits_used` | Number of credits deducted. |
| `amendment_context` | Optional; restatement or amendment information. |
| `_correction` | Optional; present on the 48-credit tier. |
| `_warnings` | Optional. |

`calculated_value` (on each fact in `block`) is the XBRL value as filed.

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings (charged). |
| 404 | `DATA_FILING_NOT_FOUND` | Filing not found. **Still charged 28 credits.** |
| 404 | `DATA_STATEMENT_ROLE_LABEL_UNRESOLVED` | role_label mode: no block matched; charged for the match tier reached. |
| 404 | `DATA_STATEMENT_NOT_AVAILABLE_IN_FILING` | statement_type mode: no block has this statement_type (charged). |
| 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_KR` | statement_type mode on a Korean (DART) filing; use `role_label` mode (charged). |
| 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_JP` | statement_type mode on a Japanese (EDINET) filing; use `role_label` mode (charged). |
| 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_EU` | statement_type mode on a European (ESEF) filing; use `role_label` mode (charged). |
| 400 | `DATA_STATEMENT_TYPE_UNSUPPORTED_FOR_CN` | statement_type mode on a China A-share filing; use `role_label` mode (charged). |
| 404 | `DATA_STATEMENT_BLOCK_INDEX_NOT_FOUND` | block_index mode: the filing has no block at that position (charged). |
| 404 | `DATA_STATEMENT_BLOCK_JSON_MISSING` | The block was found but its content is unavailable (**charged**). |
| 403 | `PLAN_TIER_INSUFFICIENT_HISTORY` | The filing, named by `ticker` and `fiscal_year`, is before your plan's history window. Not charged. |
| 403 | `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing (by `filing_id`) or the company (by `ticker`) is outside your plan. **Charged 28.** |
| 402 | `CREDITS_INSUFFICIENT` | Balance below 28. |
| 422 | — | Validation (e.g. more than one of `role_label`, `statement_type`, `block_index` given, or none). |

**Example Request (role_label mode):**

```json
{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS"
}
```

**Example Request (statement_type mode):**

```json
{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "statement_type": "Income Statement"
}
```

**Example Response:**

```json
{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "quarter": "FY",
  "matches": [
    {
      "block_index": 1,
      "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS",
      "statement_type": ["Income Statement"],
      "matched_via": {
        "source": "statement_type",
        "query": "Income Statement",
        "matched_statement_type": "Income Statement"
      },
      "block": { "elements": [ "... truncated ..." ] }
    }
  ],
  "credits_used": 28
}
```