Job Monitoring and Result Downloads

Jobs are pipeline executions. They move through queue, reservation, runtime, terminal status, and optional runtime log archive states.

List jobs

Use GET /v1/jobs to show the job queue and history currently visible to the signed-in user. Jobs are organization-owned. The API applies final JobsView=Allow together with the Job's current cluster and location visibility before sorting and pagination; organization membership by itself does not make a Job visible.

GET /v1/jobs?status=queued&sortBy=createdAt&sortDir=desc
Authorization: Bearer <personal-access-token>

Useful filters:

• status: queued, reserved, running, succeeded, failed, cancelled, or expired.
• ownerType and ownerId: restrict to one organization. ownerType=user is unsupported.
• locationId: show work for one spatial location.
• inputBundleId: show jobs started from one uploaded bundle.
• outputBundleId: find the job that produced a generated bundle.
• pipeline: filter by pipeline id.
• search: match pipeline metadata, capability class, and failure details.

The response includes the pipeline, user-facing pipelineDisplayName, current status, resource requirements, timestamps, and outputBundleId when a successful job created a model bundle.

Queued jobs can also include:

• queueReason: a stable short code for why the job is still waiting.
• retryState: short retry context when a previous attempt had to be retried.
• pendingCapacityState: capacity-wait context when no currently available worker can run the job yet.
• statusMessage: a user-safe sentence such as waiting for a larger GPU, more memory, or more worker data space.

These fields are intended for frontend queue views. They do not expose internal worker names or backend execution technology.

Get one job

GET /v1/jobs/{jobId}
Authorization: Bearer <personal-access-token>

Use this endpoint for detail panes and polling. For active terminal UX, combine it with the event endpoints.

Job detail requires the same final tier-capped JobsView=Allow and spatial visibility as the list. A hidden or unknown identifier returns an opaque 404 Not Found.

If a job is waiting for local or no-burst capacity, keep polling the job detail or list endpoint and display statusMessage. The job remains queued until matching capacity appears, a worker starts it, or the job is cancelled. Cloud-provider capacity failures can still surface as terminal failures when provisioning was allowed but could not be satisfied.

Stream runtime events

GET /v1/jobs/{jobId}/events
GET /v1/jobs/{jobId}/events/stream

events returns recent history. events/stream uses server-sent events and emits log entries as workers report progress. Both routes re-evaluate JobsView and the Job's current resource visibility on every request. Losing cluster/location access or moving to a tier where Job view is unavailable removes detail, event, and archive access without deleting the Job.

Download archived logs

GET /v1/jobs/{jobId}/archive

When runtime log archiving is available for the job, the response contains a temporary download URL. If the archive is not available, the response still returns available: false and may include a short summary.

Retry and delete queued jobs

POST /v1/jobs/{jobId}/retry
DELETE /v1/jobs/{jobId}
Authorization: Bearer <personal-access-token>

Retry and queued deletion require final tier-capped JobsManage=Allow in the Job's current cluster/location context. Neither action grants Job read access: retry returns 202 Accepted without a Job body, and deletion returns 204 No Content. Retrying resets the same logical Job to the current pipeline resource configuration. It does not create another Job or consume another monthly or organization-lifetime admission slot. Failure, cancellation, and deletion never refund either accepted-Job limit.

During output finalization, failureReason can temporarily be authorization_changed or capacity_changed while the Job and active attempt remain retryable. No output Bundle is visible in either state. Restoring every current permission and capacity prerequisite lets the worker retry the same full output set without creating another logical usage charge.

Cancel a known job

POST /v1/jobs/{jobId}/cancel
Authorization: Bearer <personal-access-token>
Content-Type: application/json

{
  "reason": "No longer needed"
}

Cancellation is deliberately narrower than Job management. An already accepted known queued or active Job can be cancelled by a caller with underlying JobsCancel, by its persisted requester, by a protected organization owner, or by platform authority. This exact-target cleanup remains available when a tier disables Job product visibility, but it returns only 204 No Content and grants no list/detail/event/archive/result/artifact, input/output, retry, delete, or other management access. Unknown and unauthorized identifiers use the same opaque 404 Not Found response. The optional reason is limited to 1,000 characters.

Outputs

Successful pipeline jobs create a generated artifact bundle. Use the returned outputBundleId with the bundle metadata, file listing, and download endpoints to display or fetch the result. JobsView does not grant Bundle access: every result metadata, file-list, content, ZIP, range-download, and presigned-download request independently requires current final LocationBundles=Read plus the same cluster/location visibility. A caller allowed only to cancel the Job cannot read its input or output Bundle.