# client.agents.promotions

> client.agents.promotions — the agents.promotions operations.

`client.agents.promotions` — the `agents.promotions` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.agents.promotions.list()`

```python signature
list(
    agent_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    scope_kind: Literal['tenant', 'org', 'project', 'segment'] | None = None,
    scope_id: str | UUID | None = None,
    segments: Sequence[ScopeSegment | Mapping[str, str]] | None = None,
    timeout: float | None = None,
) -> PromotionPage
```

List an agent's promotions. `GET /v1/agents/{agentId}/promotions`

The history of live-version changes (promotions, rollbacks, unpins), newest first. `scopeKind` (`tenant`, `org`, `project`, `segment`) with `scopeId` and `segment` narrows it to one scope.

## `client.agents.promotions.create()`

```python signature
create(
    agent_id: str | UUID,
    body: PromoteBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Promotion
```

Make a version live for a scope. `POST /v1/agents/{agentId}/promotions`

Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.

## `client.agents.promotions.check()`

```python signature
check(
    agent_id: str | UUID,
    body: PromoteBody | Mapping[str, Any] | None = None,
    /,
    *,
    timeout: float | None = None,
    **fields: Any,
) -> PromotionCheck
```

Check a promotion against its gate. `POST /v1/agents/{agentId}/promotions/check`

What `POST …/promotions` with the same body would do, with nothing recorded: `would-promote`, `needs-approval` (with the approval it needs) or `gate-failed`, with every check. For a pipeline: evaluate, check, promote. Needs `read` on the agent.

## `client.agents.promotions.get()`

```python signature
get(
    agent_id: str | UUID,
    promotion_id: str | UUID,
    /,
    *,
    timeout: float | None = None,
) -> Promotion
```

Get a promotion. `GET /v1/agents/{agentId}/promotions/{promotionId}`