# `POST /data/filings/excel`

**Purpose:** Obtain a download URL for the filing's Excel file, valid for one hour.

**Filing selection:** supply **`filing_id`**, or **`ticker`** and **`fiscal_year`** with optional **`form_type`** (default **`10-K`**) and **`quarter`**. Giving both, or `form_type` or `quarter` with `filing_id`, returns 422.

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `filing_id` | integer | Conditional | 1–10⁹. |
| `ticker` | string | Conditional | Required if `filing_id` omitted. 1–32 characters. |
| `form_type` | string | No | Default `10-K`, max 32. |
| `fiscal_year` | integer | Conditional | Required if `filing_id` omitted. 1990–2100. |
| `quarter` | string | No | Max 4 characters. |

**Response:**

| Field | Meaning |
|-------|---------|
| `ticker`, `fiscal_year` | Filing identity. |
| `download_url` | The URL to download the Excel file. |
| `expires_in` | Seconds the URL stays valid (**3600**). |
| `credits_used` | **300**. |

**Credits:** **300**, debited after the filing and its Excel attachment are found; a `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` response is still charged.

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 400 | `DATA_FILING_QUARTER_REQUIRED` | Several filings match without a quarter; message lists available quarters. Not charged. |
| 404 | `DATA_FILING_NOT_FOUND` | No filing for the given id or identity. Not charged. |
| 403 | `PLAN_TIER_INSUFFICIENT_HISTORY`, `PLAN_TIER_INSUFFICIENT`, `PLAN_TIER_INSUFFICIENT_COVERAGE` | The filing is outside your plan. Not charged. |
| 404 | `DATA_EXCEL_NOT_AVAILABLE_FOR_FILING` | The filing has no Excel attachment. Not charged. |
| 503 | `DATA_EXCEL_PUBLIC_URL_UNAVAILABLE` | A download URL cannot be provided right now. Not charged. |
| 404 | `DATA_EXCEL_OBJECT_NOT_IN_STORAGE` | The Excel file is not available. **Charged 300.** |
| 402 | `CREDITS_INSUFFICIENT` | Insufficient credits. |
| 422 | — | Validation (filing selector, limits). |

**Example Request:**

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

**Example Response:**

```json
{
  "ticker": "AAPL",
  "fiscal_year": 2024,
  "download_url": "https://api.akkrudata.ai/...",
  "expires_in": 3600,
  "credits_used": 300
}
```