ContainerPoolsClient

synth_ai.sdk.pools

Container pools, tasks, rollouts, metrics, artifacts, usage, and events.

Access this API through SynthClient().pools. Prefer its task-oriented namespaces:

• pools.rollouts for rollouts scoped to one pool.
• pools.agent_rollouts for global rollouts.
• pools.tasks for pool task definitions.
• pools.metrics for pool utilization.

Lower-level methods remain available through the pools.raw client. Request and response bodies are backend-owned JSON objects. Rollout creation through either the task-oriented namespaces or their lower-level implementations validates a closed set of request keys. Other raw methods pass backend contracts through without fabricating a second schema authority.

Example:

from synth_ai import SynthClient

client = SynthClient()
try:
    page = client.pools.list(limit=20)
    for pool in page.get("items", []):
        metrics = client.pools.metrics.get(pool["id"])
        print(pool["id"], metrics)
finally:
    client.pools.close()

Expected output:

Expected output is one line per pool containing its stable ID and the service-owned metrics object. An organization with no pools returns an empty items list.

Pagination:

limit defaults to 100. Pagination is backend-owned: continue only when a response supplies a distinct continuation token such as next_cursor. The current production service may omit a continuation or echo the supplied cursor; stop in either case to avoid a loop.

Errors:

The four rollout-creation entry points named above reject unsupported keys locally with ValueError. Service failures raise httpx.HTTPStatusError. Inspect error.response.status_code to distinguish authentication, authorization, validation, capacity, and transient service failures.

Functions

validate_pool_rollout_request

validate_pool_rollout_request(request: dict[str, Any]) -> None

Reject rollout payloads with non-canonical keys.

Classes

PoolTarget

Deployment target substrate for a pool.

ContainerPoolsClient

Manage container pools, tasks, rollouts, and metrics.

Args:

• api_key: Synth API key. Defaults to SYNTH_API_KEY.
• backend_base: Preferred API base URL override.
• base_url: Compatibility alias for backend_base.
• timeout: Default request timeout in seconds. Defaults to 30.
• timeout_seconds: Preferred timeout override. When supplied, it takes precedence over timeout.

Attributes:

• rollouts: Pool-scoped rollout operations.
• agent_rollouts: Global rollout operations.
• tasks: Pool task operations.
• metrics: Pool utilization reads.

Raises:

• ValueError: The API key is missing or a rollout request contains a non-canonical key.
• httpx.HTTPStatusError: The service rejects an operation.

Methods:

raw

raw(self) -> ContainerPoolsClient

Return self for advanced raw HTTP access.

create_pool

create_pool(self, request: dict[str, Any]) -> dict[str, Any]

Create one container pool.

Args:

• request: Backend-owned pool definition. Use fields documented by the active pool API contract.

Returns:

• The created pool JSON object, including its service-assigned ID.

Raises:

• httpx.HTTPStatusError: Authentication, authorization, validation, conflict, quota, or service errors.

create

create(self, request: dict[str, Any]) -> dict[str, Any]

Create a container pool (alias for create_pool).

list_pools

list_pools(self, *, state: str | None = None, limit: int = 100, cursor: str | None = None) -> dict[str, Any]

List container pools with cursor pagination.

Args:

• state: Optional service-owned lifecycle-state filter. Defaults to no state filter.
• limit: Maximum page size. Defaults to 100.
• cursor: Backend-owned continuation token. Defaults to None.

Returns:

• The backend page object. Stop if its continuation is missing or unchanged.

Raises:

• httpx.HTTPStatusError: The request is rejected.

list

list(self, *, state: str | None = None, limit: int = 100, cursor: str | None = None) -> dict[str, Any]

List container pools (alias for list_pools).

get_pool

get_pool(self, pool_id: str) -> dict[str, Any]

Retrieve one pool by ID.

Args:

• pool_id: Stable ID returned by create_pool or list_pools.

Returns:

• The current pool JSON object.

Raises:

• httpx.HTTPStatusError: The pool is unavailable or the request is rejected.

get

get(self, pool_id: str) -> dict[str, Any]

Retrieve a pool by id (alias for get_pool).

replace_pool

replace_pool(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Replace a pool definition.

replace

replace(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Replace a pool definition (alias for replace_pool).

update_pool

update_pool(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Patch-update a pool definition.

update

update(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Patch-update a pool (alias for update_pool).

delete_pool

delete_pool(self, pool_id: str) -> dict[str, Any]

Delete a pool by id.

delete

delete(self, pool_id: str) -> dict[str, Any]

Delete a pool by id (alias for delete_pool).

get_pool_urls

get_pool_urls(self, pool_id: str) -> dict[str, Any]

Return rollout URLs for a pool.

get_urls

get_urls(self, pool_id: str) -> dict[str, Any]

Return rollout URLs (alias for get_pool_urls).

get_pool_metrics

get_pool_metrics(self, pool_id: str) -> dict[str, Any]

Return utilization metrics for a pool.

list_tasks

list_tasks(self, pool_id: str) -> dict[str, Any]

List tasks configured on a pool.

create_task

create_task(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Create a task on a pool.

update_task

update_task(self, pool_id: str, task_id: str, request: dict[str, Any]) -> dict[str, Any]

Replace a pool task definition.

patch_task

patch_task(self, pool_id: str, task_id: str, request: dict[str, Any]) -> dict[str, Any]

Patch-update a pool task.

delete_task

delete_task(self, pool_id: str, task_id: str) -> dict[str, Any]

Delete a pool task.

create_rollout

create_rollout(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Start one rollout on a pool.

Args:

• pool_id: Target pool ID.
• request: Rollout request using only CANONICAL_ROLLOUT_REQUEST_KEYS.

Returns:

• The created rollout JSON object.

Raises:

• ValueError: request contains a non-canonical key.
• httpx.HTTPStatusError: The pool cannot accept the rollout or the request is rejected.

get_rollout

get_rollout(self, pool_id: str, rollout_id: str) -> dict[str, Any]

Fetch rollout state for a pool.

list_rollouts

list_rollouts(self, pool_id: str, *, state: str | None = None, limit: int = 100, cursor: str | None = None) -> dict[str, Any]

List rollouts for one pool.

Args:

• pool_id: Target pool ID.
• state: Optional service-owned lifecycle-state filter. Defaults to no state filter.
• limit: Maximum page size. Defaults to 100.
• cursor: Backend-owned continuation token. Defaults to None.

Returns:

• The backend page object. Stop if its continuation is missing or unchanged.

Raises:

• httpx.HTTPStatusError: The request is rejected.

cancel_rollout

cancel_rollout(self, pool_id: str, rollout_id: str) -> dict[str, Any]

Cancel an in-flight pool rollout.

get_rollout_artifacts

get_rollout_artifacts(self, pool_id: str, rollout_id: str) -> dict[str, Any]

List artifacts produced by a pool rollout.

get_rollout_usage

get_rollout_usage(self, pool_id: str, rollout_id: str) -> dict[str, Any]

Return usage totals for a pool rollout.

get_rollout_summary

get_rollout_summary(self, pool_id: str, rollout_id: str) -> dict[str, Any]

Return a summary document for a pool rollout.

stream_rollout_events

stream_rollout_events(self, pool_id: str, rollout_id: str, *, cursor: str | None = None) -> Iterator[dict[str, Any]]

Stream rollout events for a pool.

create_global_rollout

create_global_rollout(self, request: dict[str, Any]) -> dict[str, Any]

Start a global (non-pool-scoped) rollout.

list_global_rollouts

list_global_rollouts(self, *, state: str | None = None, limit: int = 100, cursor: str | None = None) -> dict[str, Any]

List global rollouts.

get_global_rollout

get_global_rollout(self, rollout_id: str) -> dict[str, Any]

Fetch a global rollout by id.

cancel_global_rollout

cancel_global_rollout(self, rollout_id: str) -> dict[str, Any]

Cancel a global rollout.

get_global_rollout_artifacts

get_global_rollout_artifacts(self, rollout_id: str) -> dict[str, Any]

List artifacts for a global rollout.

get_global_rollout_usage

get_global_rollout_usage(self, rollout_id: str) -> dict[str, Any]

Return usage totals for a global rollout.

get_global_rollout_summary

get_global_rollout_summary(self, rollout_id: str) -> dict[str, Any]

Return a summary for a global rollout.

stream_global_rollout_events

stream_global_rollout_events(self, rollout_id: str, *, cursor: str | None = None) -> Iterator[dict[str, Any]]

Stream events for a global rollout.

get_pool_container_health

get_pool_container_health(self, pool_id: str) -> dict[str, Any]

Return container health for a pool.

get_task_container_health

get_task_container_health(self, pool_id: str, task_id: str) -> dict[str, Any]

Return container health for a pool task.

get_pool_container_info

get_pool_container_info(self, pool_id: str) -> dict[str, Any]

Return container info for a pool.

get_task_container_info

get_task_container_info(self, pool_id: str, task_id: str) -> dict[str, Any]

Return container info for a pool task.

get_pool_container_metadata

get_pool_container_metadata(self, pool_id: str) -> dict[str, Any]

Return container metadata for a pool.

get_task_container_metadata

get_task_container_metadata(self, pool_id: str, task_id: str) -> dict[str, Any]

Return container metadata for a pool task.

execute_pool_container_rollout

execute_pool_container_rollout(self, pool_id: str, request: dict[str, Any]) -> dict[str, Any]

Execute a one-off container rollout on a pool.

execute_task_container_rollout

execute_task_container_rollout(self, pool_id: str, task_id: str, request: dict[str, Any]) -> dict[str, Any]

Execute a container rollout for a specific task.

get_queue_status

get_queue_status(self) -> dict[str, Any]

Return global queue saturation status.

get_capabilities

get_capabilities(self) -> dict[str, Any]

Return backend capability flags for pools.

AsyncContainerPoolsClient

Async adapter over ContainerPoolsClient.