Skip to content
Console
On this page

Job runs

A JobRun is one start of a Job: queued until the environment's quota admits it, then one attempt per try until an exit of 0, the retries run…

A JobRun is one start of a Job: queued until the environment's quota admits it, then one attempt per try until an exit of 0, the retries run out, the deadline passes, or it is cancelled.

Service Sylphx Workflows · Resource type workflows.sylphx.com/JobRun · Name pattern orgs/{org}/projects/{project}/envs/{env}/jobs/{job}/job_runs/{job_run} · Shape record

Fields

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/jobs/{job}/job_runs/{job_run}.
uidstringjrun_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
job_generationint64The Job generation the run pinned. Output only.
resolved_imagestringThe image digest the run executes. Output only.
argsstring[]Arguments of this run (the Job's when empty).
envmap<string, string>Environment overrides of this run.
stateJobRunStateThe run's lifecycle state. Output only. One of queued, running, succeeded, failed, cancelled, timed_out.
exit_codeint32The last attempt's exit code, once it exited. Output only.
attempt_countint32Attempts made so far. Output only.
termination_reasonstringWhy the last attempt ended other than by exiting, for example OOMKilled or Evicted. Output only.
schedule_fireScheduleFireRefSet when a Schedule fire started the run. Output only.
create_timetimestampWhen the run was accepted. Output only.
start_timetimestampWhen the first attempt started. Output only.
end_timetimestampWhen the run closed. Output only.
usageJobRunUsageMetered usage across attempts. Output only.
messagestringWhy the run failed or was refused, when it did. Output only.
schedule_timetimestampStart no earlier than this: set it directly, or through start_delay; at most 365 days ahead. A run cancelled before then makes no attempt.
start_delaydurationStart no earlier than this long after the request.
caller_principal_idstringPrincipal authenticated by Access when the run was created; not caller-writable. Output only.
caller_key_idstringAccess key that created the run; never the key's secret value. Output only.
job_uidstringImmutable Job UID captured with the run's generation and spec. Output only.
job_spec_digeststringSHA-256 of the frozen base Job spec, before this run's overrides. Output only.
stop_verifiedboolTrue only after all dispatched or ambiguously dispatched attempts have an observed stop/retirement receipt. Cancellation acceptance is not proof. Output only.

Methods

Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.

MethodCallWhat it does
POSTcreateStarts a run of a Job now. The same Idempotency-Key returns the same run for 24h; a Schedule fire uses {job}:{intended time}. With concurrency forbid, a start while a run is active fails with INVALID_STATE.
POSTcreate_pinnedStarts exactly the pinned Job snapshot under a permanent caller-selected run id. Predecessor servers do not serve this route, so unsupported pins cannot silently start work. Replays return the original immutable run.
GETgetGets a job run.
GETlistLists a job's runs, newest first.
POSTcancelCancels a job run: SIGTERM, then SIGKILL after 30s. A closed run fails with INVALID_STATE.
GETread_logsReads a page of a job run's log lines, oldest first. With wait, an empty page on a running run waits up to that long for new lines, so a client follows the log by passing each next_page_token back.

create

Starts a run of a Job now. The same Idempotency-Key returns the same run for 24h; a Schedule fire uses {job}:{intended time}. With concurrency forbid, a start while a run is active fails with INVALID_STATE.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs · scope workflows:run · effect write · Request, response and examples

create_pinned

Starts exactly the pinned Job snapshot under a permanent caller-selected run id. Predecessor servers do not serve this route, so unsupported pins cannot silently start work. Replays return the original immutable run.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs:createPinned · scope workflows:run · effect write · Request, response and examples

get

Gets a job run.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs/job-run · scope workflows:read · effect read · Request, response and examples

list

Lists a job's runs, newest first.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs · scope workflows:read · effect read · paginated · Request, response and examples

cancel

Cancels a job run: SIGTERM, then SIGKILL after 30s. A closed run fails with INVALID_STATE.

POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs/job-run:cancel · scope workflows:run · effect destructive · Request, response and examples

read_logs

Reads a page of a job run's log lines, oldest first. With wait, an empty page on a running run waits up to that long for new lines, so a client follows the log by passing each next_page_token back.

GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/jobs/job/job_runs/job-run:readLogs · scope workflows:run · effect read · Request, response and examples