# Retrieve a Spark Idea

`GET /v1/images/{image_id}/spark/ideas/{idea_id}`

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

`data` carries the suggestion markdown only when `status` is
`completed`. Ideas that have been non-terminal for longer than the
5-minute timeout are reported as `failed` here even when the
database row still reads as `processing`.

## Responses

### 200 — Spark Idea state

**application/json**

- **object** — A Spark Idea result. `data` carries the suggestion markdown only once
`status` is `completed`; in every other state it is `null` so internal
pipeline details never leak.

  - `idea_id` (string, required)
  - `image_id` (string, required) — Root image the Idea was requested for.
  - `pdp_id` (any) — PDP the root image belongs to, if any. `null` when the image is not attached to a PDP.
  - `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` (any) — Markdown body of the suggestion. Populated only when
`status` is `completed`; `null` otherwise.

  - `created_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
  - IDEA_NOT_FOUND — the Idea 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)