# Orchestration Control Flow: Delay, Poll, and Loop
> Use orchestration control-flow nodes — delay, poll, loop, and condition — to pace, wait, repeat, and branch a run.
# Orchestration Control Flow: Delay, Poll, and Loop
This tutorial focuses on the **control-flow nodes** of the [Orchestrations](/docs/modules/orchestrations) module — the ones that pace, wait, repeat, and branch a run rather than call an LLM. You will build a sub-orchestration, a [builtin tool](/docs/modules/tools) for the `poll` node, and a main orchestration wiring `delay → poll → loop → condition → transform`, then run it and inspect the per-node executions.
Everything here is deterministic — **no AI provider is required**. For `agent` nodes (LLM calls), see [Orchestrate a Sonnet](/docs/tutorials/orchestrate-a-sonnet); a [reference table](#every-node-type) at the end maps every node type to where it is demonstrated.
## Prerequisites
- SOAT running locally. Follow the [Quick Start](/docs/getting-started) guide to bring the stack up with Docker Compose.
- New to SOAT? Read [Key Concepts](/docs/getting-started/concepts) to understand projects, tools, and runs first.
- CLI installed and configured, or SDK set up. See [CLI](/docs/cli) or [SDK](/docs/sdk).
- For production hardening (secrets, env vars), see [Configuration](/docs/self-hosting/configuration).
- Server is at `http://localhost:5047`.
```bash
export SOAT_BASE_URL=http://localhost:5047
```
```ts
```
```bash
export SOAT_BASE_URL=http://localhost:5047
```
---
## Step 1 — Log in as admin
Admin is the built-in superuser role. See [Users](/docs/modules/users#examples) for authentication details.
```bash
ADMIN_TOKEN=$(soat login-user --username admin --password Admin1234! | jq -r '.token')
export SOAT_TOKEN=$ADMIN_TOKEN
```
```ts
const soat = new SoatClient({ baseUrl: 'http://localhost:5047' });
const { data: login } = await soat.users.loginUser({
body: { username: 'admin', password: 'Admin1234!' },
});
const adminSoat = new SoatClient({
baseUrl: 'http://localhost:5047',
token: login.token,
});
```
```bash
ADMIN_TOKEN=$(curl -s -X POST "$SOAT_BASE_URL/api/v1/users/login" \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Admin1234!"}' | jq -r '.token')
```
---
## Step 2 — Create a project
Every resource lives inside a [project](/docs/modules/projects#examples).
```bash
PROJECT_ID=$(soat create-project --name "Node Tour" | jq -r '.id')
echo "PROJECT_ID: $PROJECT_ID"
```
```ts
const { data: project } = await adminSoat.projects.createProject({
body: { name: 'Node Tour' },
});
const PROJECT_ID = project.id;
```
```bash
PROJECT_ID=$(curl -s -X POST "$SOAT_BASE_URL/api/v1/projects" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Node Tour"}' | jq -r '.id')
echo "PROJECT_ID: $PROJECT_ID"
```
---
## Step 3 — Create the per-item sub-orchestration
The `loop` node runs a whole [orchestration](/docs/modules/orchestrations#loops-collection-iteration) once per item in a collection. Create a tiny child orchestration that receives one `item` and echoes it through a `transform` node. The loop injects each element under the `item` variable, seeded into the sub-run's input namespace, so the child reads it with `{"var": "input.item"}`.
```bash
SUB_ORCH_ID=$(soat create-orchestration \
--project-id "$PROJECT_ID" \
--name "Process One Item" \
--nodes '[{"id":"echo","type":"transform","expression":{"var":"input.item"},"state_mapping":{"state.processed":{"var":"output.result"}}}]' \
--edges '[]' | jq -r '.id')
echo "SUB_ORCH_ID: $SUB_ORCH_ID"
```
```ts
const { data: subOrch } = await adminSoat.orchestrations.createOrchestration({
body: {
project_id: PROJECT_ID,
name: 'Process One Item',
nodes: [
{
id: 'echo',
type: 'transform',
expression: { var: 'input.item' },
state_mapping: { 'state.processed': { var: 'output.result' } },
},
],
edges: [],
},
});
const SUB_ORCH_ID = subOrch.id;
```
```bash
SUB_ORCH_ID=$(curl -s -X POST "$SOAT_BASE_URL/api/v1/orchestrations" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"project_id\":\"$PROJECT_ID\",\"name\":\"Process One Item\",\"nodes\":[{\"id\":\"echo\",\"type\":\"transform\",\"expression\":{\"var\":\"input.item\"},\"state_mapping\":{\"state.processed\":{\"var\":\"output.result\"}}}],\"edges\":[]}" \
| jq -r '.id')
echo "SUB_ORCH_ID: $SUB_ORCH_ID"
```
---
## Step 4 — Create the tool the poll node calls
A `poll` node repeatedly calls a [Tool](/docs/modules/tools#examples) until a JSON Logic exit condition on its response holds. Create a [builtin tool](/docs/modules/tools) that reads this project back via the `get-project` action. Polling a resource until a field reaches an expected value is the canonical use of a `poll` node — here the project is already readable, so the loop exits on the first attempt.
```bash
CHECK_TOOL_ID=$(soat create-tool \
--project-id "$PROJECT_ID" \
--name "read-project" \
--type "builtin" \
--description "Read this project so the poll node can check readiness" \
--actions '["get-project"]' \
--preset-parameters '{"project_id": "'"$PROJECT_ID"'"}' | jq -r '.id')
echo "CHECK_TOOL_ID: $CHECK_TOOL_ID"
```
```ts
const { data: checkTool } = await adminSoat.tools.createTool({
body: {
project_id: PROJECT_ID,
name: 'read-project',
type: 'soat',
description: 'Read this project so the poll node can check readiness',
actions: ['get-project'],
preset_parameters: { projectId: PROJECT_ID },
},
});
const CHECK_TOOL_ID = checkTool.id;
```
```bash
CHECK_TOOL_ID=$(curl -s -X POST "$SOAT_BASE_URL/api/v1/tools" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"project_id\":\"$PROJECT_ID\",\"name\":\"read-project\",\"type\":\"soat\",\"description\":\"Read this project so the poll node can check readiness\",\"actions\":[\"get-project\"],\"preset_parameters\":{\"projectId\":\"$PROJECT_ID\"}}" \
| jq -r '.id')
echo "CHECK_TOOL_ID: $CHECK_TOOL_ID"
```
---
## Step 5 — Create the control-flow orchestration
This [orchestration](/docs/modules/orchestrations#node-types) chains the control-flow nodes:
- **`delay`** — waits a fixed `duration`. Accepts the friendly suffix form (`1s`, `5m`, `2h`) or ISO 8601 (`PT1S`).
- **`poll`** — calls the tool each attempt and stops when `exit_condition` is truthy, bounded by `interval` + `max_iterations`. The condition is evaluated against the run state plus `response` (the latest tool result) and `attempt`. See [Polling](/docs/modules/orchestrations#polling).
- **`loop`** — runs `orchestration_id` once per element of `collection`, injecting each as `item_variable`. This is the *same* `orchestration_id` field the standalone `sub_orchestration` node uses. See [Loops](/docs/modules/orchestrations#loops-collection-iteration).
- **`condition`** — emits a label; outgoing edges select a branch with `condition: "