Workload API > Get started: Workload API > Tutorial: Hello, Workload

Tutorial: Hello, Workload¶

Premium feature

The Workload API is a premium feature. Contact your DataRobot representative or administrator for information on enabling the feature.

This tutorial demonstrates the shortest path from zero to a running container on DataRobot. In about five minutes you'll deploy containous/whoami—a tiny, publicly available third-party image (not published by DataRobot) that echoes request headers—as a draft Workload, hit its endpoint, and tear it down.

A draft Workload is the hello-world equivalent for the Workload API: one create call, no artifact registration ceremony, and an 8-hour TTL that cleans it up automatically if you don't.

Pick the tab that matches how you want to work: cURL calls the REST API directly, the CLI wraps the same calls in dr workload commands, and Pulumi declares the end state and reconciles it for you. Prefer a runnable notebook instead:

View as a runnable notebook

Prerequisites¶

cURLCLIPulumi

A terminal with curl and, optionally, jq (used in the commands that follow to extract fields from JSON responses; without it, drop the trailing | jq ... and read the raw response instead).
Your DataRobot API endpoint and token, exported as shell variables:

export DATAROBOT_ENDPOINT="https://app.datarobot.com/api/v2"
export DATAROBOT_API_TOKEN="<your-api-token>"

The DataRobot CLI (dr), authenticated with dr auth login, or with DATAROBOT_ENDPOINT / DATAROBOT_API_TOKEN set in your shell.
Workload commands enabled: export DATAROBOT_CLI_FEATURE_WORKLOAD=true.

Pulumi CLI installed, plus the DataRobot Pulumi provider.
A Pulumi stack configured with datarobot:endpoint and datarobot:apikey—see Pulumi setup.

Deploy whoami¶

Create a Workload with an inline draft artifact—one call defines the container and creates the Workload together.

cURLCLIPulumi

curl -s -X POST "${DATAROBOT_ENDPOINT}/workloads" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-whoami",
    "artifact": {
      "name": "whoami-artifact",
      "type": "service",
      "spec": {
        "containerGroups": [{
          "name": "default",
          "containers": [{
            "name": "whoami",
            "imageUri": "containous/whoami:latest",
            "port": 8080,
            "primary": true,
            "entrypoint": ["/whoami", "--port", "8080"],
            "readinessProbe": {"path": "/", "port": 8080, "initialDelaySeconds": 5}
          }]
        }]
      }
    },
    "runtime": {
      "containerGroups": [{
        "name": "default",
        "replicaCount": 1,
        "containers": [{
          "name": "whoami",
          "resourceAllocation": {"cpu": 1, "memory": "512MB"}
        }]
      }]
    }
  }' | tee /tmp/workload.json | jq -r '.id'

export WORKLOAD_ID=$(jq -r '.id' /tmp/workload.json)

The response is a Workload object; id is the Workload ID used for the rest of this tutorial.

Save the spec to a file:

workload.yaml

name: hello-whoami
artifact:
  name: whoami-artifact
  type: service
  spec:
    containerGroups:
      - name: default
        containers:
          - name: whoami
            imageUri: containous/whoami:latest
            port: 8080
            primary: true
            entrypoint: ["/whoami", "--port", "8080"]
            readinessProbe:
              path: "/"
              port: 8080
              initialDelaySeconds: 5
runtime:
  containerGroups:
    - name: default
      replicaCount: 1
      containers:
        - name: whoami
          resourceAllocation:
            cpu: 1
            memory: "512MB"

Then create it:

dr workload create --spec-file workload.yaml --output-format json | tee /tmp/workload.json
export WORKLOAD_ID=$(jq -r '.id' /tmp/workload.json)

__main__.py

import pulumi
import pulumi_datarobot as datarobot

artifact = datarobot.Artifact(
    "whoami-artifact",
    name="whoami-artifact",
    type="service",
    spec={
        "container_groups": [{
            "name": "default",
            "containers": [{
                "name": "whoami",
                "image_uri": "containous/whoami:latest",
                "port": 8080,
                "primary": True,
                "entrypoint": ["/whoami", "--port", "8080"],
                "readiness_probe": {"path": "/", "port": 8080, "initial_delay_seconds": 5},
            }]
        }]
    },
)

workload = datarobot.Workload(
    "hello-whoami",
    name="hello-whoami",
    artifact_id=artifact.artifact_id,
    runtime={
        "container_groups": [{
            "name": "default",
            "replica_count": 1,
            "containers": [{
                "name": "whoami",
                "resource_allocation": {"cpu": 1, "memory": "512MB"},
            }],
        }]
    },
)

pulumi.export("workloadId", workload.id)
pulumi.export("endpoint", workload.endpoint)

pulumi up

pulumi up blocks until the Workload reaches running, so once it returns, skip ahead to Say hello.

Wait for running¶

Poll the Workload's status until it reaches running. Expected happy-path progression: submitted → provisioning → launching → running. running requires the readiness probe (path: "/", set in Deploy whoami) to return 2xx on the container's port—if you typo the path, the Workload sits in launching even though the container itself is up.

cURLCLIPulumi

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq -r '.status'

For the full lifecycle audit trail, call the events endpoint directly:

curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/events" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

dr workload status "$WORKLOAD_ID"

If it reads errored, dr workload get "$WORKLOAD_ID" gives a fuller detail view.

Nothing to do here—pulumi up already blocked until running.

Say hello¶

Read the invoke URL and call it. whoami echoes request headers and connection info back—that's your hello world.

cURLCLIPulumi

ENDPOINT=$(curl -s "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq -r '.endpoint')

curl -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" "${ENDPOINT}"

ENDPOINT=$(dr workload endpoint "$WORKLOAD_ID")
curl -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" "$ENDPOINT"

curl -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" "$(pulumi stack output endpoint)"

401 error

If the call returns 401, double-check that DATAROBOT_API_TOKEN is set and passed in the Authorization: Bearer header—the platform only reports a Workload as running once its endpoint is confirmed reachable, so a persistent 401 at that point points to the token rather than a route that hasn't propagated yet.

Clean up¶

Draft Workloads auto-terminate after their 8-hour TTL, so cleanup is optional, but good hygiene.

cURLCLIPulumi

curl -X POST "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/stop" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

dr workload stop "$WORKLOAD_ID"

pulumi destroy

Summary¶

In this tutorial you:

Created a draft Workload from an inline draft artifact (type service).
Watched the platform build the container group, run readiness probes, and assign an invoke URL.
Confirmed traffic flows end-to-end by calling that URL.
Learned that because the artifact is draft, the Workload is short-lived: 8-hour TTL, one Workload per draft artifact, automatic cleanup.

Next steps¶

Resource	Description
Tutorial: Deploy a production-ready container	Take a service to production with a locked artifact, importance, sharing, and monitoring.
Workload concepts	The object model, lifecycle states, and the draft vs. locked decision in depth.
Manage Workloads with the CLI	Full `dr workload` command reference.
Manage Workloads with Pulumi	Full Pulumi provider reference and production patterns.