# Retrieve a Spark Images batch

`GET /v1/images/{image_id}/spark/images/{batch_id}`

Returns the current state of a Spark Images batch. Poll until `status`
moves from `processing` to `completed` or `failed`.

`data` is empty until `status` is `completed`. The batch only completes
once every prompt is terminal and Spark Cull has resolved every child
image; while cull is settling it stays `processing` with empty `data`.
Once `completed`, `data` holds the visible children only — each with a
short-lived pre-signed download URL that a fresh request refreshes.
A batch that has been non-terminal for longer than the 5-minute timeout
is reported as `failed` here even when the database rows still read as
in-flight.

## Responses

### 200 — Spark Images batch state

**application/json**

- **object** — A Spark Images batch result. `data` stays empty until `status` is
`completed`: the batch only completes once every prompt is terminal and
Spark Cull has resolved every child image. While cull is still settling
the batch reads as `processing` with empty `data`, so pending-review or
rejected siblings never leak — only the visible children are returned.

  - `batch_id` (string, required)
  - `image_id` (string, required) — Root image the batch was requested for.
  - `status` (enum: "processing" | "failed" | "completed", required) — Lifecycle status of a Spark request, shared by Spark Ideas and Spark
Images.

- `processing` — non-terminal; the request is queued or running.
- `completed` — terminal success; the response payload is populated.
- `failed` — terminal failure. Also reported for a request that stayed
  non-terminal past the 5-minute processing timeout, even when the
  underlying record still reads as in-flight, so a stuck request is
  always observable here.

  - `data` (array<object>, required) — Visible generated child images, each with a short-lived pre-signed
download URL. Empty unless `status` is `completed`; rejected siblings
are filtered out.

    - items:
      - **object**
        - `image_id` (string, required) — Identifier of the generated child image.
        - `url` (string, required) — Short-lived pre-signed URL to download the image. Re-fetch the batch
to obtain a fresh URL once it expires.

        - `url_expires_at` (string, required) — When `url` stops working. Re-fetch the batch for a fresh URL.
  - `created_at` (string, required)
  - `updated_at` (string, required)

### 401 — Missing or invalid Bearer token

### 404 — Check `error_code` to distinguish:
  - IMAGE_NOT_FOUND — the image does not exist in the caller's organization
  - BATCH_NOT_FOUND — the batch does not exist or is not linked to this image


**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)