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

# Runs

> Create, list, monitor, and inspect LoomLoom workflow runs.

A `runId` identifies one hosted workflow execution. Preserve it exactly from an official-template, private-template, or Market submission response.

## Create an official-template run from rows

The CLI separates preparation from execution:

```bash theme={null}
loomloom run validate <template-id> --file ./rows.jsonl
loomloom run precheck <template-id> --file ./rows.jsonl
# Show the estimate and wait for explicit confirmation.
loomloom run execute <template-id> --file ./rows.jsonl \
  --client-request-id <new-id>
```

`run execute` is the current command for new integrations. The older combined `run submit` flow is hidden.

## List and inspect

```bash theme={null}
loomloom run list
loomloom run list --status running --page-size 20 --output json
loomloom run get <run-id> --output json
```

`run list` supports `--status`, `--page-size`, `--page-token`, and ordering by `createdAt` or `updatedAt` in ascending or descending order.

## Watch progress

```bash theme={null}
loomloom run watch <run-id>
loomloom run watch <run-id> --interval 10s --max-wait 30m
```

Without `--max-wait`, watch continues until a terminal status. Recognized terminal statuses are `completed`, `failed`, `partially_failed`, and `cancelled`/`canceled`.

## Read results

```bash theme={null}
loomloom run result-rows <run-id> --page-size 50
loomloom run result-workbook <run-id> --output-file ./result.xlsx
```

`result-rows` joins persisted input snapshots with row results and supports page tokens. `result-workbook` downloads the server-generated workbook containing original inputs and results.

<Tip>
  Prefer `result-workbook` for workbook workflows. It is generated from the server-side input snapshot and result data.
</Tip>

Do not construct a console URL from a `runId`; no stable run-detail URL format is published. Use the CLI unless the service explicitly returns a URL.

## Retry safely

After an ambiguous execution failure, query the run or related usage record before retrying. Reuse the original `--client-request-id` only for the identical confirmed payload. A changed input or new confirmation requires a new ID.