Definition and API reference

ReferenceApplies to: Unified engine deployments

Use the same workload model as the editor when creating or managing workflows through HTTP. Routes below are relative to your engine’s HTTP origin and include the /api/v1 prefix. For editable requests and a complete linked example, use Create and run a workload over HTTP. The HTTP API reference covers the full API beyond workloads.

Definition shape

A workload draft contains name, tasks, dependencies, parameters, options, policy, and optional workflow settings. The complete definitions in Your first workload and Build a multi-task workflow can be expanded and copied. For HTTP creation, add a nonnil UUID submission_id to the draft. The editor supplies request identities itself. Update and validation requests have their own request fields; do not send a run’s response object as a create body. POST the complete draft plus submission_id to /api/v1/workloads/validate to validate, or to /api/v1/workloads to create. Validation does not save or execute it. For PUT, add both a fresh submission_id and the reviewed expected_revision to the complete updated definition. Pause and resume requests contain submission_id and expected_revision.

Field	Purpose
`name`	Workload display name.
`tasks`	Named SQL, batch Python, or sensor tasks with initial query settings and optional execution overrides.
`dependencies`	Edges containing `upstream`, `downstream`, and nullable `input_name`.
`parameters`	Named typed definitions with presence, default, description, and allowed-value rules.
`options`	Workload execution and scheduling-behavior defaults.
`policy`	Manual, immediate, one-time, interval, or cron schedule.
`workflow`	Data-window generation and notification subscriptions.

Task fields

Field	Purpose
`name`	Unique stable task name.
`sql`	SQL source for a SQL task.
`python`, `python_mode`	Python source and `Batch` mode for a batch Python task.
`settings`	`current_catalog`, `namespace`, `time_zone`, `case_sensitive`, and `ansi_enabled`.
`control.retry`	Optional task retry override. See Retry policies.
`control.sensor`	Optional sensor definition. Sensor tasks do not need SQL. See Sensors.
Execution overrides	`worker_scope`, `deployment_profile`, `provisioner`, `profile`, or `compute_requirements`.
`incremental_source`	Supported table cursor source. See Incremental workloads.

All tasks use the same initial query context. Python uses ordering dependencies without incoming SQL result aliases. A sensor supplies no row result. Graph validation rejects cycles and missing task references.

Schedule JSON

"Manual"

Other shapes are:

"Immediately"

{ "At": { "at": { "unix_millis": 1893456000000 } } }

{
  "Interval": {
    "start_at": { "unix_millis": 1893456000000 },
    "every": { "secs": 300, "nanos": 0 }
  }
}

{ "Cron": { "expression": "0 0 0 * * *", "timezone": "UTC" } }

Timestamps use Unix milliseconds. Durations use seconds and nanoseconds. Cron uses a seconds field. Data-window interval boundaries use UTC; cron windows follow the saved schedule time zone.

Execution options

Option	Values or meaning
`worker_scope`	`Deployment`, `Workload`, or `Task`.
`deployment_profile`	A configured deployment compute profile.
`provisioner`, `profile`	Available allocation choices for non-deployment compute.
`compute_requirements`	CPU millicores, memory bytes, and optional query tuning.
`parallelism`	Positive task concurrency limit.
`queue_timeout`, `execution_timeout`	Optional durations for their respective phases.
`max_attempts`	Positive inherited task attempt limit.
`missed_run_policy`	`RunOnce`, `RunAll`, or `Skip`.
`overlap_policy`	`Wait`, `Skip`, or `Allow`; incremental workloads reject Allow.
`execution_target`	Engine target; native editor examples use `DuckDb` in the API model.

Omitted choices are resolved from instance defaults. Deployment compute uses its deployment profile rather than a separate provisioner, profile, or custom resource request. Inspect GET /api/v1/execution-options for available compute choices.

Create and manage workloads

Method	Route	Purpose
GET / POST	`/api/v1/workloads`	List or create workloads.
POST	`/api/v1/workloads/validate`	Validate a definition without executing it.
GET / PUT / DELETE	`/api/v1/workloads/{workload_id}`	Read, update, or delete a workload.
POST	`/api/v1/workloads/{workload_id}/pause`	Pause new work.
POST	`/api/v1/workloads/{workload_id}/resume`	Resume new work under the saved policy.

Start and inspect runs

Method	Route	Purpose
GET / POST	`/api/v1/workloads/{workload_id}/runs`	List runs or start a manual run.
GET	`/api/v1/workloads/{workload_id}/run-summaries`	Read paged run summaries.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}`	Read a run’s recorded invocation and state.
POST	`/api/v1/workloads/{workload_id}/runs/{run_id}/cancel`	Request cancellation.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}/tasks`	Read tasks.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}`	Read a task.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}/attempts`	Read attempts.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}/tasks/{task_id}/attempts/{attempt_id}`	Read one attempt.

A manual start body contains:

{
  "submission_id": "66666666-6666-4666-8666-666666666666",
  "expected_revision": 1,
  "parameters": { "region": "North", "minimum_amount": 0 }
}

Use parameter values defined by that workload. Add data_window for a manual windowed invocation; see Data windows. Replace example IDs and revisions with your saved values.

Reruns, backfills, and notifications

Method	Route	Purpose
POST	`/api/v1/workloads/{workload_id}/runs/{run_id}/rerun/preview`	Preview execute, reuse, and blocked tasks.
POST	`/api/v1/workloads/{workload_id}/runs/{run_id}/rerun`	Start the reviewed selective rerun.
GET / POST	`/api/v1/workloads/{workload_id}/backfills`	List or create backfills.
POST	`/api/v1/workloads/{workload_id}/backfills/preview`	Preview historical windows.
GET / POST	`/api/v1/workloads/{workload_id}/backfills/{backfill_id}`	Read progress or submit a control action.
GET	`/api/v1/workloads/{workload_id}/runs/{run_id}/notifications`	Read delivery history.
POST	`/api/v1/workloads/{workload_id}/runs/{run_id}/notifications/retry`	Retry a recorded event’s delivery.

Use the full request examples in Selective reruns, Backfills, and Notifications. For retained query output, see Results and table commits.

Request identity and revisions

A submission ID identifies one intended operation. Retry an identical request with the same ID after a lost response. Use a fresh ID for new intended work. Reusing an ID with changed content can produce a conflict. expected_revision protects operations that depend on a reviewed workload definition. Reload and review if the saved revision changes before acceptance. A successful HTTP acceptance is not proof that execution or publication finished; follow the returned identity to its final status.

Operator defaults

Service configuration belongs under Operations: Scheduler, Controller, Compute, and Submission defaults.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Definition and API reference

Definition shape

Task fields

Schedule JSON

Execution options

Create and manage workloads

Start and inspect runs

Reruns, backfills, and notifications

Request identity and revisions

Operator defaults

​Definition shape

​Task fields

​Schedule JSON

​Execution options

​Create and manage workloads

​Start and inspect runs

​Reruns, backfills, and notifications

​Request identity and revisions

​Operator defaults

Definition shape

Task fields

Schedule JSON

Execution options

Create and manage workloads

Start and inspect runs

Reruns, backfills, and notifications

Request identity and revisions

Operator defaults