> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motioness.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response headers

Every header the proxy emits — what each one means and when to read it.

# Response headers

Every `/v1/...` response carries a stable set of headers for tracing and player hints.

## Always present

| Header | Description |
|---|---|
| `X-Request-Id` | Echoes incoming `X-Request-Id` if it matches `^[\w-]{4,64}$`, else fresh `req_<8 hex>`. Use in support tickets. |

## On all asset responses

| Header | Description |
|---|---|
| `X-Motioness-Asset-Id` | Content-addressed asset id. Stable across calls with same opts. |
| `X-Motioness-Stage` | `queued`, `vision`, `stage1`, `stage2`, `merge`, or `ready` at response time. |

## On 202 (pending) only

| Header | Description |
|---|---|
| `X-Motioness-Eta-Ms` | Server-estimated remaining time in ms. Static `(model, pipeline)` table for v1.1. |
| `Retry-After` | Seconds (rounded ETA). Standard HTTP. |

## On 200 (ready) only

| Header | Description |
|---|---|
| `X-Motioness-Loop` | `native` (loop_capable model) or `crossfade` (Free tier post-stitch). Hint for the player. |
| `Server-Timing` | Per-stage latency breakdown. `vision;dur=2200, stage1;dur=4820, merge;dur=900`. (Coming in v1.2.) |
| `cache-control` | `public, max-age=31536000, immutable` — content-addressed, never stale |
| `cf-cache-status` | `HIT` if served from edge cache, `MISS` if from R2/D1 |

## On error responses

| Header | Description |
|---|---|
| `X-Request-Id` | Always — quote in support tickets |
| `X-Motioness-Asset-Id` | Set when the error is asset-scoped (502 last-failed, 429 quota) |

## Custom request headers Motioness reads

| Header | Effect |
|---|---|
| `X-Request-Id` | Sets the request id (validated against `^[\w-]{4,64}$`) |
| `Idempotency-Key` | Same as `?idem=…` query param. Forces a distinct asset from the same source. |
| `Last-Event-ID` | SSE reconnect cursor. Sent automatically by browser `EventSource`. |

## CORS

All proxy responses set `Access-Control-Allow-Origin: *`. Proxy URLs work cross-origin in `<video>` and `<img>`.