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

# Runs

`client.runs` is the shared run API for workflow, agent, manual, and eval runs.

## Start

```python theme={null}
started = client.run("workflows.extract-invoice", input={})
```

For short jobs, ask the server to hold the request:

```python theme={null}
result = client.run(
    "workflows.extract-invoice",
    input={},
    wait_for_completion=60,
)
```

For longer jobs, use `client.run_and_wait` or poll manually:

```python theme={null}
final = client.run_and_wait("agents.invoice-agent", input={})
```

## Get

```python theme={null}
run = client.runs.get(started.id)
# { id, type, finished, execution, output?, files?, error?, timing, ... }
```

Add heavier optional sections with `expand`:

```python theme={null}
run = client.runs.get(started.id, expand=["usage", "execution"])
print(run.output, run.usage, run.execution)
```

## List

```python theme={null}
listing = client.runs.list(
    type="workflow",
    status="failed,cancelled",
    limit=50,
)
```

## Subresources

```python theme={null}
client.runs.usage(started.id)
client.runs.steps(started.id)
client.runs.events(started.id)
client.runs.trace.get(started.id)
client.runs.reviews.get(started.id)
client.runs.reviews.update(started.id, {"note": "Looks wrong", "verdict": "incorrect", "status": "open"})
```

## Artifacts

```python theme={null}
artifacts = client.runs.artifacts.list(started.id)
content = client.runs.artifacts.download(started.id, artifacts.artifacts[0].path)
```

Artifacts are run-scoped snapshots. Reusable uploaded files are managed separately through `client.files`.

## Cancel And Rerun

```python theme={null}
client.runs.cancel(started.id)
rerun = client.rerun(started.id, wait_for_completion=60)
```

## Promote

Copy a completed run's input, output, review, and corrected artifacts into a dataset example on the same automation:

```python theme={null}
result = client.runs.promote(started.id, name="golden-invoice")
print(result.example_id, result.name)
```