Skip to main content
A run is an asynchronous canvas-generation task. You submit a prompt, optionally constrain the templates or block types, and poll until the run reaches a terminal state. See Canvases and runs for the conceptual model.

Creating a run

runs.create returns a CreatedRun holding run_id, status (always 'running'), poll_url, and estimated_duration_ms. Passing blocks: [] is rejected client-side with SpineBadRequestError — omit the field entirely to use the template default.

Uploading files

The SDK normalises several shapes so you can mix them freely:
Content types are inferred when you don’t pass one. In a browser you can pass File objects directly. Supported file types and size limits are documented on File uploads.

Waiting for completion

client.runs.waitForCompletion() polls the server until the run reaches a terminal state (completed, partial, or failed), then returns the terminal Run:
By default, a 'failed' terminal state throws SpineRunFailedError. Partial successes return normally — some blocks succeeded, some failed; inspect terminal.errors on the returned object.

Cancellation

Narrowing the result

The returned Run is a discriminated union on status. Narrow before accessing state-specific fields:

Manual polling

If you want full control — custom cadence, streaming progress to a UI, non-standard backoff — call client.runs.retrieve() directly:
See Polling and status for the server-side semantics (typical run durations, recommended intervals).