# `POST /metric/filings`

**Purpose:** List filings for a ticker that have **metrics available**, returning one row per filing with identifiers you use as **`metric_group_id`** on other metric routes.

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `ticker` | string | Yes | 1–32 characters. |
| `fiscal_year` | integer | Conditional | 1990–2100. You must supply **`fiscal_year`** **or** **`as_of_date`** (`YYYY-MM-DD`). |
| `form_types` | array of string | No | Max **8** entries; each max **32** characters. |
| `quarter` | string | No | Max **4** characters. |
| `as_of_date` | string | No | `YYYY-MM-DD`: exclude filings filed after this date. |

**Response:**

| Field | Meaning |
|-------|---------|
| `credits_used` | Always **10** when successful. |
| `fiscal_year` | Echo of request. |
| `as_of_date` | Echo of request. |
| `company` | Company profile (`ticker`, `jurisdiction`, `cik`, `legal_name`) or `null`. |
| `metric_groups` | Array of objects; each includes `metric_group_id`, filing identity fields, dates, reporting currency, and optional amendment flags. |
| `form_types`, `quarter` | Present only if you sent them in the request. |
| `_warnings` | Optional; present when dates exclude all rows. |

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `METRICS_UNSUPPORTED_FOR_KR`, `_JP`, `_EU`, `_CN` | Computed metrics are available for US (SEC) companies; the ticker is a Korean, Japanese, European or China A-share company (not charged). |
| 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The company is outside your plan's coverage scope. **Still debits 10 credits.** |
| 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. |
| 422 | — | Validation (e.g. neither `fiscal_year` nor `as_of_date`). |

**Example Request:**

```json
{
  "ticker": "AAPL",
  "fiscal_year": 2024
}
```

**Example Response:**

```json
{
  "credits_used": 10,
  "fiscal_year": 2024,
  "as_of_date": null,
  "company": {
    "ticker": "AAPL",
    "cik": "0000320193",
    "legal_name": "Apple Inc."
  },
  "metric_groups": [
    {
      "metric_group_id": 9876,
      "ticker": "AAPL",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "quarter": "FY",
      "period_end": "2024-09-28",
      "filing_date": "2024-11-01",
      "reporting_currency": "USD"
    }
  ]
}
```