> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dagraph.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List dagraph runs and resume incomplete ones quickly

> Audit all dagraph runs in your runs directory with status filtering, and resume paused or interrupted runs without re-running completed nodes.

`agentgraph list` gives you a table of every run in your runs directory, with status, DAG name, start time, and a node count breakdown. `agentgraph resume` is a shorthand that continues a run from where it left off — useful after an approval gate is cleared or after a crash.

<Tabs>
  <Tab title="list">
    ## agentgraph list

    List all runs in the runs directory, ordered by most recent first.

    ```
    agentgraph list [OPTIONS]
    ```

    ### Flags

    <ParamField path="--runs-dir" type="string" default="runs">
      Directory containing run subdirectories to scan.
    </ParamField>

    <ParamField path="--status" type="string">
      Filter results to runs matching a derived status. Options: `completed`, `paused`, `partial`, `failed`.
    </ParamField>

    <ParamField path="--limit" type="number" default="20">
      Maximum number of rows to display.
    </ParamField>

    ### Examples

    <CodeGroup>
      ```bash List all recent runs theme={null}
      agentgraph list
      ```

      ```bash List only paused runs theme={null}
      agentgraph list --status paused
      ```

      ```bash List failed runs, show up to 50 theme={null}
      agentgraph list --status failed --limit 50
      ```

      ```bash Custom runs directory theme={null}
      agentgraph list --runs-dir /data/production-runs
      ```
    </CodeGroup>

    ### Output table

    `list` prints a table with one row per run:

    | Column  | Contents                                         |
    | ------- | ------------------------------------------------ |
    | run\_id | 12-character hex run identifier                  |
    | dag     | DAG name as declared in the YAML `name:` field   |
    | started | ISO 8601 timestamp when the run began            |
    | status  | Derived status (see below)                       |
    | nodes   | Node status counts, e.g. `completed=3, failed=1` |

    ### Status derivation

    agentgraph derives run status from the node table at list time — there is no separate run-level status field:

    | Derived status | Condition                                                      |
    | -------------- | -------------------------------------------------------------- |
    | `paused`       | At least one node is `awaiting_approval`                       |
    | `failed`       | At least one node is `failed` (and none are awaiting approval) |
    | `completed`    | Run has a `finished_at` timestamp set                          |
    | `partial`      | None of the above — run stopped mid-way without a clean finish |
  </Tab>

  <Tab title="resume">
    ## agentgraph resume

    Resume a paused or partial run. This is syntactic sugar for `agentgraph run <dag_path> --run-id <run_id>` — the scheduler skips all nodes that already have a `completed` status and re-runs only the pending, failed, or newly unblocked nodes.

    ```
    agentgraph resume <dag_path> <run_id> [OPTIONS]
    ```

    ### Arguments and flags

    <ParamField path="dag_path" type="string" required>
      Path to the DAG YAML file that was originally executed.
    </ParamField>

    <ParamField path="run_id" type="string" required>
      Run ID of the run to resume.
    </ParamField>

    <ParamField path="--input / -i" type="string">
      Override or supplement template inputs. Original inputs are replayed from the checkpoint; use this flag only if you need to change a value.
    </ParamField>

    <ParamField path="--runs-dir" type="string" default="runs">
      Runs directory.
    </ParamField>

    <ParamField path="--backend" type="string" default="claude_code">
      Executor backend. See [`agentgraph run`](/cli/run) for options.
    </ParamField>

    <ParamField path="--sandbox" type="string">
      Sandbox for exec nodes. Required if your DAG contains `bash` or `python_exec` nodes.
    </ParamField>

    ### Examples

    <CodeGroup>
      ```bash Resume after an approval gate was cleared theme={null}
      agentgraph resume examples/approval_flow.yaml a1b2c3d4e5f6
      ```

      ```bash Resume a crashed run with a different backend theme={null}
      agentgraph resume examples/research.yaml a1b2c3d4e5f6 --backend api
      ```

      ```bash Resume and override an input theme={null}
      agentgraph resume examples/research.yaml a1b2c3d4e5f6 \
        --input topic="updated topic"
      ```
    </CodeGroup>

    ### Common resume workflow

    <Steps>
      <Step title="Find a paused run">
        ```bash theme={null}
        agentgraph list --status paused
        ```
      </Step>

      <Step title="Clear the gate">
        ```bash theme={null}
        agentgraph approve <run_id> <node_id>
        ```
      </Step>

      <Step title="Resume execution">
        ```bash theme={null}
        agentgraph resume examples/my_dag.yaml <run_id>
        ```

        Only nodes that did not complete previously will execute.
      </Step>
    </Steps>

    <Tip>
      `resume` and `run --run-id` are identical in behavior. Use `resume` when you want the intent to be explicit in scripts and shell history.
    </Tip>
  </Tab>
</Tabs>