Runs
Start runs in a factory, list and read them, follow their logs, resolve asks, and pause, resume, cancel or restart them through the Duun API.
On this page
A run is one pass of a workflow: it starts from a trigger, works through the workflow’s steps on its own branch, and ends with a merged or open pull request, a failure, or a cancellation. Each run stays bound to the workflow version it started on, even if someone applies a new version while it’s running.
When a run needs a person, it stops at an ask: a plan to approve, a command to allow, questions to answer, a pull request to review, or a budget decision. Asks appear in the Inbox, and you can resolve them through the API too.
The run object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed run_. |
object | string | Always "run". |
title | string | Short title, usually from the issue or prompt. |
status | enum | queued, running, waiting (an ask is open), succeeded, failed or cancelled. |
factory_id | string | The factory the run belongs to. |
workflow_id | string | The workflow it follows. |
workflow_revision | integer | The workflow version it’s bound to. |
project_id | string | null | The project its work counts towards, if any. |
issue | object | null | The issue it works on: provider (linear, github or jira), key and url. |
agent | string | The agent doing the current step’s work, by name. |
current_step | string | null | The id of the step in progress, or the last step for finished runs. |
branch | string | The run’s branch. Every run works in its own worktree. |
ask | object | null | The open ask, if status is waiting: id, kind (approve_plan, allow_command, answer, review_pr or budget), title, created_at. |
pull_request | object | null | The run’s pull request once opened: number, url, state (open, merged or closed). |
cost | object | spent_usd so far, limit_usd (the lowest limit that applies to this run) and billed_to (duun, provider for bring-your-own-key model calls, or owned machines). |
inputs | object | Run inputs passed at start, available to steps as {{input.*}}. |
test | boolean | true for test runs started from a workflow’s Test. |
created_at | string | When the run was created. |
updated_at | string | When anything about the run last changed. |
finished_at | string | null | When it reached succeeded, failed or cancelled. |
{
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "waiting",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": {
"provider": "linear",
"key": "PLT-482",
"url": "https://linear.app/acme/issue/PLT-482"
},
"agent": "builder",
"current_step": "plan",
"branch": "duun/plt-482-idempotency-keys",
"ask": {
"id": "ask_3h2Lm8",
"kind": "approve_plan",
"title": "Approve the plan",
"created_at": "2026-11-15T09:42:07Z"
},
"pull_request": null,
"cost": { "spent_usd": 1.84, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"test": false,
"created_at": "2026-11-15T09:38:12Z",
"updated_at": "2026-11-15T09:42:07Z",
"finished_at": null
}Run status
| Status | Meaning |
|---|---|
queued | Created, waiting for a free slot (the workflow’s Concurrent runs limit) or a machine. |
running | A step is in progress. |
waiting | An ask is open. Nothing else happens until someone resolves it, or a countdown auto-approves it. Runs paused by a budget or by Pause after this step are also waiting. |
succeeded | The workflow finished. |
failed | A step failed after its retries, or the run hit its timeout. |
cancelled | Someone cancelled it. The worktree and thread are kept, so it can be restarted. |
Endpoints
Create a run
https://api.duun.ai/v1/runs Starts a run in a factory. The run follows the factory’s default workflow unless you pass workflow_id. Give the agent something to work on with an issue, a prompt, inputs, or a mix. Needs runs:write.
The workflow must have the Manual trigger on (it is on by default) for API runs to start.
Body parameters
-
factory_idstring Required -
The factory to run in, e.g.
fac_platform. -
workflow_idstring Optional -
A workflow in that factory. Defaults to the factory's default workflow.
-
promptstring Optional -
What to do, in plain language. Becomes the first message of the run's conversation.
-
issue_urlstring Optional -
A Linear, GitHub or Jira issue URL. The run reads the issue and its title becomes the run title. Its fields are available as
{{trigger.issue.*}}. -
inputsobject Optional -
Values for the workflow's run inputs, keyed by input key. Unknown keys return 400.
-
project_idstring Optional -
Count the run towards a project. Defaults to the factory's project.
-
titlestring Optional -
Overrides the title derived from the issue or prompt. Max 200 characters.
At least one of prompt, issue_url or inputs is required.
curl https://api.duun.ai/v1/runs \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: plt-482-ci-9134" \
-d '{
"factory_id": "fac_platform",
"issue_url": "https://linear.app/acme/issue/PLT-482",
"prompt": "Make any backfill a dry run first. Finance reconciles on Mondays."
}'import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
const run = await duun.runs.create(
{
factory_id: "fac_platform",
issue_url: "https://linear.app/acme/issue/PLT-482",
prompt: "Make any backfill a dry run first. Finance reconciles on Mondays.",
},
{ idempotencyKey: "plt-482-ci-9134" },
);
console.log(run.id, run.status); // run_7f3aK2pQ queuedfrom duun import Duun
client = Duun()
run = client.runs.create(
factory_id="fac_platform",
issue_url="https://linear.app/acme/issue/PLT-482",
prompt="Make any backfill a dry run first. Finance reconciles on Mondays.",
idempotency_key="plt-482-ci-9134",
)
print(run.id, run.status) # run_7f3aK2pQ queued{
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "queued",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": null,
"branch": "duun/plt-482-idempotency-keys",
"ask": null,
"pull_request": null,
"cost": { "spent_usd": 0, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"test": false,
"created_at": "2026-11-15T09:38:12Z",
"updated_at": "2026-11-15T09:38:12Z",
"finished_at": null
}Errors worth handling:
409 conflictwith codefactory_pausedorworkflow_paused: resume it first, or start the run in the app.409 conflictwith codemanual_trigger_off: turn on the workflow’s Manual trigger.409 conflictwith codebudget_exhausted: a budget or the credit balance can’t cover a new run. Themessagenames the binding budget. See Usage and budgets.
List runs
https://api.duun.ai/v1/runs Returns runs, newest first. Needs runs:read.
Query parameters
-
statusenum Optional -
Only runs in this status.
-
factory_idstring Optional -
Only runs in this factory.
-
workflow_idstring Optional -
Only runs of this workflow.
-
project_idstring Optional -
Only runs in this project.
-
created_afterstring Optional -
ISO 8601 timestamp. Only runs created after it.
-
created_beforestring Optional -
ISO 8601 timestamp. Only runs created before it.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl "https://api.duun.ai/v1/runs?factory_id=fac_platform&status=waiting" \
-H "Authorization: Bearer $DUUN_API_KEY"for await (const run of duun.runs.list({ factory_id: "fac_platform", status: "waiting" })) {
console.log(`${run.issue?.key ?? run.id}: ${run.ask?.title}`);
}for run in client.runs.list(factory_id="fac_platform", status="waiting"):
print(run.issue.key if run.issue else run.id, run.ask.title){
"object": "list",
"data": [
{
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "waiting",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"agent": "builder",
"current_step": "plan",
"ask": { "id": "ask_3h2Lm8", "kind": "approve_plan", "title": "Approve the plan", "created_at": "2026-11-15T09:42:07Z" },
"cost": { "spent_usd": 1.84, "limit_usd": 8.0, "billed_to": "duun" },
"created_at": "2026-11-15T09:38:12Z"
}
],
"has_more": false,
"next_cursor": null
}List items are full run objects; the example is trimmed.
Retrieve a run
https://api.duun.ai/v1/runs/{run_id} Returns one run. Needs runs:read.
Path parameters
-
run_idstring Required -
The run's id, e.g.
run_7f3aK2pQ.
curl https://api.duun.ai/v1/runs/run_7f3aK2pQ \
-H "Authorization: Bearer $DUUN_API_KEY"const run = await duun.runs.retrieve("run_7f3aK2pQ");run = client.runs.retrieve("run_7f3aK2pQ"){
"id": "run_7f3aK2pQ",
"object": "run",
"title": "Idempotency keys for refund webhooks",
"status": "running",
"factory_id": "fac_platform",
"workflow_id": "wf_base9c1d",
"workflow_revision": 5,
"project_id": "prj_payments",
"issue": { "provider": "linear", "key": "PLT-482", "url": "https://linear.app/acme/issue/PLT-482" },
"agent": "builder",
"current_step": "implement",
"branch": "duun/plt-482-idempotency-keys",
"ask": null,
"pull_request": null,
"cost": { "spent_usd": 2.61, "limit_usd": 8.0, "billed_to": "duun" },
"inputs": {},
"test": false,
"created_at": "2026-11-15T09:38:12Z",
"updated_at": "2026-11-15T10:04:51Z",
"finished_at": null
}Follow run logs
https://api.duun.ai/v1/runs/{run_id}/logs Returns the run’s timeline: step starts and finishes, agent messages, tool calls, commands and their output. With follow=true the connection stays open and streams new entries as server-sent events until the run finishes. Needs runs:read.
Secret values never appear in logs. Commands that used a secret show the variable name instead.
Path parameters
-
run_idstring Required -
The run's id.
Query parameters
-
stepstring Optional -
Only entries from this step id, e.g.
implement. -
sincestring Optional -
ISO 8601 timestamp, or the
idof the last entry you saw. Only later entries are returned. -
followboolean Optional -
Stream new entries as
text/event-streamuntil the run reachessucceeded,failedorcancelled. -
limitinteger Optional -
1–1000. Ignored when
follow=true.
curl -N "https://api.duun.ai/v1/runs/run_7f3aK2pQ/logs?follow=true" \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Accept: text/event-stream"for await (const entry of duun.runs.logs("run_7f3aK2pQ", { follow: true })) {
console.log(`[${entry.step}] ${entry.text}`);
}for entry in client.runs.logs("run_7f3aK2pQ", follow=True):
print(f"[{entry.step}] {entry.text}")event: log
data: {"id":"log_01","object":"log_entry","at":"2026-11-15T09:38:20Z","step":"plan","kind":"step_started","text":"Plan with repo context"}
event: log
data: {"id":"log_02","object":"log_entry","at":"2026-11-15T09:39:02Z","step":"plan","kind":"message","text":"Reading the refund webhook path, the ledger schema and INC-204, INC-219, INC-231."}
event: log
data: {"id":"log_03","object":"log_entry","at":"2026-11-15T09:42:07Z","step":"plan","kind":"ask","text":"Approve the plan","ask_id":"ask_3h2Lm8"}
event: end
data: {"status":"succeeded"}Each entry has id, object: "log_entry", at, step, kind (step_started, step_finished, message, tool_call, command, output, ask, error) and text. Without follow, the response is a normal list of entries.
Resolve an ask
https://api.duun.ai/v1/runs/{run_id}/asks/{ask_id}/resolve Answers whatever the run is waiting on, exactly as the buttons in the Inbox do. The run continues as soon as the ask is resolved. Needs runs:write.
The key must belong to a workspace where the ask’s approver rules allow API resolution; asks that require a specific person (for example a Human step owned by CODEOWNERS) return 403 permission_denied with code approver_required.
Path parameters
-
run_idstring Required -
The run's id.
-
ask_idstring Required -
The open ask, from
run.ask.id.
Body parameters
-
actionenum Required -
What to do. Valid actions depend on the ask kind; see the table below.
-
notestring Optional -
A message for the agent. Required with
request_changes. -
answersarray Optional -
For
answer: a list of{ question_id, answer }. -
amount_usdnumber Optional -
For
approve_onceon a budget ask: how much more this run may spend.
| Ask kind | Inbox button | Valid actions |
|---|---|---|
approve_plan | Approve plan | approve, request_changes, stop |
allow_command | Allow once | allow_once, request_changes, stop |
answer | Send answers | answer, stop |
review_pr | Approve & merge | merge, request_changes, stop |
budget | Approve once | approve_once, stop |
stop cancels the run. To raise a budget for every run it holds, change the budget instead.
curl https://api.duun.ai/v1/runs/run_7f3aK2pQ/asks/ask_3h2Lm8/resolve \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9e2c41d0-7a3b-4c55-8f1e-6d2b0a9c4e17" \
-d '{
"action": "request_changes",
"note": "Split the backfill into its own PR and keep it a dry run."
}'const run = await duun.runs.asks.resolve("run_7f3aK2pQ", "ask_3h2Lm8", {
action: "request_changes",
note: "Split the backfill into its own PR and keep it a dry run.",
});run = client.runs.asks.resolve(
"run_7f3aK2pQ",
"ask_3h2Lm8",
action="request_changes",
note="Split the backfill into its own PR and keep it a dry run.",
){
"id": "run_7f3aK2pQ",
"object": "run",
"status": "running",
"current_step": "plan",
"ask": null,
"updated_at": "2026-11-15T09:51:30Z"
}The response is the full run object; the example is trimmed. Resolving an ask that’s already resolved returns 409 conflict with code ask_resolved. An action that doesn’t fit the ask kind returns 400 invalid_request with param: "action".
Pause a run
https://api.duun.ai/v1/runs/{run_id}/pause Holds the run after its current step, like Pause after this step in the app. The current step finishes; nothing after it starts until you resume. The run’s status becomes waiting once the step ends. Needs runs:write.
Path parameters
-
run_idstring Required -
The run's id.
curl -X POST https://api.duun.ai/v1/runs/run_7f3aK2pQ/pause \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.runs.pause("run_7f3aK2pQ");client.runs.pause("run_7f3aK2pQ"){
"id": "run_7f3aK2pQ",
"object": "run",
"status": "running",
"current_step": "implement",
"updated_at": "2026-11-15T10:06:02Z"
}Pausing a finished run returns 409 conflict with code run_finished.
Resume a run
https://api.duun.ai/v1/runs/{run_id}/resume Continues a run you paused, or one held by a budget once there’s room under the limit. It doesn’t resolve open asks; use Resolve an ask for those. Needs runs:write.
Path parameters
-
run_idstring Required -
The run's id.
curl -X POST https://api.duun.ai/v1/runs/run_7f3aK2pQ/resume \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.runs.resume("run_7f3aK2pQ");client.runs.resume("run_7f3aK2pQ"){
"id": "run_7f3aK2pQ",
"object": "run",
"status": "running",
"current_step": "test",
"updated_at": "2026-11-15T10:20:44Z"
}Resuming a run held by a budget that is still exhausted returns 409 conflict with code budget_exhausted.
Cancel a run
https://api.duun.ai/v1/runs/{run_id}/cancel Stops the run. The agent stops after its current tool call. The worktree and thread are kept, so you can restart later. The response shows the run as it is at that moment; it reaches cancelled within a few seconds. Needs runs:write.
Path parameters
-
run_idstring Required -
The run's id.
curl -X POST https://api.duun.ai/v1/runs/run_7f3aK2pQ/cancel \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.runs.cancel("run_7f3aK2pQ");client.runs.cancel("run_7f3aK2pQ"){
"id": "run_7f3aK2pQ",
"object": "run",
"status": "running",
"current_step": "implement",
"updated_at": "2026-11-15T10:07:15Z",
"finished_at": null
}Cancelling a run that already finished returns 409 conflict with code run_not_cancellable.
Restart a run
https://api.duun.ai/v1/runs/{run_id}/restart Starts a finished, failed or cancelled run again from its first step, on the same branch and the same workflow version. The run keeps its id; its log continues. To use the latest workflow version, create a new run instead. Needs runs:write.
Path parameters
-
run_idstring Required -
The run's id.
curl -X POST https://api.duun.ai/v1/runs/run_7f3aK2pQ/restart \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"const run = await duun.runs.restart("run_7f3aK2pQ");run = client.runs.restart("run_7f3aK2pQ"){
"id": "run_7f3aK2pQ",
"object": "run",
"status": "queued",
"workflow_revision": 5,
"current_step": null,
"updated_at": "2026-11-15T11:02:09Z",
"finished_at": null
}Restarting a run that’s still queued, running or waiting returns 409 conflict with code run_active.
Related
- Approve a plan and Stop, pause or retry a run in the help center
- Webhook events for
run.*andask.*events instead of polling duun runandduun logsin the CLI