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

# Managed Research Quickstart

> Start one hosted research run, then read back state and artifacts.

This quickstart starts a one-off Managed Research run and reads back the evidence it leaves behind. Use MCP when an agent client is driving the workflow. Use Python when you want a repeatable script.

Install once: **`synth-ai[research]`** with **`SynthClient().research`**. Managed Research and Research Factory share that surface.

## Prerequisites

* A [Synth account](https://usesynth.ai/signup?product=managed-research).
* A `SYNTH_API_KEY`.
* A repo or research target the worker can inspect.

## Start a one-off run

<Tabs>
  <Tab title="MCP">
    ```bash theme={null}
    codex mcp add managed-research --url https://api.usesynth.ai/mcp
    ```

    Ask your MCP client:

    ```text theme={null}
    Start a Managed Research one-off run with directed effort mode.
    Use host_kind daytona, provider openrouter, runbook lite, and this message:
    "Inspect the repo context, propose the smallest high-impact improvement, and leave evidence."
    ```
  </Tab>

  <Tab title="Python">
    ```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

    run = research.runs.start(
        "Inspect the repo context, propose the smallest high-impact improvement, and leave evidence.",
        host_kind="daytona",
        work_mode="directed_effort",
        providers=[{"provider": "openrouter"}],
        runbook="lite",
    )

    print("project:", run.project_id)
    print("run:", run.run_id)
    ```
  </Tab>
</Tabs>

## Inspect the run

<Tabs>
  <Tab title="MCP">
    Ask your MCP client:

    ```text theme={null}
    Show the latest Managed Research run state, messages, task counts, artifact manifest, and usage.
    ```

    Useful tools include `smr_get_run`, `smr_get_run_execution`, `smr_get_run_transcript`, `smr_list_run_artifacts`, `smr_get_artifact_content`, `smr_list_run_actor_logs`, and `smr_get_run_usage`.
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    result = run.wait(timeout=60 * 60, poll_interval=15)

    print("state:", result.state.value)
    print("stop reason:", result.stop_reason_message or result.stop_reason)
    print("tasks:", run.task_counts())
    print("actors:", run.actor_counts())

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

    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)
    ```
  </Tab>
</Tabs>

Runs normally move through `queued`, `planning`, `executing`, and `finalizing`
before reaching `done`. Terminal outcomes include `done`, `failed`, `blocked`,
or a stopped state when a budget, timeout, operator action, or launch/runtime
policy ends the run. Treat a terminal state as stable: inspect the stop reason,
artifact manifest, usage, and final report before starting follow-up work.

## Use a project when context matters

Projects are reusable control units for repos, files, datasets, credentials, notes, budgets, and project knowledge.

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

research = SynthClient().research

created = research.projects.create_runnable({"name": "Improve my eval runner"})
project_id = created.project_id

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

if not preflight.get("clear_to_trigger"):
    raise RuntimeError(preflight.get("resolution_reason") or "Run is not ready to start")

run = research.runs.start(
    "Inspect the eval runner, fix the highest-leverage issue, and explain the evidence.",
    project_id=project_id,
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)
```

Attach repos, credentials, and files in the [web console](/managed-research/projects-and-context#using-projects-in-the-web-app-logged-in) or via MCP (`smr_attach_source_repo`, `smr_work_repos_attach`, provider key tools).

## Limits and launch denials

Free plans include one-time Managed Research credits, `lite` runbooks,
`directed_effort`, standard model access, and one active run at a time. Beta
Access can unlock `heavy`, `open_ended_discovery`, and all-model access on top
of the base plan. Pro and Team plans add higher included usage and higher active
run limits.

Use preflight before launching when you want structured blockers without
spending runtime. A **402** response usually means credit or budget headroom is not
available. A **429** response usually means a rate, capacity, or concurrent-run cap
is active. User-fixable denials should name the blocking resource, such as
credits, `agent_codex`, `sandbox`, active-run capacity, unsupported harness,
unsupported model, or missing provider credentials.

See [Preflight and Errors](/managed-research/preflight-and-errors).

## What just happened

Synth provisioned a hosted workspace, gave workers the launch message and project context, tracked durable run state, and exposed the evidence stream for review.

Next, choose the detailed path:

* [MCP Quickstart](/managed-research/mcp-quickstart)
* [Python SDK Quickstart](/managed-research/sdk-quickstart)
* [Launch Fields](/managed-research/launch-fields)
* [Runs and Evidence](/managed-research/runs-and-evidence)