Container Pools

Create container pools, launch rollouts, and read rollout artifacts, usage, summaries, and events.

Container pools are reusable task-service targets for hosted optimizer runs. Use a pool when you want GEPA or GELO to run against managed infrastructure instead of a local tunnel or one-off public URL.

Hosted optimizer submits can target a pool directly:

synth-optimizers gepa submit \
  --config gepa.toml \
  --container-pool pool_123 \
  --follow

synth-optimizers gelo submit \
  --preset crafter_smoke \
  --container-pool pool_123 \
  --follow

List container pools

from synth_ai import SynthClient

client = SynthClient()
pools = client.pools.list(limit=20)
print(pools)

Create a container pool

Container pool request shape depends on your runtime adapter and task contract.

pool = client.pools.create(
    {
        "name": "docs-example-pool",
        "target": "arbitrary",
        "tasks": [],
    }
)
pool_id = pool["id"]

Create a rollout

rollout = client.pools.rollouts.create(
    pool_id,
    {
        "messages": [
            {"role": "user", "content": "Summarize this input."}
        ],
        "metadata": {"source": "docs"},
    },
)
rollout_id = rollout["id"]

Read results

status = client.pools.rollouts.get(pool_id, rollout_id)
summary = client.pools.rollouts.summary(pool_id, rollout_id)
artifacts = client.pools.rollouts.artifacts(pool_id, rollout_id)
usage = client.pools.rollouts.usage(pool_id, rollout_id)

for event in client.pools.rollouts.events(pool_id, rollout_id):
    print(event)

CLI

synth-ai pools list
synth-ai pools create --request @pool.json
synth-ai pools rollout-create pool_123 --request @rollout.json
synth-ai pools rollout-summary pool_123 rollout_123
synth-ai pools rollout-artifacts pool_123 rollout_123

Request validation

Rollout requests accept canonical rollout fields only. Unsupported keys fail before the request is sent.