> For the complete documentation index, see [llms.txt](https://docs.apolo.us/index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apolo.us/index/apolo-mcp/capabilities/tools/jobs.md).

# Jobs

[Back to the MCP tool reference](/index/apolo-mcp/capabilities/tools.md).

## `run_job`

Start an approved job; direct secret values are forbidden.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "$defs": {
    "DiskVolumeInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "disk": {
          "description": "Disk URI/reference",
          "title": "Disk",
          "type": "string"
        },
        "read_only": {
          "default": false,
          "title": "Read Only",
          "type": "boolean"
        }
      },
      "required": [
        "disk",
        "container_path"
      ],
      "title": "DiskVolumeInput",
      "type": "object"
    },
    "SecretFileInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "secret": {
          "description": "secret: reference only; never a secret value",
          "title": "Secret",
          "type": "string"
        }
      },
      "required": [
        "secret",
        "container_path"
      ],
      "title": "SecretFileInput",
      "type": "object"
    },
    "StorageVolumeInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "read_only": {
          "default": false,
          "title": "Read Only",
          "type": "boolean"
        },
        "storage": {
          "description": "Storage URI/reference, never a credential",
          "title": "Storage",
          "type": "string"
        }
      },
      "required": [
        "storage",
        "container_path"
      ],
      "title": "StorageVolumeInput",
      "type": "object"
    }
  },
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "command": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Command"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "disk_volumes": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DiskVolumeInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Disk Volumes"
    },
    "energy_schedule": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Energy Schedule"
    },
    "entrypoint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entrypoint"
    },
    "env": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Env"
    },
    "http_auth": {
      "default": true,
      "title": "Http Auth",
      "type": "boolean"
    },
    "http_port": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Http Port"
    },
    "image": {
      "title": "Image",
      "type": "string"
    },
    "life_span_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Life Span Seconds"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "preset": {
      "title": "Preset",
      "type": "string"
    },
    "priority": {
      "anyOf": [
        {
          "enum": [
            "low",
            "normal",
            "high"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Priority"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "restart_policy": {
      "default": "never",
      "enum": [
        "never",
        "on-failure",
        "always"
      ],
      "title": "Restart Policy",
      "type": "string"
    },
    "schedule_timeout_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Schedule Timeout Seconds"
    },
    "scheduler_enabled": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scheduler Enabled"
    },
    "secret_env": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Secret Env"
    },
    "secret_files": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/SecretFileInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Secret Files"
    },
    "storage_volumes": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/StorageVolumeInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Storage Volumes"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "wait_for_jobs_quota": {
      "default": false,
      "title": "Wait For Jobs Quota",
      "type": "boolean"
    },
    "workdir": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workdir"
    }
  },
  "required": [
    "image",
    "preset"
  ],
  "title": "run_jobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "run_jobDictOutput",
  "type": "object"
}
```

## `list_jobs`

List jobs using context and bounded status/name/tag/owner/time filters.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "limit": {
      "default": 20,
      "title": "Limit",
      "type": "integer"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "owners": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Owners"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    },
    "statuses": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Statuses"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "until": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Until"
    }
  },
  "title": "list_jobsArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "list_jobsDictOutput",
  "type": "object"
}
```

## `get_job`

Get one job and its resolved context.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_jobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "get_jobDictOutput",
  "type": "object"
}
```

## `wait_for_job`

Poll until terminal state, always bounded by timeout\_seconds.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "poll_interval_seconds": {
      "default": 2,
      "title": "Poll Interval Seconds",
      "type": "number"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 300,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "wait_for_jobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "wait_for_jobDictOutput",
  "type": "object"
}
```

## `get_job_logs`

Read a bounded log prefix with explicit timeout and truncation metadata.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "max_bytes": {
      "default": 32768,
      "title": "Max Bytes",
      "type": "integer"
    },
    "max_lines": {
      "default": 1000,
      "title": "Max Lines",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 30,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_job_logsArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "get_job_logsDictOutput",
  "type": "object"
}
```

## `get_job_telemetry`

Collect a bounded telemetry summary and optionally bounded raw samples.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "include_raw": {
      "default": false,
      "title": "Include Raw",
      "type": "boolean"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "max_samples": {
      "default": 10,
      "title": "Max Samples",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 10,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_job_telemetryArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "get_job_telemetryDictOutput",
  "type": "object"
}
```

## `bump_job_life_span`

Extend a job lifespan; requires enabled high-risk server policy.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "additional_seconds": {
      "title": "Additional Seconds",
      "type": "number"
    },
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id",
    "additional_seconds"
  ],
  "title": "bump_job_life_spanArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "bump_job_life_spanDictOutput",
  "type": "object"
}
```

## `send_job_signal`

Send the SDK's graceful job signal; requires high-risk policy.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "send_job_signalArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "send_job_signalDictOutput",
  "type": "object"
}
```

## `save_job_image`

Save a job filesystem as an image; requires high-risk policy.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "image": {
      "title": "Image",
      "type": "string"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id",
    "image"
  ],
  "title": "save_job_imageArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "save_job_imageDictOutput",
  "type": "object"
}
```

## `kill_job`

Kill a job (destructive); requires enabled high-risk server policy.

**Operation type:** destructive

**Annotations:** read-only `false`, destructive `true`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "kill_jobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "kill_jobDictOutput",
  "type": "object"
}
```