Skip to main content
Use this page as the quick map for container execution surfaces in Synth.
SDK version note The client mapping shown here assumes synth-ai>=0.11.0.

​
Mental model

There are two different runtime surfaces:
SurfacePrimary useCore paths
Hosted containers CRUDManage container records and metadata/v1/containers/*
Container pools + rolloutsRun repeatable tasks/rollouts and consume artifacts/usage/v1/pools/*, /v1/rollouts/*
Managed Agents are separate and live under:
  • /api/managed-agents/anthropic/v1/*

​
SDK mapping (synth-ai)

SDK clientIntended use
client.containersHosted container CRUD
client.pools / client.horizons_privatePools, tasks, rollouts, artifacts, usage
client.managed_agentsAnthropic-compatible managed-agents via backend BFF

​
Example: list pools

from synth_ai import SynthClient

client = SynthClient(api_key="sk_...")
print(client.pools.list())

​
Example: list containers

from synth_ai import SynthClient

client = SynthClient(api_key="sk_...")
print(client.containers.list())

​
End-to-end container pools example

Use this sequence for a minimal pool-to-rollout flow. 
from synth_ai import SynthClient

client = SynthClient(api_key="sk_...")

# 1) Create a pool (shape depends on your adapter/runtime config)
pool = client.horizons_private.create_runtime(
    {
        "name": "docs-container-pool",
        "target": "horizons_private",
        "adapter": "openai_review",
        "tasks": [],
    }
)
pool_id = pool["pool_id"]

# 2) Launch a rollout against that pool
rollout = client.horizons_private.create_session(
    pool_id,
    {"input": {"prompt": "summarize this code change"}},
)
rollout_id = rollout.get("rollout_id") or rollout.get("id")

# 3) Read rollout status/events/artifacts/usage
status = client.horizons_private.get(pool_id, rollout_id)
events = list(client.horizons_private.events(pool_id, rollout_id))
artifacts = client.horizons_private.artifacts(pool_id, rollout_id)
usage = client.horizons_private.usage(pool_id, rollout_id)

print(status.get("status"), len(events), usage)

​
Common rollout errors

SymptomLikely cause
401/403invalid/missing SYNTH_API_KEY
404 pool not foundwrong pool_id or cross-org resource
404 rollout not foundwrong rollout_id
409 or capacity-style failureorg/pool concurrent rollout limit reached
artifacts endpoint emptyrollout not completed yet

​
Common confusion to avoid

  • client.managed_agents is not a pools/rollouts API.
  • Pools/rollouts are not the Anthropic-compatible managed-agents session APIs.
  • Keep endpoint families separate in docs, code samples, and production runbooks.