Skip to navigation

Run a Machine

View as Markdown

Starts a run of a saved Machine. Creates a job: the run id is the job id. An unknown Machine or version gives 404 not_found and no job. Too many active runs give 429 concurrency_limited. When the run waits for your system, the job is needs_input: read the run for its required_action. Needs the scope machines. With no preference, the API holds the request up to 30 seconds.

Authentication

AuthorizationBearer

An API key (crk_), an exchanged token (crt_) or a JWT of a trusted issuer. The credential needs the scope of the capability. Read the description of each route.

Path parameters

namestringRequired

The Machine name: lowercase letters, digits and hyphens.

Headers

PreferstringOptional

wait=N (1 to 90) holds the request up to N seconds. respond-async answers 202 at once. Behind a proxy with a 60 second idle timeout, use wait=55 or less.

Idempotency-KeystringOptional<=255 characters

A key that makes a retry safe, valid for 24 hours. The same key with another body gives 409 idempotency_key_reused.

Query parameters

waitintegerOptional1-90

The alias of Prefer: wait=N. The Prefer header wins when both are there.

Request

This endpoint expects an object.
versionintegerOptional1-9007199254740991

The version to run. Default: the published version.

inputsmap from strings to anyOptional

The inputs of the procedure, by name. A file input is {url, name?} or {id} of a stored file.

optionsobjectOptional
The options of a run.
notifyobjectOptional

Where the API sends the webhook of the job. Each delivery has an x-cr-signature header: a JWT that you verify with the JWKS of the tenant.

deadline"asap"Optional

Only asap. Other values give 400 deadline_not_supported.

metadatamap from strings to anyOptional
A JSON object of at most 10 KB. The API checks it and does not store it.

Response headers

x-request-idstringOptional

The id of the request: req_ and a ULID. Every answer has it.

server-timingstringOptional
The time of the admission.
x-ratelimit-limit-requestsstringOptional
The size of the request bucket, per minute.
x-ratelimit-remaining-requestsstringOptional
The requests that remain.
x-ratelimit-reset-requestsstringOptional
The time until the request bucket is full.
x-ratelimit-limit-unitsstringOptional
The size of the units bucket, per minute. Absent when no limit applies.
x-ratelimit-remaining-unitsstringOptional
The units that remain.
x-ratelimit-reset-unitsstringOptional
The time until the units bucket is full.
preference-appliedstringOptional
The preferences that the API applied.
idempotent-replayedstringOptional

true when the answer replays an earlier request with the same key.

Response

The job ended. A failed job also answers 200. Accept: text/event-stream streams the events of the job as server-sent events: job.progress, job.needs_input, job.succeeded, job.failed, job.cancelled, job.expired. A terminal event carries the job and ends the stream.

object"job"
idstring

job_ and a ULID.

capabilitystring
The capability of the job.
statusenum
The status of the job.
deadline"asap"

Only asap at this time.

created_atdatetime
When the API accepted the job.
completed_atdatetime or null
When the job ended. Null while the job runs.
outputany
The output of a succeeded job, or null. The shape depends on the capability. The stored output is at most 1048576 bytes.
errorobject or null
Why a job did not succeed.
usageobject or null
The metered use of a job.
run_idstringOptional
The Run run id. Agent jobs only.
required_actionobject or nullOptional

Machine jobs only. What the job waits for while its status is needs_input, else null. The other jobs do not have this field.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error