SynthClient

SynthClient is the front-door Python client for research products and infrastructure surfaces.

SynthClient is the front-door client for the public synth-ai package.

from synth_ai import SynthClient

client = SynthClient()

Product namespaces

Namespace	Products	Purpose
client.research	Managed Research, Research Factory	Projects, runs, limits, and the research control plane
client.containers	Infrastructure	Hosted container records and lifecycle
client.tunnels	Infrastructure	Tunnel records, leases, heartbeats, refresh, and release
client.pools	Infrastructure	Pools, tasks, rollouts, artifacts, usage, summaries, and events

Managed Research and Research Factory share client.research. Use Managed Research intro for single-run workflows and Research Factory for multi-run programs.

Research example

from synth_ai import SynthClient

client = SynthClient()
research = client.research

for project in research.projects.list():
    print(project.project_id, project.name)

run = research.runs.start(
    "Inspect the repo and leave evidence.",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)
print(run.run_id, run.state)

Install with the research extra: uv add "synth-ai[research]". See Python SDK reference and MCP reference.

Explicit configuration

client = SynthClient(
    api_key="sk_...",
    base_url="https://api.usesynth.ai",
    timeout=30.0,
)

Async client

from synth_ai import AsyncSynthClient

client = AsyncSynthClient()
containers = await client.containers.list()
projects = await client.research.projects.list()

Infrastructure examples

for container in client.containers.list():
    print(container.id, container.name, container.status)

for tunnel in client.tunnels.list():
    print(tunnel)

pools = client.pools.list(limit=10)
print(pools)

For generated reference details, see SynthClient Reference.