# REST: Operate Workloads

> REST: Operate Workloads - Lifecycle, settings, sharing, telemetry, and inspection endpoints for
> running Workloads.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-06-22T16:50:38.253814+00:00` (UTC).

## Primary page

- [REST: Operate Workloads](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Lifecycle and policy](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#lifecycle-and-policy): In-page section heading.
- [Runtime settings](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#runtime-settings): In-page section heading.
- [Sharing](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#sharing): In-page section heading.
- [Protons](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#protons): In-page section heading.
- [Statistics, events, and related entities](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/operate-rest-endpoints.html.md#statistics-events-and-related-entities): In-page section heading.

## Related documentation

- [Workload API](https://docs.datarobot.com/en/docs/workload-api/index.html.md): Linked from this page.
- [Operate running Workloads](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/index.html.md): Linked from this page.
- [REST: update Workloads](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md): Linked from this page.
- [Update Workloads](https://docs.datarobot.com/en/docs/workload-api/update-workloads/index.html.md): Linked from this page.
- [Replace and roll out](https://docs.datarobot.com/en/docs/workload-api/update-workloads/replace-artifact-rollouts.html.md): Linked from this page.
- [Sharing and access control](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/sharing-access-control.html.md): Linked from this page.

## Documentation content

For change-event endpoints (promote, replacement history), see [REST: update Workloads](https://docs.datarobot.com/en/docs/workload-api/update-workloads/update-rest-endpoints.html.md).

## 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](https://docs.datarobot.com/en/docs/workload-api/update-workloads/index.html.md).

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

## Statistics, events, and related entities

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