Skip to main content
GET
Retrieve an image generation's status and results
Retrieve the status of a generation job. While it is pending or processing, keep polling; once completed, the response carries the produced images, each with a presigned url valid for 24 hours — download the assets before they expire. Only jobs your organization created are visible; any other id returns 404 not_found.

Compliance blocks

Every raster output passes Samsa’s compliance pipeline (C2PA signing and watermarking — see Content provenance) before the API delivers it. processing means the outputs are still on their way — keep polling. When an output permanently fails that pipeline, the job reports it: Each blocked_images entry is { "id", "reason" }. reason is compliance_failed_signing (C2PA signing failed), compliance_failed_storage, compliance_failed_watermark, or missing_provenance_state. A blocked output never becomes downloadable, so failed is terminal — stop polling.
Example: all outputs blocked
credits_used is unchanged by a compliance block. The same fields and rules apply to Magic Edit, img2img, variations, and resize jobs, and to the MCP get_job_status tool.
Prefer push over polling? Pass a webhook_url on the original generation request to receive a signed callback the moment the job reaches a terminal status. See Webhooks.

Authorizations

Authorization
string
header
required

Organization API key (Authorization: Bearer samsa_sk_...) or OAuth 2.1 access token (Authorization: Bearer samsa_at_...).

Path Parameters

generation_id
string<uuid>
required

Response

Successful Response

GET /images/generations/{id} body (ADR §7.2).

created_at is the job's submit time, sourced from the credit ledger — the image_generation_tasks table has no created_at column.

id
string<uuid>
required
status
enum<string>
required

pending, processing, completed, failed, or cancelled. A job whose outputs ALL failed the compliance pipeline (for example C2PA signing) is failed with error starting delivery_blocked_compliance — a terminal state, so stop polling.

Available options:
pending,
processing,
completed,
failed,
cancelled
Example:

"completed"

created_at
string<date-time>
required

When the job was submitted.

credits_used
integer | null

Net credits charged for this job, after any refunds.

Example:

5

images
PublicImageAsset · object[]

Produced images (presigned URLs); empty until completed.

blocked_images
PublicBlockedImage · object[]

Produced images that are permanently withheld because they failed the compliance pipeline, each with its compliance code. Empty unless a completed job delivered only some of its outputs, or a failed job was blocked by compliance.

error
string | null

Failure detail when status is failed; otherwise null. A compliance block reads delivery_blocked_compliance: <codes>, where <codes> are the blocked_images reasons.

Example:

"delivery_blocked_compliance: compliance_failed_signing"