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

# Runs and Evidence

> Inspect run state, messages, tasks, actors, artifacts, checkpoints, usage, reports, and PRs.

Managed Research runs are designed to leave a reviewable trail.

## Launch and state types

`ResearchRunLaunchRequest` is the released typed launch request.
`ResearchSwarm` is the state model returned by swarm state and wait operations.
Import both from the public Research namespace:

```python theme={null}
from synth_ai.research import ResearchRunLaunchRequest, ResearchSwarm
```

Most applications launch and inspect runs through `SynthClient().research`;
use these models when a typed application boundary needs to construct a launch
request or annotate a returned swarm without adding low-level transport code.

## State flow

Runs usually move through:

```text theme={null}
queued -> planning -> executing -> finalizing -> done
                         |             |
                         v             v
                      blocked        failed
```

A run may also stop because of budget, timeout, operator action, or launch/runtime failure.

## Status and messages

Use status reads for current state and messages for durable communication with the runtime.

MCP tools:

* `smr_get_run`
* `smr_get_run_execution`
* `smr_get_run_transcript`
* `smr_list_run_actor_logs`

Python:

```python theme={null}
result = run.wait(timeout=60 * 60, poll_interval=15)
print(result.state.value)

for message in run.messages(limit=20):
    print(message.get("role"), message.get("status"), message.get("body", "")[:120])
```

## Tasks and actors

Task and actor counts help show what the system actually did.

```python theme={null}
print("tasks:", run.task_counts())
print("actors:", run.actor_counts())
```

## Artifacts and reports

Artifacts include reports, files, diffs, PR metadata, logs, and workflow-specific outputs.

```python theme={null}
manifest = run.artifact_manifest()
print("output files:", [artifact.path for artifact in manifest.output_files])

for artifact in run.artifacts():
    print(artifact.artifact_id, artifact.artifact_type, artifact.title)
```

MCP tools:

* `smr_list_run_artifacts`
* `smr_get_run_artifact_manifest`
* `smr_get_artifact_content`

## Checkpoints and branches

Use checkpoints before riskier changes or when a long run finds a useful intermediate state.

```python theme={null}
checkpoint = run.create_checkpoint(reason="before trying a riskier refactor")
retry = run.branch_from_checkpoint(
    checkpoint_id=checkpoint.checkpoint_id,
    mode="with_message",
    message="Try again from this checkpoint with a smaller patch.",
)
```

## Usage

Usage readback helps connect the evidence to spend and budgets. Use `smr_get_run_usage`, `smr_get_project_usage`, and resource-limit progress tools from MCP, or `handle.usage.get()` / `client.research.limits.get()` from the [hero Python SDK](/managed-research/sdk).

Hard stops can come from run budget, monthly budget, timebox, or policy blockers.