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
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/jobs/{job}/job_runs/{job_run}. |
uid | string | jrun_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
job_generation | int64 | The Job generation the run pinned. Output only. |
resolved_image | string | The image digest the run executes. Output only. |
args | string[] | Arguments of this run (the Job's when empty). |
env | map<string, string> | Environment overrides of this run. |
state | JobRunState | The run's lifecycle state. Output only. One of queued, running, succeeded, failed, cancelled, timed_out. |
exit_code | int32 | The last attempt's exit code, once it exited. Output only. |
attempt_count | int32 | Attempts made so far. Output only. |
termination_reason | string | Why the last attempt ended other than by exiting, for example OOMKilled or Evicted. Output only. |
schedule_fire | ScheduleFireRef | Set when a Schedule fire started the run. Output only. |
create_time | timestamp | When the run was accepted. Output only. |
start_time | timestamp | When the first attempt started. Output only. |
end_time | timestamp | When the run closed. Output only. |
usage | JobRunUsage | Metered usage across attempts. Output only. |
message | string | Why the run failed or was refused, when it did. Output only. |
schedule_time | timestamp | Start 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_delay | duration | Start no earlier than this long after the request. |
caller_principal_id | string | Principal authenticated by Access when the run was created; not caller-writable. Output only. |
caller_key_id | string | Access key that created the run; never the key's secret value. Output only. |
job_uid | string | Immutable Job UID captured with the run's generation and spec. Output only. |
job_spec_digest | string | SHA-256 of the frozen base Job spec, before this run's overrides. Output only. |
stop_verified | bool | True 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.
| Method | Call | What it does |
|---|---|---|
POST | 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 | 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. |
GET | get | Gets a job run. |
GET | list | Lists a job's runs, newest first. |
POST | cancel | Cancels a job run: SIGTERM, then SIGKILL after 30s. A closed run fails with INVALID_STATE. |
GET | 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. |
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