Workload API > Tutorial: Hello, Workload!

Tutorial: Hello, Workload!¶

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 POST /workloads call, no artifact registration ceremony, auto-cleanup after 8 hours.

Connect to DataRobot¶

To connect to DataRobot, you need the following:

DataRobot API endpoint and token, DATAROBOT_ENDPOINT and DATAROBOT_API_TOKEN.
A terminal with curl. JSON responses are parsed in Python in this notebook so it runs without extra dependencies.

The connection details are set automatically inside this DataRobot Notebook. The next cell connects to DataRobot and exports DATAROBOT_ENDPOINT / DATAROBOT_API_TOKEN as shell environment variables so the curl cells that follow can use them.

In [ ]:

Copied!

import os

import datarobot as dr

client = dr.Client()
os.environ.setdefault("DATAROBOT_ENDPOINT", client.endpoint)
os.environ.setdefault("DATAROBOT_API_TOKEN", client.token)

print("Connected:", os.environ["DATAROBOT_ENDPOINT"])
import os

import datarobot as dr

client = dr.Client()
os.environ.setdefault("DATAROBOT_ENDPOINT", client.endpoint)
os.environ.setdefault("DATAROBOT_API_TOKEN", client.token)

print("Connected:", os.environ["DATAROBOT_ENDPOINT"])

Deploy whoami¶

Create a Workload with an inline draft artifact—one POST /workloads call defines the container and creates the Workload together. whoami is a tiny HTTP server that echoes request information, perfect for confirming traffic flows end-to-end.

In [ ]:

Copied!





%%bash
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 create_output.json
%%bash
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 create_output.json

Save the Workload ID from the response so later cells can reference it:

In [ ]:

Copied!





import json
from pathlib import Path

result = json.loads(Path("create_output.json").read_text())
workload_id = result["id"]
os.environ["WORKLOAD_ID"] = workload_id
print("Workload ID:", workload_id)
import json
from pathlib import Path

result = json.loads(Path("create_output.json").read_text())
workload_id = result["id"]
os.environ["WORKLOAD_ID"] = workload_id
print("Workload ID:", workload_id)

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 to pass—the platform polls readinessProbe.path (here, /) on the container's port. If you typo the path or your container doesn't serve a 2xx on it, the Workload sits in launching even though the container itself is up.

In [ ]:

Copied!





import time

import requests

headers = {"Authorization": f"Bearer {os.environ['DATAROBOT_API_TOKEN']}"}

for i in range(120):
    resp = requests.get(
        f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}", headers=headers
    )
    resp.raise_for_status()
    status = resp.json()["status"]
    print("status:", status, flush=True)
    if status == "running":
        break
    if status == "errored":
        events = requests.get(
            f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}/events", headers=headers
        )
        print("Workload errored; see the events endpoint for detail:", events.json(), flush=True)
        raise RuntimeError("Workload errored")
    time.sleep(5)
else:
    raise TimeoutError("Timed out waiting for running")
import time

import requests

headers = {"Authorization": f"Bearer {os.environ['DATAROBOT_API_TOKEN']}"}

for i in range(120):
    resp = requests.get(
        f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}", headers=headers
    )
    resp.raise_for_status()
    status = resp.json()["status"]
    print("status:", status, flush=True)
    if status == "running":
        break
    if status == "errored":
        events = requests.get(
            f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}/events", headers=headers
        )
        print("Workload errored; see the events endpoint for detail:", events.json(), flush=True)
        raise RuntimeError("Workload errored")
    time.sleep(5)
else:
    raise TimeoutError("Timed out waiting for running")

Say hello¶

Read the invoke URL from the Workload and call it. whoami will echo request headers and connection info. That's your hello world.

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.

In [ ]:

Copied!





import requests

headers = {"Authorization": f"Bearer {os.environ['DATAROBOT_API_TOKEN']}"}
workload = requests.get(
    f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}", headers=headers
).json()
endpoint = workload["endpoint"]

response = requests.get(endpoint, headers=headers)
print(response.status_code)
print(response.text)
import requests

headers = {"Authorization": f"Bearer {os.environ['DATAROBOT_API_TOKEN']}"}
workload = requests.get(
    f"{os.environ['DATAROBOT_ENDPOINT']}/workloads/{workload_id}", headers=headers
).json()
endpoint = workload["endpoint"]

response = requests.get(endpoint, headers=headers)
print(response.status_code)
print(response.text)

Clean up¶

POST /workloads/{id}/stop stops the underlying proton. Draft Workloads also auto-terminate after 8 hours, so cleanup is optional, but good hygiene.

In [ ]:

Copied!





%%bash
set -euo pipefail
curl -X POST "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/stop" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"
%%bash
set -euo pipefail
curl -X POST "${DATAROBOT_ENDPOINT}/workloads/${WORKLOAD_ID}/stop" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

Summary¶

In this tutorial:

You created a draft Workload from an inline draft artifact (type service).
The platform built the container group, ran readiness probes, and assigned an invoke URL.
Because the artifact is draft, the Workload is short-lived: 8-hour TTL, one Workload per draft artifact, automatic cleanup.