Skip to main content

Track progress

Poll GET /v1/jobs/{job_id}?include_result=true every 30–60 seconds. Save the job ID returned at acceptance. Stop polling when job.status is succeeded, failed, or cancelled. Inspect job.error on failure. For batches, poll the batch and paginate its items rather than polling every job.

Cancel a job

Cancellation requests stop unfinished work; running workers may take time to stop. Poll until terminal. Completed work is not undone. Use the batch cancellation endpoint to stop a whole batch’s unfinished items.

Retry generation safely

Give each intended generation a unique Idempotency-Key (1–128 ASCII letters, digits, dots, underscores, colons or hyphens):
Retry a lost response with the same key and same JSON body. Once accepted, retries return the original job, with Idempotency-Replayed: true. A different body with the same key returns 409 idempotency_key_reused for Personal keys or 409 idempotency_conflict for Team keys. For Personal requests, concurrent or interrupted acceptance returns 409 request_in_progress with Retry-After: 5; retry the same key. If that persists, contact support with X-Request-ID rather than creating a new key and risking a duplicate job. Keys are scoped to your account and do not expire. A request that was rejected with a 4xx error is replayed with the same error, so use a new key after fixing the request. Personal requests without a key create a new job every time; Team requests without a key are rejected. The 202 response includes Location: /v1/jobs/{id} and Retry-After: 30.

Completion notifications

Generation continues on the server when your client disconnects. Save the job_id to check the result later; you do not need to keep sending requests to keep generation running. Poll every 30–60 seconds, or with a Personal key, keep one SSE connection open for progress and completion. The API does not send webhooks, and any emails are a courtesy; drive your integration from the job status or the SSE done event.

Streaming progress

Personal keys only. Server-sent events (SSE) stream progress over one HTTP response and end with a done event, so you do not need to poll. Team keys should poll.
Progress events include a sequence number. Reconnect with ?after=LAST_SEQUENCE to receive later events. Progress event types can vary; ignore types your client does not recognize. ping is a keepalive. done includes the terminal status and job_id, and closes the stream. Fetch the job with include_result=true to retrieve the asset after success.

Retry export without regeneration

Team keys only. If an asset was built but only its export failed, regenerating returns 409 export_retry_required. Recover the export from the saved build instead:
The response is 202 with a new job_id. Poll it and use its asset ID for downloads; the original job stays unchanged. This reuses the saved geometry, physics, joints and materials and does not run generation again. It is not a geometry repair. The Team’s normal pricing applies.

Endpoint reference

Job status · Cancel a job · Retry export