Workloads

Workloads are compute jobs on Targon. The API uses a register-then-deploy flow:

1. Register — POST /tha/v3/orgs/{org_slug}/workloads saves configuration. State is registered.
2. Deploy — POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/deploy provisions runtime resources.

Updating a running workload (outside registered, suspended, or deleted) triggers an automatic redeploy.

Workload types

RENTAL

Dedicated container deployed via targon-op. Supports volumes, SSH keys, exec, and persistent storage. Maps to inventory type rental.

VM

Virtual machine deployed via the Targon VM master. Requires vm_config.password. Does not support envs, commands, args, registry_auth, or volumes. Maps to inventory type vm.

See the Virtual Machines guide for dashboard workflows and SSH access.

Lifecycle states

Status	Description
registered	Created; awaiting deploy
provisioning	Deploy in progress
running	Healthy / ready
error	Failure
suspended	Suspended; runtime removed (not supported for VM)
deleted	Soft-deleted

Authentication

All workload endpoints are scoped to an organization. Replace {org_slug} with your organization slug.

Authenticate with a personal access token or org service token:

Authorization: Bearer <YOUR_API_TOKEN>

JSON request bodies reject unknown fields.

Pagination: list endpoints accept limit (default 1000) and cursor (UID of the last item from the previous page). Responses include next_cursor.

---

Create Workload

POST /tha/v3/orgs/{org_slug}/workloads

Request body

Field	Type	Description
type	string	Required. RENTAL or VM
name	string	Required. Lowercase alphanumeric and hyphens, max 32 characters
image	string	Required. Container image reference (not validated for VM)
resource_name	string	Required. Inventory resource name (e.g. h200-small)
envs	array	Environment variables. Not for VM
ports	array	Port mappings. See Port object
commands	array	Container command override. Not for VM
args	array	Container arguments. Not for VM
registry_auth	object	Private registry credentials. Not for VM
ssh_keys	array	SSH key UIDs to attach
volumes	array	Volume mounts. RENTAL only
vm_config	object	Required for VM. See VM config
project_id	string	Optional project UID to assign the workload
experiments	object	Feature experiments (config-gated). Keys: reserved-gpu, persistent-workload

Port object

Field	Type	Description
port	integer	Required. 1024–65535
protocol	string	TCP, UDP, or SCTP (VM: TCP / UDP only)
routing	string	PROXIED (default) or DIRECT (max 10 direct ports per workload)

Env object

Field	Type	Description
name	string	Variable name
value	string	Variable value

Registry auth object

Field	Type	Description
server	string	Registry server URL
username	string	Registry username
password	string	Registry password or token

Volume mount object

Field	Type	Description
uid	string	Required. Volume UID
mount_path	string	Required. Absolute path inside the container
read_only	boolean	Mount read-only. Default false

VM config

Field	Type	Description
password	string	Required. Min 4 characters

Example: Rental

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/workloads \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-training-job",
    "image": "pytorch/pytorch:latest",
    "resource_name": "h200-small",
    "type": "RENTAL",
    "ports": [
      {"port": 8080, "protocol": "TCP", "routing": "PROXIED"},
      {"port": 2222, "protocol": "TCP", "routing": "DIRECT"}
    ],
    "volumes": [
      {"uid": "vol-xyz789abc123", "mount_path": "/data"}
    ],
    "ssh_keys": ["shk-def456ghi789"]
  }'

Example: VM

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/workloads \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-confidential-vm",
    "type": "VM",
    "image": "<vm-image-name>",
    "resource_name": "h200-small",
    "ssh_keys": ["shk-def456ghi789"],
    "vm_config": {
      "password": "your-sudo-password"
    }
  }'

List available VM images with GET /tha/v3/orgs/{org_slug}/workloads/vm-images. See the Virtual Machines guide.

Response

Returns WorkloadOperationResponse:

Field	Type	Description
uid	string	Workload UID
type	string	Workload type
name	string	Workload name
image	string	Container image
cost_per_hour	number	Hourly cost (USD)
resource	object	Resource details
revision	string	Current revision
volumes	array	Volume mounts
state	object	Current state
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

resource object: name, display_name, gpu_type, gpu_count, vcpu, memory, disk_size_mib, network_mode.

state object: status, message, urls, public_ip, ssh_port, ready_replicas, total_replicas.

---

List Workloads

GET /tha/v3/orgs/{org_slug}/workloads

Query	Type	Description
limit	integer	Max items
cursor	string	Pagination cursor
type	string	Filter by workload type
status	string	Filter by status
project_id	string	Filter by project UID
name	string	Filter by name

Returns { "items": [...], "next_cursor": "..." }. Each item is a WorkloadOperationResponse.

---

Get Workload

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

Returns the full Workload object, including envs, ports, commands, args, registry_auth, ssh_keys, and experiments.

---

Update Workload

PATCH /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

All fields optional. Supported: name, image, envs, ports, commands, args, registry_auth, ssh_keys, volumes, project_id, experiments. Set project_id to "" to unassign a project.

---

Delete Workload

DELETE /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

Returns 204 No Content. Tears down runtime and soft-deletes the workload.

---

Deploy Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/deploy

Starts provisioning. Returns WorkloadOperationResponse. Checks credits and inventory availability.

---

Suspend Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/suspend

Suspends the workload and removes runtime resources. Not supported for VM.

---

Reboot Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/reboot

Reboots a VM workload.

---

Get Workload State

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/state

Field	Type	Description
uid	string	Workload UID
workload_type	string	Workload type
status	string	Current status
message	string	Status message
urls	array	{ "port", "url" } access URLs
public_ip	string	Public IP (when applicable)
ssh_port	integer	SSH port (when applicable)
ready_replicas	integer	Ready replica count
total_replicas	integer	Total replica count
updated_at	string	ISO 8601 timestamp

---

List Workload Events

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/events

Query: limit, cursor.

Each event: workload_uid, workload_type, resource_name, event_type, pod_name, container_name, container_image, new_status, replica_count, old_replica_count, reason, message, display_message, exit_code, created_at.

---

Get Workload Logs

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/logs

Query	Type	Description
since	string	RFC 3339 timestamp
tail	integer	Number of recent lines
follow	boolean	Stream logs (text/plain)
previous	boolean	Logs from previous container instance
type	string	VM only: serial or qemu

---

Exec Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/exec

RENTAL only. Streams command output as text/plain.

Query: command (repeatable) — e.g. ?command=ls&command=-la.

---

List VM Images

GET /tha/v3/orgs/{org_slug}/workloads/vm-images

Returns available VM images: { "name", "display_name", "description" }.

---

Verify Workload Digest

POST /tha/v3/orgs/{org_slug}/workloads/verify

Body: { "uid": string, "digest": string } (SHA256).

Response: { "verified": boolean }.

---

Attach / Detach Volume

PUT /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/volumes/{volume_uid}

Body: { "mount_path": string, "read_only": boolean }. RENTAL only.

DELETE /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/volumes/{volume_uid} — returns 204.

---

Attach / Detach SSH Key

PUT /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/ssh-keys/{ssh_key_uid} — empty body.

Response: { "workload_uid", "ssh_key_uid" }.

DELETE /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/ssh-keys/{ssh_key_uid} — returns 204.

---

Errors

Errors return JSON: { "error": "message", "reason": "REASON_CODE" }.

Common status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 500 (server error).