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.

BM

Dedicated physical server claimed from Targon Mainframe. Requires region and at least one SSH key. Optional bm_config.hostname and reservation_uid. Does not support envs, ports, commands, args, registry_auth, volumes, or experiments. Maps to inventory type bm.

See the Bare Metal guide for region selection 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, VM, or BM
name	string	Required. Lowercase alphanumeric and hyphens, max 32 characters
image	string	Required. Container image reference (RENTAL), VM image name (VM), or BM image name (BM)
resource_name	string	Required. Inventory resource name (e.g. h200-small)
region	string	Required for BM. Active region UID (lowercase slug, max 32 characters). Not for other types
reservation_uid	string	Bind to an ACTIVE reservation. VM and BM only
envs	array	Environment variables. RENTAL only
ports	array	Port mappings. See Port object. Not for BM
commands	array	Container command override. RENTAL only
args	array	Container arguments. RENTAL only
registry_auth	object	Private registry credentials. RENTAL only
ssh_keys	array	SSH key UIDs to attach. Required for BM
volumes	array	Volume mounts. RENTAL only
vm_config	object	Required for VM. See VM config
bm_config	object	Optional for BM. See BM config
project_id	string	Optional project UID to assign the workload
experiments	object	Feature experiments (config-gated). Keys: reserved-gpu, persistent-workload. Not for BM

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

BM config

Field	Type	Description
hostname	string	RFC 1123 hostname (lowercase letters, digits, hyphens, dots; max 63 characters). Defaults to the workload name

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.

Example: Bare Metal

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-bare-metal",
    "type": "BM",
    "image": "<bm-image-name>",
    "resource_name": "<hardware-class>",
    "region": "us-ord-1",
    "ssh_keys": ["shk-def456ghi789"],
    "bm_config": {
      "hostname": "gpu-node-01"
    }
  }'

List available BM images with GET /tha/v3/orgs/{org_slug}/workloads/bm-images. List regions with GET /tha/v3/region. See the Bare Metal guide.

Response

Returns WorkloadOperationResponse:

Field	Type	Description
uid	string	Workload UID
type	string	Workload type
name	string	Workload name
image	string	Container image
reservation_uid	string	Bound reservation UID (VM / BM, when set)
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. BM workloads also include bm_config (region, hostname) and reservation_uid when bound.

---

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 (region-scoped for BM).

BM deploys are single-attempt: a 409 WORKLOAD_BM_CLAIM_CONFLICT means no capacity matched and nothing was claimed.

---

Suspend Workload

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

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

---

Reboot Workload

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

Reboots a VM workload. Not supported for BM.

---

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" }.

---

List BM Images

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

Returns managed OS images for BM workloads: { "name", "display_name", "os_family" }. Pass name as image when creating a BM workload.

---

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).

BM-specific reason codes:

Reason	Status	Description
WORKLOAD_BM_REGION_REQUIRED	400	region missing
WORKLOAD_BM_REGION_INVALID	400	region is not a lowercase slug ≤ 32 characters
WORKLOAD_BM_SSH_KEYS_REQUIRED	400	No ssh_keys supplied
WORKLOAD_BM_HOSTNAME_INVALID	400	bm_config.hostname is not a valid RFC 1123 hostname
WORKLOAD_BM_REGION_NOT_FOUND	409	region is not an active region
WORKLOAD_BM_RESERVATION_REGION_MISMATCH	409	Reservation is in a different region
WORKLOAD_BM_CLAIM_CONFLICT	409	No bare-metal capacity available for the request
WORKLOAD_BM_TARGET_NOT_FOUND	404	Image, reservation, or matching server not found
WORKLOAD_BM_SERVICE_UNAVAILABLE	503	Bare-metal control plane unavailable