Trigger and manage builds¶

Once an artifact has an imageBuildConfig and a codeRef, you trigger builds against it. A build takes your uploaded source, produces a container image, pushes it to DataRobot's registry, and writes the resulting imageUri back onto the artifact.

This page covers running builds. For configuring what gets built, see Build an image from source code.

Endpoints¶

Builds are always scoped to an artifact; there is no top-level builds collection, because a build's output is written directly onto that artifact's container—tracking or cancelling a build only makes sense in the context of the artifact it belongs to.

Build output is not served by the Workload API. It is exported as OpenTelemetry logs and read from GET /api/v2/otel/artifact/{artifactId}/logs/—see Build logs.

Trigger a build¶

Trigger a build directly through the REST API, or with the CLI, which can optionally block until the build reaches a terminal state.

curl -s -X POST "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}/builds" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | tee /tmp/build.json

export BUILD_ID=$(jq -r '.buildIds[0]' /tmp/build.json)

# Inside a directory linked with dr artifact code init, the ID is optional
dr artifact build create ${ARTIFACT_ID}

# Or block until the build reaches a terminal state
dr artifact build create ${ARTIFACT_ID} --wait

The response is 202 with the IDs of the builds that were started:

{ "buildIds": ["68f0d4aa11bb22cc33dd44ee"] }

buildIds always contains exactly one ID today, because only one container per artifact may build from source. Use that ID for the status and cancel calls, and to filter the build's logs.

Preconditions¶

A trigger that fails these checks returns 422 and starts nothing:

Build statuses¶

A build progresses through the following statuses, with BUILT frequently mistaken for a completed, deployable image.

Status only ever moves forward:

flowchart LR
    P["PENDING"] --> I["IN_PROGRESS"]
    I --> B["BUILT"]
    B --> C["COMPLETED"]
    I --> F["FAILED"]
    B --> F
    P --> X["CANCELLED"]
    I --> X
    B --> X

COMPLETED, FAILED, and CANCELLED are terminal and never change afterwards.

Track a build¶

Check a build's status the same two ways as triggering it: a direct API call, or the CLI, which can also poll on your behalf with --wait.

curl -s "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}/builds/${BUILD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" | jq '{id, status}'

until curl -s "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}/builds/${BUILD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  | jq -e -r '.status | test("COMPLETED|FAILED|CANCELLED")' >/dev/null; do
  sleep 10
done

dr artifact build get ${ARTIFACT_ID} ${BUILD_ID}

A single build reads as:

{
  "id": "68f0d4aa11bb22cc33dd44ee",
  "name": "my-agent image build",
  "artifactId": "68f0c1a2b3d4e5f607182930",
  "status": "COMPLETED",
  "createdAt": "2026-08-20T10:15:00Z",
  "updatedAt": "2026-08-20T10:19:42Z",
  "creator": { "id": "...", "username": "...", "email": "..." }
}

List builds¶

Retrieve the artifact's build history in a single paginated call, newest first.

curl -s "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}/builds?limit=20" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

Builds are returned newest first in the standard paginated envelope (totalCount, count, next, previous, data). The only query parameters are offset (default 0) and limit (default 10, maximum 100). There is no filtering, sorting, or search.

Rebuild after a code change¶

Sync the new code, then trigger another build. There is no need to cancel the previous one first: triggering a build stops any earlier build for the same source, and the new build gets its own ID and its own image tag. Builds are never deduplicated—every trigger produces a new build.

If a rebuild fails, the artifact keeps the imageUri from the last successful build, so anything already deployed keeps running and the image stays deployable. The failure is visible in the build status, not by the image disappearing.

Each container also exposes a read-only imageOutdated flag: true when the container has an imageUri but the most recent build is still running or has failed. The flag tracks build activity, not codeRef drift—patching a newer codeRef without triggering a build leaves imageOutdated at false even though the deployed image no longer matches the current source; it only flips once a build against that source is actually running. A cancelled build does not mark the image outdated either, since keeping the previous image is the intended outcome of a cancel. The flag is derived, never stored, and is ignored if you send it back.

Cancel a build¶

Cancelling stops an in-progress build without affecting the artifact's current image.

curl -s -X DELETE "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}/builds/${BUILD_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}"

DELETE is the cancel operation—there is no separate cancel endpoint. It returns 204 and:

• stops the running build;
• makes a best-effort attempt to remove the build's image from the registry, so a cancelled or in-progress build doesn't leave a partial image behind;
• removes the build from the artifact's build list;
• clears the build pointer from the container spec.

Cancelling does not revert imageUri. An image from an earlier successful build stays attached to the artifact and remains deployable. Deleting the same build twice returns 404.

Build results¶

When a build reaches COMPLETED, the platform updates the container in the artifact spec:

"build": {
  "artifactImageBuildId": "68f0d4aa11bb22cc33dd44ee",
  "status": "COMPLETED",
  "createdAt": "2026-08-20T10:15:00Z"
}

and sets imageUri on the container. The image tag is the build ID, so an artifact's image always traces back to the build that produced it. The build block is managed by the platform; it is ignored if you send it.

Build before you deploy or lock¶

Both deploying and locking require a real, completed build. The relevant errors are:

Error reference¶

The following table maps the HTTP status codes the build endpoints return to their cause and the corrective action.

A build that is accepted (202) and then fails asynchronously reports FAILED rather than an HTTP error. Use Build logs to find out why.

Next steps¶

Triggering and tracking a build is one stage in the source-to-Workload flow; the following resources cover diagnosing a failure, configuring what gets built, and deploying the result.