Start a build
POST /v1/buildsJSON body
{
"dataset_id": "finnish-vehicle-market-listings",
"definition_version": "0.2.0",
"source_snapshot_ids": ["snapshot-20260813"]
}202 JSON
{
"id": "build_preview_1",
"status": "queued",
"dataset_id": "finnish-vehicle-market-listings",
"definition_version": "0.2.0",
"created_at": "2026-08-15T09:00:00.000Z"
}Build lifecycle
| Status | Meaning | Terminal |
|---|---|---|
| queued | Accepted and waiting for capacity | No |
| running | Builder is processing source snapshots | No |
| completed | Build finished; inspect the resulting release workflow | Yes |
| failed | Build stopped with an error | Yes |
| cancelled | Cancellation was accepted | Yes |
Poll with a bounded interval
cURL
curl "https://api.datasets.nordicdevhouse.com/v1/builds/build_preview_1" \
-H "Authorization: Bearer $DATASET_API_KEY" \
-H "X-API-Version: 1"Poll GET /builds/{build_id} until a terminal status. Use a bounded interval with jitter and stop after your operational deadline instead of polling continuously.
Cancellation is a state transition
DELETE /v1/builds/{build_id}A successful cancellation returns the build object. Continue reading the returned status rather than assuming that closing the client connection cancelled server-side work.