Job run execution, monitoring, and lifecycle.
/me/jobs/runsList my job runs
Returns all job runs that the authenticated user can access based on their team memberships and role permissions.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100markerstring
The pagination token returned from the previous list operation.
Responses
Responses
The list of job runs accessible by the current user is returned.
/workloads/jobs/{job}/runsList job runs
Returns a paginated list of runs for a specific job, ordered by creation time. Includes status, timing, and trigger information for each run.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100markerstring
The pagination token returned from the previous list operation.
Responses
Responses
The list of LakeSail job runs is returned.
/workloads/jobs/{job}/runsCreate a job run
Triggers a new execution of the job using its currently active version configuration. The run is placed in a pending state until released or automatically dispatched by the scheduler. Send an Idempotency-Key header to make a retry of this request return the same run instead of a second one. A continuous job starts its own runs, so it refuses this with 400, as does a request for a continuous version: resume the job to start its run, or restart a live one with RestartJobRun.
Parameters
jobrequired
A LakeSail job ID.
Idempotency-Keystring
A key the caller chooses to make a retried request safe. The first request with a
key creates the run. A later request from the same member with the same key for
the same job creates nothing and returns that run with status 200, so a caller
that lost the response can send the request again. The request must match the
first one; a different request with a used key, or any request from another
member with it, is refused with 409. Keys are kept for the life of the run.
"orchestrator:daily_etl:load:2026-09-19T00:00:00+00:00:1"1255Request Body
Responses
Responses
The request repeats an earlier one with the same Idempotency-Key. Nothing was created; this is the run the earlier request created.
/workloads/jobs/{job}/runs/{jobRun}Describe a job run
Returns the full details of a job run, including its current status, timing information, and execution results.
Parameters
jobrequired
A LakeSail job ID.
jobRunrequired
A LakeSail job run ID.
Responses
Responses
The LakeSail job run is returned.
/workloads/jobs/{job}/runs/{jobRun}/cancelCancel a job run
Stops a job run that has not finished. The run moves to cancelled, its
runner is stopped regardless of resourceCleanupMode, its remaining
resources follow that mode, and the job_run.status.cancelled notification
fires.
Cancelling a continuous run also pauses its job, so no new run replaces it, and releases
the compute it kept between versions. Resuming the job starts a new run.
Idempotent: a run that is already in a terminal status (succeeded,
failed, cancelled or timeout) is returned unchanged, so a caller can
cancel on every teardown path without checking first.
A run cancelled while its resources are still being created finishes
cleaning them up shortly after the response.
Stopping is not instant: the job code can keep executing for up to about half
a minute. cancelled means the run was stopped and its compute released, not
that the code had no effect. If the code finishes in that window the run stays
cancelled, with its runner timings and results recorded.
Responses
Responses
The job run. Its status is cancelled, or the terminal status it already had when the request arrived.
/workloads/jobs/{job}/runs/{jobRun}/retentionSet how long a job run's resources are retained
A run whose resourceCleanupMode retains its resources keeps its Sail server
and namespace after it ends, for debugging. The Sail server keeps running
while they are retained, and that compute is billed.
Sets retainedUntil to the given time, earlier or later than the current one.
It must be in the future and no later than the run's retainedUntilMax. To
end the retention now, use EndJobRunRetention.
Refused with 409 while the run is still executing, when it retains
nothing, and once its retention has ended. Refused with 400 when retainedUntil is in the past or past the
maximum.
Request Body
Responses
Responses
The job run, carrying the new retainedUntil.
/workloads/jobs/{job}/runs/{jobRun}/retentionEnd a job run's retention now
Ends the retention of a run whose resourceCleanupMode retained its
resources: its Sail server and namespace are cleaned up now, logs included,
and the run stays on record. Removal is not instant: cleanedAt is set once
they are gone.
Refused with 409 while the run is still executing, and when it retains
nothing.
Responses
Responses
The requested operation was done successfully.
/workloads/jobs/{job}/runs/{jobRun}/readyRelease a pending job run for execution
Transitions a job run from pending to ready, making it eligible for execution.
Use this when orchestrating job runs that were created in pending status and
should be released once their dependencies are satisfied.
Returns 409 if the run is not in pending status or its compute profile has
an external data target operation in progress.
Responses
Responses
The job run has been released and is now in ready status.
/workloads/jobs/{job}/runs/{jobRun}/retryRetry a job run
Resets a terminal job run so it can be executed again.
The run keeps its original ID, version, parameters, and audit trail.
The run's status must be failed, timeout, or cancelled. By default
the run transitions to ready (immediately eligible for execution).
If hold is true in the request body, the run transitions to pending
instead, requiring a subsequent Release call before execution.
Returns 400 if the run is not in an allowed terminal status or is a continuous
run (resume its job, or restart a live one with RestartJobRun), and 409 if
its compute profile has an external data target operation in progress.
Request Body
Responses
Responses
The job run has been reset. Its status is ready (eligible for execution) or pending (held until released) depending on the hold flag in the request.
/workloads/jobs/{job}/runs/{jobRun}/restartRestart a continuous job run
Restarts the runner of a live continuous run. The run keeps its id and its Sail engine,
and restarts counts the restart with cause requested_by_user. The job's code is
stopped as a cancel stops it, so it can clean up when it catches SailStopRequested,
then starts again from the beginning.
When releaseOutdated is true, the restart also moves the run to the platform's
current runner and Sail engine, which restarts the engine too and loses its session state.
The platform never does this by itself.
Only a continuous run restarts in place, because only its runner outlives the job's code: a
supervisor in a Deployment starts the code again within the same run. A batch run's runner is
a Kubernetes Job whose pod ends with the code, and the Job's completion, timeout and retry budget
decide the run's outcome, so restarting it in place would blur what that outcome means. Returns
400 for a run that is not a live continuous run; to run a batch job's code again, retry a run
that ended with RetryJobRun, or cancel it and create a new one.
Responses
Responses
The job run. The restart happens shortly after the response; restarts counts it once the runner has stopped.
/workloads/jobs/{job}/runs/{jobRun}/results/downloadDownload a job run's results
Returns short-lived URLs that download the files of a succeeded run's results directly from workspace storage; the data does not pass through this API. The results are Parquet files that together form one table. The list is empty when the run wrote no files, for example when its SQL is a command rather than a query, or when the files were deleted from storage.
Parameters
jobrequired
A LakeSail job ID.
jobRunrequired
A LakeSail job run ID.
Responses
Responses
Short-lived URLs that download a job run's results from workspace storage.
/workloads/jobs/{job}/runs/{jobRun}/logs/streamIssue a job run log stream
Issues a short-lived token and URL for streaming the live log of one of the job run's pods, selected by source, from the customer-side session proxy. Available while the run is live and, after it finishes, until the run's resources are cleaned up; once cleaned, the endpoint returns 410. Returns 409 while the selected pod is not yet running (retry shortly) or when the cluster requires re-provisioning for live logs.
Parameters
sourcestring
Which of the run's pods to stream. runner (default) is the job runner that submits the work; engine is the Sail driver that executes it, where engine-side failures such as out-of-memory kills and panics appear.
"runner""engine""runner"Responses
Responses
Connection details for the job run's live log stream.