# client.improve_runs

> client.improve_runs — the improveRuns operations.

`client.improve_runs` — the `improveRuns` operations.

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

## `client.improve_runs.list()`

```python signature
list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    agent_id: str | UUID | None = None,
    project_id: str | UUID | None = None,
    status: Literal['running', 'completed', 'failed', 'cancelled'] | None = None,
    timeout: float | None = None,
) -> ImproveRunCollectionPage
```

List Improve runs. `GET /v1/improve-runs`

Newest first, only the Improve runs of agents the caller can read. `?agentId=`, `?projectId=` and `?status=` narrow them.

## `client.improve_runs.start()`

```python signature
start(
    body: StartImproveRunBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ImproveRun
```

Start an Improve run. `POST /v1/improve-runs`

Starts an Improve run for an agent in a project. From the version the project runs (pinned there, else its Latest), it looks for better wording (the prompt tier) or settings values (the settings tier) on the project's test set, learning from the project's open corrections sorted to improve, within the budget. Its best change is proven on every case of the test set, at the reference's repetitions: when it passes more cases than that version and fails none that passed, it becomes a suggested change for a reviewer. It answers at once with the Improve run, `running`. Under `kindgi dev`, the run counts in its project (its corrections, its test set and its cost), and its suggested change is for the whole workspace (the `tenant` scope), which the pack's files serve: pinning it writes its block into the pack's files. The readiness check (`POST /v1/improve-runs/check`) runs first: when something the Improve run needs is missing, it's refused with `409 improve-not-ready`, listing every missing item at once (`details.items`, each with its fix); while the agent has a running Improve run in the project, with `409 improve-run-running` (`details.improveRunId`). An Improve run going when its project is suspended ends `cancelled`, with the reason in `cancelReason`. Needs `publish` on the agent; for an agent more than one project serves, `write` where its versions are made. Without Improve runs in this runtime, `501 improve-unsupported`.

## `client.improve_runs.check()`

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

Check an Improve run. `POST /v1/improve-runs/check`

Whether the Improve run this input would start is ready, and what it's estimated to cost, before you start it. The body is the start body of `POST /v1/improve-runs`. `items` lists everything an Improve run needs, in a fixed order, missing or not; each missing one says where it's fixed (`repo`: in the agent's code, then a deploy; `kindgi`: in Kindgi) and how. `estimate.costUsd` prices each replay at the version's mean cost over its recent completed runs: the search's replays at most `budget.maxCostUsd`, plus the proof's (`estimate.basis.proofReplays`), which the budget doesn't cap. It's absent when the version has no cost history; `estimate.basis` gives the inputs. The estimate prices every replay at that one mean, so a candidate whose prompt or settings cost more or less per run isn't captured, and it leaves out a prompt Improve run's one-off drafting of its templates: an Improve run can cost more than the estimate. The Improve run checks its cost before each comparison, so the one already running can take it a little over, and its search starts no more once the cost reaches `budget.maxCostUsd`. It proves its best change after that, uncapped. With an Improve schedule on the agent and project, `month` is this UTC month's spend on their Improve runs against the schedule's monthly cap; only the schedule stops at the cap. It changes nothing (no Improve run starts) and takes no Idempotency-Key. Needs `publish` on the agent; for an agent more than one project serves, `write` where its versions are made. Without Improve runs in this runtime, `501 improve-unsupported`.

## `client.improve_runs.get()`

```python signature
get(improve_run_id: str | UUID, /, *, timeout: float | None = None) -> ImproveRun
```

Fetch an Improve run. `GET /v1/improve-runs/{improveRunId}`

Its status, the candidates it compared and what they cost, and once it ends, what it found. Needs `read` on its agent.

## `client.improve_runs.cancel()`

```python signature
cancel(
    improve_run_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ImproveRun
```

Cancel an Improve run. `POST /v1/improve-runs/{improveRunId}/cancel`

A running Improve run stops and ends `cancelled`, writing no suggested change. Needs `publish` on its agent.