---
title: "Run jobs"
description: "Start an agent, follow it, cancel it and list what ran."
canonical_url: "https://docs.oz0.ai/agents/run-jobs"
---
# Run jobs

> Start an agent, follow it, cancel it and list what ran.

For: people running and reviewing agents.

Use `run` to start one run of an agent. The command waits for its answer:

```bash [Terminal]
oz0 run acme-reviewer "Review PR 42 in acme/api"    # text input
oz0 run acme-reviewer '{"repo": "acme/api", "pr": 42}' # JSON, for agents with an input schema
echo "Review PR 42" | oz0 run acme-reviewer -       # input from stdin
```

The answer goes to stdout. Everything else goes to stderr, so you can pipe the answer on: while the job runs, what its agents write and the tools they call, child jobs on other nodes included, and at the end what the job cost, one row per job in its tree.

```text
lead → oz.delegate {"agent":"helper","task":"Please greet Ada"}
lead ⇢ helper (job job-1746aef4-.../helper-8c872bc6)
helper → team.hello {"name":"Ada"}
helper ← team.hello Hello, Ada!
helper: Done: Hello, Ada!
lead ← oz.delegate Done: Hello, Ada!
lead: Done. Ada has been greeted.
```

`→` is a tool call, `←` its result, `⇢` a child job and `name:` what an agent writes. `--quiet` turns the live output off.

`run` also runs [flows](https://docs.oz0.ai/build/parts/flows), by name: their tool steps, agent steps and approvals show up the same way.

## Don't wait

```bash [Terminal]
oz0 run acme-reviewer --detach "Review PR 42 in acme/api" # prints the job ID and returns
oz0 job watch <job-id>                                 # follow it live until it ends
oz0 job get <job-id>                                   # status, answer and cost per branch
```

Jobs are durable. If you stop waiting, with Ctrl+C or `--wait 30s`, the job keeps running; follow it again with `job watch`, or check it with `job get`.

## Choose the ID

```bash [Terminal]
oz0 run acme-reviewer --id pr-42-review "Review PR 42 in acme/api"
```

Starting a job under an ID you chose is safe to retry: the same request under the same ID answers with the job it started, showing what `GetJob` shows you now, so a label the job took since closes what it would close there.

Any other start under an ID a job holds is refused with `already_exists`, a job with no start recorded to compare with included.

IDs may not contain `/`, which separates a job from its children, nor `\` or `"`: Temporal's visibility, which finds a job's children, matches no ID that has one.

Control characters (NUL, line breaks, tabs and the like) are refused for the same reason, since retention and erasure find a job's runs by asking Temporal for its ID; a start through the Temporal proxy, and a schedule's action, are held to these two rules as well.

The prefixes the platform names its own jobs with are refused too, so nobody starts a job ahead of the platform under the ID it will use: `rt.` (routines' fires), `evs.`, `kp.`, `jdg.`, `cmp.`, `rpl.`, `shadow-`, `ev.`, `event-`, `ch.`, `channel-`, `gate-` (quality gates' eval cases) and `hook-` (flow webhooks' deliveries).

## Limit it

```bash [Terminal]
oz0 run acme-reviewer --timeout 15m "..."
oz0 run acme-reviewer --budget 0.50 "..."
```

`--timeout` limits the whole job on top of the agent's own limits. `--budget` caps what the job and the jobs it delegates to may spend on model calls, in US dollars; see [budgets](https://docs.oz0.ai/build/parts/contracts-and-limits/budgets#budgets).

## List and cancel

```bash [Terminal]
oz0 job list                  # recent top-level jobs, newest first
oz0 job list --limit 50 --tenant acme
oz0 job cancel <job-id> --reason "wrong PR"
```

Cancelling a job cancels the jobs it delegated to as well. The reason goes into the job's history.

A cancel stops a tool call where it runs: a running call reports to Temporal every second, so the cancel reaches it within seconds (a node that stops reporting for 15 seconds loses the call), and the node then cancels it at its tool server, which hears MCP's `notifications/cancelled`, and stops the job's own sandboxed server.

Until the call has stopped, `job get` says `cancelling (a call is being stopped at its tool)` and the console shows **cancelling**; the job is `CANCELED` only after.

A tool server that ignores the cancel cannot be stopped this way on a shared server: see [cancels and the idempotency key](https://docs.oz0.ai/build/parts/tools/call-lifecycle#cancels-time-limits-and-the-idempotency-key). A call that runs past its tool's `timeout` is cancelled at the tool the same way.

## A job's states

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        RUNNING
      </code>
    </td>
    
    <td>
      A node is working on it, or it waits for one
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        COMPLETED
      </code>
    </td>
    
    <td>
      It has an answer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        FAILED
      </code>
    </td>
    
    <td>
      It ended with an error, such as <code>
        InvalidInput
      </code>
      
       or a limit reached
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CANCELED
      </code>
    </td>
    
    <td>
      Someone cancelled it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TIMED_OUT
      </code>
    </td>
    
    <td>
      It ran out of time
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TERMINATED
      </code>
    </td>
    
    <td>
      It was stopped without cleanup
    </td>
  </tr>
</tbody>
</table>

## Follow-up questions

`oz0 run --continue JOB "..."` asks a follow-up: the new job is the next turn of a conversation and gets the earlier turns, and `oz0 chat AGENT` does it in a loop. See [conversations](https://docs.oz0.ai/agents/conversations).

## From apps

Apps start and follow jobs through the [runtime API](https://docs.oz0.ai/build/apps/runtime-api) on the edge, the same API the CLI uses.

Jobs also start without anyone running a command: [routines](https://docs.oz0.ai/build/parts/routines) fire an agent or a flow on a schedule, a webhook or an event, a [flow's webhook](https://docs.oz0.ai/build/parts/flows#start-one-from-a-webhook) starts it with the request's body, and [MCP and A2A clients](https://docs.oz0.ai/build/apps/mcp-server) start jobs as tasks.


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
