Workload API > Create Workloads > Workload concepts

Workload concepts¶

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.

Lifetime policies¶

A Workload's lifetime is determined by the status of the artifact it references. A draft artifact supports only one active Workload at a time. A locked artifact 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.

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.

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

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.