# `POST /data/filing-statements`

**Purpose:** Discovery — list every statement block in a filing with its `block_index`, `statement_type` (array of canonical statement-type labels; more than one when the block combines several statements; `null` for non-financial blocks such as the cover page), and `role_label` (filer-specific XBRL string). Use this to find out which `statement_type` / `role_label` / `block_index` values a specific filing exposes before calling **[`POST /data/statement`](/documents/post-datastatement.md)** or the convenience endpoints.

**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 | |

**Response:**

| Field | Meaning |
|-------|---------|
| `ticker`, `form_type`, `fiscal_year`, `quarter` | Filing identity. |
| `statements` | Array of `{block_index, statement_type, role_label}`, ordered by `block_index`. |
| `credits_used` | Always **10** when successful. |

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `DATA_FILING_QUARTER_REQUIRED` | Ambiguous quarterly filings (charged). |
| 404 | `DATA_FILING_NOT_FOUND` | Filing not found. **Still charged 10 credits.** |
| 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 10.** |
| 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. |
| 422 | — | Validation. |

**Example Request:**

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

**Example Response:**

```json
{
  "ticker": "AAPL",
  "form_type": "10-K",
  "fiscal_year": 2024,
  "quarter": "FY",
  "statements": [
    { "block_index": 0, "statement_type": null,                    "role_label": "Cover Page" },
    { "block_index": 1, "statement_type": ["Income Statement"],    "role_label": "CONSOLIDATED STATEMENTS OF OPERATIONS" },
    { "block_index": 2, "statement_type": ["Comprehensive Income"],"role_label": "CONSOLIDATED STATEMENTS OF COMPREHENSIVE INCOME" },
    { "block_index": 3, "statement_type": ["Balance Sheet"],       "role_label": "CONSOLIDATED BALANCE SHEETS" },
    { "block_index": 4, "statement_type": ["Stockholders Equity"], "role_label": "CONSOLIDATED STATEMENTS OF SHAREHOLDERS' EQUITY" },
    { "block_index": 5, "statement_type": ["Cash Flow Statement"], "role_label": "CONSOLIDATED STATEMENTS OF CASH FLOWS" },
    { "block_index": 6, "statement_type": ["Earnings Per Share"],"role_label": "Earnings Per Share - Computation of Basic and Diluted..." }
  ],
  "credits_used": 10
}
```