Skip to content
For Self-Managed AI Platform users running v11.1, see the on-premise platform documentation
Workload API > Operate running Workloads > REST: Operate Workloads

REST: Operate Workloads

For change-event endpoints (promote, replacement history), see REST: update Workloads.

Lifecycle and policy

These endpoints start, stop, delete, and update metadata on a Workload.

Verb Path Description
POST /workloads/{workload_id}/start Start a stopped Workload. Returns 202 with a WorkloadOperationResponse.
POST /workloads/{workload_id}/stop Stop a running Workload (graceful). Returns 202.
DELETE /workloads/{workload_id} Delete a Workload. Returns 204 on clean deletion. Returns 502 with a detail message if the Workload was deleted but one or more protons could not be stopped.
PATCH /workloads/{workload_id} Update name, description, or importance.

Runtime settings

These endpoints read and change runtime settings on a Workload. A PATCH triggers a replacement; the rollout itself is documented under Update Workloads.

Verb Path Description
GET /workloads/{workload_id}/settings Get the current runtime settings (replicas, autoscaling, resources).
PATCH /workloads/{workload_id}/settings Update runtime settings. Triggers a replacement using the strategies in Replace and roll out and returns a Replacement (HTTP 202). Returns 409 if a replacement is already in progress.

Sharing

These endpoints read and update the shared roles attached to a Workload.

Verb Path Description
GET /workloads/{workload_id}/sharedRoles List shared roles on the Workload.
PATCH /workloads/{workload_id}/sharedRoles Replace the shared role list (up to 100 entries). See Sharing and access control for the role enum and recipient identification options.

Protons

These endpoints list protons backing a Workload and inspect per-replica readiness during a replacement.

Verb Path Description
GET /workloads/{workload_id}/protons List protons (active and candidate).
GET /workloads/{workload_id}/protons/{proton_id} Get a specific proton.
GET /workloads/{workload_id}/protons/{proton_id}/statusDetails Per-replica status (pod phase, container statuses, readiness conditions). Returns 204 if no status snapshot is available yet.

These endpoints expose request statistics, lifecycle events, and entities related to a Workload.

Verb Path Description
GET /workloads/{workload_id}/stats Aggregated request statistics for the Workload. Optional query params: protonId, startTime, endTime, responseTimeQuantile (default 0.5), slowRequestsThreshold (default 2000 ms).
GET /workloads/{workload_id}/stats/{metric_name} Time-series for a specific metric (totalRequests, requestsOverN, requestsPerMinute, concurrentRequests, responseTime, totalErrorRate). Optional resolution (default P1D).
DELETE /workloads/{workload_id}/stats Reset Workload statistics, optionally for a protonId and startTime/endTime window.
GET /workloads/{workload_id}/events List lifecycle events (status changes, errors).
GET /workloads/{workload_id}/related List entities related to a Workload (linked artifacts, etc.).
GET /workloads/stats Aggregated statistics across all Workloads accessible to the caller. Same filter parameters as GET /workloads.