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

FieldTypeDescription
idstringUnique id, prefixed run_.
objectstringAlways "run".
titlestringShort title, usually from the issue or prompt.
statusenumqueued, running, waiting (an ask is open), succeeded, failed or cancelled.
factory_idstringThe factory the run belongs to.
workflow_idstringThe workflow it follows.
workflow_revisionintegerThe workflow version it’s bound to.
project_idstring | nullThe project its work counts towards, if any.
issueobject | nullThe issue it works on: provider (linear, github or jira), key and url.
agentstringThe agent doing the current step’s work, by name.
current_stepstring | nullThe id of the step in progress, or the last step for finished runs.
branchstringThe run’s branch. Every run works in its own worktree.
askobject | nullThe open ask, if status is waiting: id, kind (approve_plan, allow_command, answer, review_pr or budget), title, created_at.
pull_requestobject | nullThe run’s pull request once opened: number, url, state (open, merged or closed).
costobjectspent_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).
inputsobjectRun inputs passed at start, available to steps as {{input.*}}.
testbooleantrue for test runs started from a workflow’s Test.
created_atstringWhen the run was created.
updated_atstringWhen anything about the run last changed.
finished_atstring | nullWhen it reached succeeded, failed or cancelled.
Run
{
  "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

StatusMeaning
queuedCreated, waiting for a free slot (the workflow’s Concurrent runs limit) or a machine.
runningA step is in progress.
waitingAn 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.
succeededThe workflow finished.
failedA step failed after its retries, or the run hit its timeout.
cancelledSomeone cancelled it. The worktree and thread are kept, so it can be restarted.

Endpoints

Create a run

POST 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_id string Required

The factory to run in, e.g. fac_platform.

workflow_id string Optional

A workflow in that factory. Defaults to the factory's default workflow.

prompt string Optional

What to do, in plain language. Becomes the first message of the run's conversation.

issue_url string 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.*}}.

inputs object Optional

Values for the workflow's run inputs, keyed by input key. Unknown keys return 400.

project_id string Optional

Count the run towards a project. Defaults to the factory's project.

title string 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 queued
from 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
Response
{
  "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 conflict with code factory_paused or workflow_paused: resume it first, or start the run in the app.
  • 409 conflict with code manual_trigger_off: turn on the workflow’s Manual trigger.
  • 409 conflict with code budget_exhausted: a budget or the credit balance can’t cover a new run. The message names the binding budget. See Usage and budgets.

List runs

GET https://api.duun.ai/v1/runs

Returns runs, newest first. Needs runs:read.

Query parameters

status enum Optional

Only runs in this status.

One of queued running waiting succeeded failed cancelled

factory_id string Optional

Only runs in this factory.

workflow_id string Optional

Only runs of this workflow.

project_id string Optional

Only runs in this project.

created_after string Optional

ISO 8601 timestamp. Only runs created after it.

created_before string Optional

ISO 8601 timestamp. Only runs created before it.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from 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)
Response
{
  "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

GET https://api.duun.ai/v1/runs/{run_id}

Returns one run. Needs runs:read.

Path parameters

run_id string 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")
Response
{
  "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

GET 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_id string Required

The run's id.

Query parameters

step string Optional

Only entries from this step id, e.g. implement.

since string Optional

ISO 8601 timestamp, or the id of the last entry you saw. Only later entries are returned.

follow boolean Optional

Stream new entries as text/event-stream until the run reaches succeeded, failed or cancelled.

Default false

limit integer Optional

1–1000. Ignored when follow=true.

Default 100

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}")
Response (follow=true)
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

POST 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_id string Required

The run's id.

ask_id string Required

The open ask, from run.ask.id.

Body parameters

action enum Required

What to do. Valid actions depend on the ask kind; see the table below.

One of approve request_changes allow_once answer merge approve_once stop

note string Optional

A message for the agent. Required with request_changes.

answers array Optional

For answer: a list of { question_id, answer }.

amount_usd number Optional

For approve_once on a budget ask: how much more this run may spend.

Ask kindInbox buttonValid actions
approve_planApprove planapprove, request_changes, stop
allow_commandAllow onceallow_once, request_changes, stop
answerSend answersanswer, stop
review_prApprove & mergemerge, request_changes, stop
budgetApprove onceapprove_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.",
)
Response
{
  "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

POST 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_id string 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")
Response
{
  "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

POST 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_id string 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")
Response
{
  "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

POST 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_id string 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")
Response
{
  "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

POST 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_id string 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")
Response
{
  "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.

    Type to search the docs, help center and blog.