> ## 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.

# Python SDK Reference

> SynthClient().research namespaces, install, and launch patterns.

Install **`synth-ai[research]`** once. Use **`SynthClient().research`** for Managed Research and Research Factory.

```bash theme={null}
uv add "synth-ai[research]==0.13.0"
export SYNTH_API_KEY="sk_..."
```

```python theme={null}
from synth_ai import SynthClient

research = SynthClient().research
```

* [Python SDK Quickstart](/managed-research/sdk-quickstart) — first run end-to-end
* [Auto-generated API reference](/reference/sdk/index) — exhaustive method list from docstrings
* [MCP Tool Reference](/managed-research/mcp-reference) — agent-client parity

## Research namespace layout

| Member                   | Role                                                | API reference                                                          |
| ------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------- |
| `research.projects`      | Create, list, archive projects; setup and workspace | [Projects](/reference/sdk/research/synth_ai-research-projects)         |
| `research.runs`          | Launch, preflight, wait, lifecycle                  | [Runs](/reference/sdk/research/synth_ai-research-runs)                 |
| `research.limits.get()`  | Organization limit snapshot                         | [Limits](/reference/sdk/research/synth_ai-research-limits)             |
| `research.factories.tag` | Factory Tag sessions                                | [Factories](/reference/sdk/research/synth_ai-research-factories)       |
| Run handle readouts      | Usage, progress, queue, artifacts, logs             | [Run readouts](/reference/sdk/research/synth_ai-research-run_readouts) |

Prefer nested readouts on the handle returned from [`runs.get`](/reference/sdk/research/synth_ai-research-runs): `handle.usage.get()`, `handle.snapshots.get()`, `handle.message_queue.messages.send(...)`.

## Typical run flow (hero API)

```python theme={null}
from synth_ai import SynthClient

research = SynthClient().research

project = research.projects.create({"name": "Improve eval reliability", "work_mode": "directed_effort"})
project_id = project.project_id

research.projects.setup.prepare(project_id)

preflight = research.runs.check_preflight(
    project_id=project_id,
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

handle = research.runs.create(
    project_id,
    objective="Kickoff message …",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

research.runs.wait(project_id, handle.run_id)
print(handle.progress.get())
```

## Launch fields

Common launch fields are documented in [Launch Fields](/managed-research/launch-fields). Backend preflight remains authoritative.

## Errors

Launch-time denials raise typed exceptions. See [Errors](/reference/sdk/research/synth_ai-research-errors) and [Preflight and Errors](/managed-research/preflight-and-errors).

## Versioning

Pin **`synth-ai[research]==0.13.0`** for the current hero contract. See [CHANGELOG](https://github.com/synth-laboratories/synth-ai/blob/main/CHANGELOG.md).