# Workload concepts

> Workload concepts - Object model, lifecycle states, protons, lifetime policies, and the draft vs.
> locked decision.

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.246795+00:00` (UTC).

## Primary page

- [Workload concepts](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [Object model](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#object-model): In-page section heading.
- [Lifecycle states](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#lifecycle-states): In-page section heading.
- [Lifetime policies](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#lifetime-policies): In-page section heading.
- [Draft (ephemeral)](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#draft-ephemeral): In-page section heading.
- [Locked (persistent)](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#locked-persistent): In-page section heading.
- [Choose draft vs. locked](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#choose-draft-vs-locked): In-page section heading.
- [Importance](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#importance): In-page section heading.
- [Sharing](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#sharing): In-page section heading.

## Related documentation

- [Workload API](https://docs.datarobot.com/en/docs/workload-api/index.html.md): Linked from this page.
- [Create Workloads](https://docs.datarobot.com/en/docs/workload-api/create-workloads/index.html.md): Linked from this page.
- [Lifecycle states](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/lifecycle-states.html.md): Linked from this page.
- [Artifact lifecycle](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-lifecycle): Linked from this page.
- [Promote to production](https://docs.datarobot.com/en/docs/workload-api/update-workloads/promote-production.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

A Workload is the logical unit of the Workload API: a stable identity, an invoke endpoint, and the governance wrapper around one or more running container instances (protons). Workloads are what you create, monitor, share, and tear down.

## Object model

A Workload always has at least one proton. During a replace operation it can temporarily have two—active and candidate. High-availability Workloads can run multiple protons permanently.

A Workload is created with `POST /workloads/`, either with an inline artifact spec or a reference to an existing `artifactId`.

## Lifecycle states

Workloads report a user-facing `WorkloadStatus` derived from the primary proton's `ProtonStatus` —the Workload view collapses internal proton-only states ( `initializing`, `warming`, `draining`, `restarting`) into adjacent Workload-visible states. The following table lists proton-level sequences for create, update, replace, stop, failure, and promote operations:

| Operation | Transition |
| --- | --- |
| Create | submitted -> provisioning -> launching -> running |
| Update | running -> initializing -> running |
| Replace | running -> running(active) + initializing/warming/running(candidate) -> switch -> draining(active) + running(new active) -> running(single active) |
| Stop | running -> stopping -> stopped |
| Failure | initializing\|running -> errored |
| Promote | running (draft) -> running (locked) (no restart) |

The platform derives these states from the Kubernetes pods backing the Workload's protons. For the full `WorkloadStatus` and `ProtonStatus` enums, pod-state predicates, multi-replica worst-state-wins aggregation, and the proton runtime backing, see [Lifecycle states](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/lifecycle-states.html.md).

## Lifetime policies

A Workload's lifetime is determined by the status of the artifact it references. A [draft artifact](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#draft-ephemeral) supports only one active Workload at a time. A [locked artifact](https://docs.datarobot.com/en/docs/workload-api/create-workloads/workload-concepts.html.md#locked-persistent) can serve any number of Workloads simultaneously—useful for multi-region or multi-tenant deployments.

### Draft (ephemeral)

Draft Workloads are short-lived and tied to a single iterating artifact. They carry an 8-hour TTL (time-to-live)—a countdown that auto-terminates the Workload 8 hours after creation, freeing the resources for other work and allowing iteration without manual cleanup.

| Policy | Behavior |
| --- | --- |
| Auto-cleanup | Terminates 8 hours after creation (the TTL). |
| Restart timer | TTL resets to 8 hours each time you restart the Workload. |
| Workloads per artifact | At most one active Workload per draft artifact. |

### Locked (persistent)

Locked Workloads run indefinitely against an immutable artifact and require an explicit importance. They have no TTL—they run until you stop or delete them, or until you replace them with a new artifact.

| Policy | Behavior |
| --- | --- |
| Lifetime | Runs until explicitly stopped or deleted. |
| importance | Optional; defaults to low. A priority hint the platform uses for resource prioritization and operational triage when the cluster is under contention. Does not affect routing, autoscaling, or QoS guarantees—it is a governance signal. Values: critical, high, moderate, low. |
| Workloads per artifact | Multiple Workloads can share one locked artifact. |

### Choose draft vs. locked

For the artifact-side definitions—what `draft` and `locked` mean as artifact statuses, how to lock, and the one-way rule—see [Artifact lifecycle](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-lifecycle).

| Dimension | Draft artifact Workload | Locked artifact Workload |
| --- | --- | --- |
| Mutability | Artifact spec can change while you iterate. | Artifact is immutable after lock. |
| Lifetime | 8-hour TTL from creation; timer resets when you restart the Workload. | Runs until you stop or delete it. |
| importance | Optional; defaults to low. | Optional; defaults to low. Set explicitly for production Workloads. |
| Workloads per artifact | At most one active Workload per draft artifact. | Many Workloads can share one locked artifact. |
| Replace rules | Replace with another draft artifact when swapping experiments. | Replace with another locked artifact for controlled production rollouts. |
| Promotion | Use POST /workloads/{id}/promote to move the same Workload identity to production semantics. | Not applicable—already on the locked path. |

Use a draft artifact Workload for active development and iteration. Use a locked artifact Workload for production services that need a stable endpoint.

See also [Artifact lifecycle](https://docs.datarobot.com/en/docs/workload-api/build-artifacts/artifacts-concepts.html.md#artifact-lifecycle) and [Promote to production](https://docs.datarobot.com/en/docs/workload-api/update-workloads/promote-production.html.md).

## Importance

`importance` is a priority hint used for resource prioritization and operational triage under contention (default `low`). It does not change routing or autoscaling targets by itself.

| Importance | When to use |
| --- | --- |
| low | Internal tooling, dev Workloads, low-stakes services. |
| moderate | Internal services with limited blast radius. |
| high | User-facing services that are intended to be hard to evict. |
| critical | Mission-critical Workloads; do not evict. |

`importance` is mutable on a running Workload ( `PATCH /workloads/{id}` with `{"importance": "..."}`).

## Sharing

Workloads support shared roles via `PATCH /workloads/{workload_id}/sharedRoles`. A shared role grants a specific access level on the Workload (the `SubjectType` values are `user`, `group`, `organization`, and `role`). Roles use the `SharingRole` enum—most integrations use `OWNER`, `EDITOR`, or `OBSERVER`. Shared roles propagate to events, statistics, and the `/protons/` sub-resource. The artifact backing the Workload has its own sharing policy ( `PATCH /artifacts/{artifact_id}/sharedRoles`).

```
curl -X PATCH "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/sharedRoles" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "updateRoles",
    "roles": [{"id": "USER_ID", "role": "EDITOR", "shareRecipientType": "user"}]
  }'
```

For the full role list, propagation, and recipient identification options, see [Sharing and access control](https://docs.datarobot.com/en/docs/workload-api/operate-workloads/sharing-access-control.html.md).