Create and run a workload

How-to guideApplies to: Unified engine deployments

Save a Manual SQL workload, read its revision, start a run, and inspect its tasks. This example uses inline orders and needs only a running engine and available compute.

Create and run a workload

Create a Manual workload, read its revision, start one run, and inspect its tasks. No external data is needed.

Placeholder	Value
`{{create_id}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{run_submission_id}}`	A new UUID for this request; reuse it when recovering the same submission.

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

1. Create the workload

POST /api/v1/workloads
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{create_id}}",
  "name": "HTTP example - category sales",
  "tasks": [
    {
      "name": "summarize",
      "sql": "WITH orders(id, category, region, amount) AS (VALUES (1, 'Books', 'North', 20), (2, 'Games', 'South', 30), (3, 'Games', 'North', 15), (4, 'Books', 'North', 40), (5, 'Garden', 'South', 25), (6, 'Garden', 'North', 10)) SELECT category, SUM(amount) AS sales FROM orders GROUP BY category ORDER BY category",
      "settings": {
        "current_catalog": "default",
        "namespace": [
          "default"
        ],
        "time_zone": "UTC",
        "case_sensitive": false,
        "ansi_enabled": true
      }
    },
    {
      "name": "rank",
      "sql": "SELECT category, sales, DENSE_RANK() OVER (ORDER BY sales DESC) AS sales_rank FROM category_totals ORDER BY sales DESC",
      "settings": {
        "current_catalog": "default",
        "namespace": [
          "default"
        ],
        "time_zone": "UTC",
        "case_sensitive": false,
        "ansi_enabled": true
      }
    }
  ],
  "dependencies": [
    {
      "upstream": "summarize",
      "downstream": "rank",
      "input_name": "category_totals"
    }
  ],
  "parameters": {},
  "options": {
    "execution_target": "DuckDb"
  },
  "policy": "Manual"
}

From the response, keep workload_id from /workload_id. Endpoint reference.

2. Read the saved revision

GET /api/v1/workloads/{{workload_id}}
Host: <ENGINE_HOST>

From the response, keep revision from /workload/revision. Endpoint reference.

3. Start one run

POST /api/v1/workloads/{{workload_id}}/runs
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{run_submission_id}}",
  "expected_revision": {{revision}},
  "parameters": {}
}

From the response, keep run_id from /workload_run_id. Endpoint reference.

4. Follow the run

GET /api/v1/workloads/{{workload_id}}/runs/{{run_id}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

5. Inspect tasks

GET /api/v1/workloads/{{workload_id}}/runs/{{run_id}}/tasks
Host: <ENGINE_HOST>

Endpoint reference.

Verify each boundary

Creation returns a workload ID. The next read retrieves its saved revision. The run request uses that revision and its own submission ID. Saving the Manual definition does not start execution. Follow the run until it succeeds, then inspect tasks and attempts. The summary should contain Books 60, Games 45, and Garden 35. The dependent rank task reads those rows as category_totals and adds ranks 1, 2, and 3. Confirm that summarize succeeds before rank executes.

Keep or clean up

The saved workload stays in the engine after you leave the page. Keep it Manual, or pause it if you later enable a recurring schedule. When all work is complete, read its current revision and use the delete-workload operation if you no longer need the definition. See Workloads for graph design, compute, schedules, sensors, retries, reruns, windows, backfills, and notifications.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Create and run a workload

Create and run a workload

1. Create the workload

2. Read the saved revision

3. Start one run

4. Follow the run

5. Inspect tasks

Verify each boundary

Keep or clean up

​Create and run a workload

​1. Create the workload

​2. Read the saved revision

​3. Start one run

​4. Follow the run

​5. Inspect tasks

​Verify each boundary

​Keep or clean up

Create and run a workload

1. Create the workload

2. Read the saved revision

3. Start one run

4. Follow the run

5. Inspect tasks

Verify each boundary

Keep or clean up