# `POST /data/filings`

**Purpose:** List filings available for one company and one fiscal year, optionally filtered by form type and quarter.

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `ticker` | string | Yes | 1–32 characters; matched case-insensitively. |
| `fiscal_year` | integer | Yes | 1990–2100. |
| `form_type` | string | No | Max 32 characters. US forms: `10-K`, `10-Q`. Foreign-issuer annual reports: `20-F` (US-listed foreign companies), `40-F` (Canadian filers). Korean (DART), Japanese (EDINET), European (ESEF) and China A-share filings use the same values — `10-K` for the annual report, `10-Q` for the quarterly report. If omitted, all forms for that ticker and year are considered. |
| `quarter` | string | No | Max 4 characters (e.g. `Q1`). Only filings of this quarter. |
| `detail` | string | No | Default `"full"`. `"light"` leaves out the `fiscal_year`, `form_type` and `quarter` echoes. See [Response detail](/documents/responses.md#response-detail). |

**Response:**

| Field | Meaning |
|-------|---------|
| `credits_used` | Always **10** when successful. |
| `fiscal_year` | Echo of request. |
| `form_type` | Present only if you sent `form_type`. |
| `quarter` | Present only if you sent `quarter`. |
| `company` | Company profile (`ticker`, `jurisdiction`, `legal_name` and the identifier that applies: `cik`, `dart_corp_code`, `edinet_code`, `lei` or `uscc`), or `null` if unknown. |
| `filings` | Array of filings: `id`, `ticker`, `registrant_cik`, `registrant_name` (the filing's registrant; `null` when absent), `form_type`, `fiscal_year`, `quarter`, `total_facts`, `total_blocks`, `has_excel`, `caveat` (see [Filing caveats](/documents/responses.md#filing-caveats)). |

Optional **`amendment_context`** (`{summary}`, an English summary) appears on a filing item when an amendment was merged into it.

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope. **Still debits 10 credits.** |
| 402 | `CREDITS_INSUFFICIENT` | Not enough credits. |
| 422 | — | Validation (body rules). |

**Example Request:**

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

**Example Response:**

```json
{
  "credits_used": 10,
  "fiscal_year": 2024,
  "company": {
    "ticker": "AAPL",
    "cik": "0000320193",
    "legal_name": "Apple Inc."
  },
  "filings": [
    {
      "id": 12345,
      "ticker": "AAPL",
      "registrant_cik": "0000320193",
      "registrant_name": "Apple Inc.",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "quarter": "FY",
      "total_facts": 1500,
      "total_blocks": 12,
      "has_excel": true
    }
  ]
}
```