Update Job Control

PATCH

http://localhost:8080/apis/jobs/v2/workspaces/:workspace/jobs/:name/control

PATCH

/apis/jobs/v2/workspaces/:workspace/jobs/:name/control

curl -X PATCH http://localhost:8080/apis/jobs/v2/workspaces/workspace/jobs/name/control \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "id": "string",
  "attempt_id": "string",
  "name": "string",
  "workspace": "string",
  "source": "string",
  "platform_spec": {
    "steps": [
      {
        "name": "preprocess",
        "executor": {
          "provider": "cpu",
          "container": {
            "image": "string",
            "entrypoint": [
              "string"
            ],
            "command": [
              "string"
            ]
          },
          "profile": "default",
          "resources": {
            "requests": {
              "cpu": "string",
              "memory": "string"
            },
            "limits": {
              "cpu": "string",
              "memory": "string"
            },
            "num_nodes": 1,
            "num_gpus": 1,
            "shm_size": "string"
          }
        },
        "environment": [
          {
            "name": "string",
            "value": "string",
            "from_secret": {
              "name": "string"
            }
          }
        ],
        "config": {},
        "gateway_providers": {},
        "gateway_read_filesets": [
          "string"
        ],
        "lifecycle": {
          "staleness_timeout_seconds": 0,
          "pause_deadline_seconds": 0,
          "ttl_seconds_active": 0
        },
        "network": {
          "ingress": [
            {
              "job_id_label": "string",
              "tcp_ports": [
                1
              ]
            }
          ]
        }
      }
    ],
    "secrets": [
      {
        "name": "string",
        "value": "string",
        "ref_id": "string"
      }
    ]
  },
  "fileset": "string",
  "status": "created",
  "project": "string",
  "description": "string",
  "spec": {},
  "control": {
    "pause_ttl_seconds": 1
  },
  "output_location": "string",
  "status_details": {},
  "error_details": {},
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "ownership": {},
  "custom_fields": {}
}

Change mutable job behavior, such as how long a pause keeps storage.

Path parameters

namestringRequired

workspacestringRequired

Request

This endpoint expects an object.

pause_ttl_secondsinteger or nullOptional>=0

How long this job keeps storage after it pauses, measured from stopped_at. When the job has no value, the platform paused-storage TTL applies. Cannot exceed the platform maximum. 0 reclaims on the next retention pass. In a control update, an omitted or null value keeps the current value. Changing this value does not move the start time.

Response

Successful Response

idstring

attempt_idstring

namestring

workspacestring

Workspace identifier

sourcestring

platform_specobject

Specification for a platform job, containing steps and secrets.

filesetstring

Fileset ID for storing job artifacts

statusenum

Enumeration of possible job statuses.

This enum represents the various states a job can be in during its lifecycle, from creation to a terminal state.

CREATED means the controller has not yet considered the job. QUEUED means the controller has seen the job but not admitted it (waiting for capacity). PENDING means the backend resource exists and is waiting to start.

projectstringOptional

Project URN

descriptionstringOptional

specmap from strings to anyOptional

Job Spec

controlobjectOptional

Mutable job behavior. This is not part of the execution spec.

output_locationstringOptional

Caller-supplied artifact fileset; None when the fileset was auto-created

status_detailsmap from strings to anyOptional

Details about the job status

error_detailsmap from strings to anyOptional

created_atdatetimeOptional

updated_atdatetimeOptional

ownershipmap from strings to anyOptional

custom_fieldsmap from strings to anyOptional

Custom Fields

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error