> 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 a policy-authorized job; direct secret values are forbidden. Mount item schemas, included here for MCP clients that do not expand JSON Schema references: - storage\_volumes: {storage, container\_path, read\_only=false} - disk\_volumes: {disk, container\_path, read\_only=false} - secret\_files: {secret, container\_path} storage and disk accept short references or exact same-context URIs. secret must be a secret: reference. secret\_env maps an environment variable name to a secret: reference; env accepts non-sensitive literal values only.
**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": {
"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"
}
```
## `exec_job`
Execute one non-interactive command in an owned running job. The executable and argument list are shell-quoted separately; no stdin or TTY is exposed. Output is duration/byte bounded and credential-redacted. Use mounted secrets or secret environment references instead of command arguments for credentials.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"arguments": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Arguments"
},
"cluster": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Cluster"
},
"executable": {
"title": "Executable",
"type": "string"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"max_output_bytes": {
"default": 100000,
"title": "Max Output Bytes",
"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": 60,
"title": "Timeout Seconds",
"type": "number"
}
},
"required": [
"job_id",
"executable"
],
"title": "exec_jobArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "exec_jobDictOutput",
"type": "object"
}
```
## `start_job_port_forward`
Start a loopback-only background forward to one running owned job. Forwarded bytes never enter MCP results. The listener remains active until stop\_job\_port\_forward is called or the MCP server exits.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Cluster"
},
"job_id": {
"title": "Job Id",
"type": "string"
},
"local_port": {
"title": "Local Port",
"type": "integer"
},
"org": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Org"
},
"project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Project"
},
"remote_port": {
"title": "Remote Port",
"type": "integer"
}
},
"required": [
"job_id",
"local_port",
"remote_port"
],
"title": "start_job_port_forwardArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "start_job_port_forwardDictOutput",
"type": "object"
}
```
## `list_job_port_forwards`
List active forwards owned by this MCP process and exact 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"
},
"org": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Org"
},
"project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Project"
}
},
"title": "list_job_port_forwardsArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "list_job_port_forwardsDictOutput",
"type": "object"
}
```
## `stop_job_port_forward`
Stop one exact background forward owned by this MCP process.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"cluster": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Cluster"
},
"forwarding_id": {
"title": "Forwarding Id",
"type": "string"
},
"org": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Org"
},
"project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Project"
}
},
"required": [
"forwarding_id"
],
"title": "stop_job_port_forwardArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "stop_job_port_forwardDictOutput",
"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 under full or owned managed 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"
},
"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 signal under full or owned managed policy.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, 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": "send_job_signalArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "send_job_signalDictOutput",
"type": "object"
}
```
## `save_job_image`
Save an owned job filesystem to a policy-authorized image target.
**Operation type:** Write
**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`
**Input schema:**
```json
{
"properties": {
"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 under full or owned managed policy.
**Operation type:** Destructive write
**Annotations:** read-only `false`, destructive `true`, 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": "kill_jobArguments",
"type": "object"
}
```
**Output schema:**
```json
{
"additionalProperties": true,
"title": "kill_jobDictOutput",
"type": "object"
}
```