Skip to main content
Install synth-ai[research] once. Use SynthClient().research for Managed Research and Research Factory. 
uv add "synth-ai[research]==0.11.2"
export SYNTH_API_KEY="sk_..."

from synth_ai import SynthClient

research = SynthClient().research
Use Python SDK Quickstart for a first run. Use MCP Tool Reference for agent-client parity.

​
Research namespace layout

MemberRole
research.projectsList and create runnable projects; onboarding/setup helpers
research.runsStart runs, launch preflight, runbook presets, trigger compatibility
research.get_limits()Organization limit snapshot
research.control()Low-level control-plane session (ReportBench / full launch drivers)
Run handles returned from research.runs.start support wait, messages, artifacts, task_counts, checkpoints, branches, and usage readback.

​
Typical run flow

from synth_ai import SynthClient

research = SynthClient().research

created = research.projects.create_runnable({"name": "Improve eval reliability"})
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",
)

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

​
Launch fields

Common launch fields are documented in Launch Fields. Backend preflight remains authoritative. 
run = research.runs.start(
    "Review the repo and leave evidence.",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
    agent_harness="codex",
    agent_model="gpt-5.4-mini",
    agent_model_params={"reasoning_effort": "medium"},
)

​
Advanced: ManagedResearchClient

ManagedResearchClient remains available for low-level control-plane access (full MCP parity, project bindings, exports). Prefer SynthClient().research for new code. 
from synth_ai import ManagedResearchClient

with ManagedResearchClient() as client:
    entitlements = client.get_billing_entitlements()
    usage = client.get_project_usage("proj_…")

​
Errors

Launch-time denials raise typed exceptions instead of success-shaped payloads. Use research.runs.launch_preflight when you need structured blocker data before runtime spend. See Preflight and Errors.

​
Versioning

Pin synth-ai[research]==0.11.2 for the launch contract. See CHANGELOG for breaking changes from 0.11.1.