Job State Management

Use the following endpoint to change a job's state:

PATCH /api/pipelines/{pipeline_id}/components/{step_id}/jobs/{job_id}/state/{job_state}

Where

pipeline_id,step_id The pipeline and component ids of the pipeline that will execute the job
job_id The id of the job being updated.

Use these state values: not_ready, ready, scheduled, running, succeeded, failed, disabled, cancelled, and deleted.

State values are case-insensitive; not_ready and NotReady are equivalent. Repeating a request for the job's current state succeeds without changing it.

State Definitions

State	Meaning
`not_ready`	The job is retained but not eligible to run. Use while a job needs review, configuration, or a deliberate pause before scheduling.
`ready`	The job is enabled and waiting for its next execution to be arranged.
`scheduled`	The job has an upcoming execution time.
`running`	An execution is currently in progress.
`succeeded`	A one-time job completed successfully. Periodic jobs normally schedule their next run instead of entering this state.
`failed`	A one-time job completed unsuccessfully. Periodic jobs normally schedule their next run instead of entering this state.
`disabled`	A recurring job is deliberately disabled and will not run again unless re-enabled.
`cancelled`	The job has been stopped. It will not be scheduled again.
`deleted`	The job has been removed from the active lifecycle. This is a terminal state.

The normal system-managed lifecycle is:

One-time: ready -> scheduled -> running -> succeeded or failed
Periodic: ready -> scheduled -> running -> scheduled for the next run

"OneTime" Job States

Current state	States you can request
`not_ready`	`ready`, `cancelled`
`ready`	`not_ready`, `cancelled`
`scheduled`	`not_ready`, `cancelled`
`running`	`cancelled`
`succeeded`	`ready`, `deleted`
`failed`	`ready`, `deleted`
`disabled`	`ready`, `deleted`
`cancelled`	None
`deleted`	None

Notes:

disabled is not a state that can be requested for a one-time job, though an existing disabled one-time job can be re-enabled or deleted.
Re-requesting ready after succeeded or failed allows the job to run again.
Cancelling a running job will not interrupt work already in progress. No new work will be scheduled, and the job will terminate once all in-flight work has completed.

"Periodic" Job States

This applies to Periodic and the other recurring job types.

Current state	States you can request
`not_ready`	`ready`, `disabled`, `cancelled`
`ready`	`not_ready`, `disabled`, `cancelled`
`scheduled`	`not_ready`, `disabled`, `cancelled`
`running`	`not_ready`, `disabled`, `cancelled`
`succeeded`	`ready`, `deleted`
`failed`	`ready`, `deleted`
`disabled`	`ready`, `deleted`
`cancelled`	None
`deleted`	None

Notes:

Use disabled for a reversible pause of a recurring job.
Use not_ready to take a job out of service before re-enabling it with ready.
cancelled and deleted are terminal through this state-change endpoint.
A periodic job normally returns to scheduled after an execution, ready for its next run.