# List Improve runs

GET

/v1/improve-runs

```sh
curl --request GET \
  --url 'https://example.com/v1/improve-runs?limit=25&status=running' \
  --header 'Authorization: Bearer <token>'
```

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

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.4.0/reference/api.md#bearerauth)**

## Parameters

### Query Parameters

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

Where the previous page ended: its `nextCursor`, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise `400 bad-input`, and the list starts again without it. Absent → first page.

**agentId**

string

**projectId**

string format: uuid

Only the Improve runs in this project.

**status**

string

Allowed values: running completed failed cancelled

Only the Improve runs with this status.

## Responses

### 200

Page of Improve runs.

application/json

object

**data**

required

Array\<object>

An Improve run: the runtime looking for better wording or settings values for an agent in a project, on the project’s test set, within a budget. A candidate that does better becomes a suggested change.

object

**id**

required

string format: uuid

**agentId**

required

string

**projectId**

The project it works in. Absent from older servers, and on a run started for a tenant or an org before Improve runs worked in a project.

string format: uuid

**startsFrom**

required

The version an Improve run starts from: the one the project runs, pinned there (`pin`) or the agent’s latest (`latest`).

object

**version**

required

string

**follows**

required

string

Allowed values: pin latest

**testSetVersion**

The version of the project’s test set it searches and proves on; absent until it’s frozen.

string

**setAside**

The test set’s cases set aside for the proof: `cases` of `of`. None with fewer than five. Absent from older servers.

object

**cases**

required

integer

**of**

required

integer

**tiers**

required

The tiers it tries, the prompt tier first.

Array\<string>

Allowed values: settings prompt

**objective**

required

string

Allowed values: passRate weightedPrecisionAtK

**groupWeights**

required

Which corrections its comparisons count.

string

Allowed values: as-recorded experts-only

**model**

For the prompt tier: the provider and model that drafts the templates.

object

**providerId**

required

string

**model**

required

string

**candidates**

For the prompt tier: how many templates it drafts.

integer

\>= 1 <= 5

**budget**

required

object

**maxCostUsd**

required

The most the Improve run’s comparisons may cost, in US dollars.

number

\> 0 <= 100

**maxCandidates**

required

The most candidates it compares.

integer

\>= 1 <= 200

**requestedBy**

required

`user:<id>` or `service:<id>`.

string

**status**

required

string

Allowed values: running completed failed cancelled

**tried**

required

Candidates tried so far.

integer

**costUsd**

required

What its comparisons have cost so far (US dollars).

string

**outcome**

One of: discriminator: kind

- **object**

  A change passed more cases than the version the run started from, and failed none that passed: the run wrote it as a suggested change for a reviewer to decide.

  object

  **kind**

  required

  string

  Allowed value: suggested

  **suggestedChangeId**

  required

  string format: uuid

- **object**

  No change the run tried did better: `reason` says why, and `holdOut` has the best change’s numbers when one got that far.

  object

  **kind**

  required

  string

  Allowed value: nothing-better

  **reason**

  required

  string

  **holdOut**

  The best change’s proof numbers, when one got that far: on every case, or on the set-aside part for a run stored before that.

  object

  **baseline**

  required

  number | null

  **candidate**

  required

  number | null

  **delta**

  required

  number | null

  **spread**

  number

- **object**

  The run reached its budget with nothing kept.

  object

  **kind**

  required

  string

  Allowed value: cost-cap

  **spentUsd**

  required

  What it spent, in US dollars.

  string

- **object**

  The run failed: `message` says why.

  object

  **kind**

  required

  string

  Allowed value: failed

  **message**

  required

  string

**takes**

The ids of the corrections it took when it started. Absent from older servers.

Array\<string>

**cancelReason**

Why a `cancelled` Improve run stopped when nobody cancelled it: a comparison’s test run was cancelled for it (that run’s `cancelReason`, e.g. `project-suspended`). It wrote no suggested change. Absent when it was cancelled.

string

**comparisons**

Its comparisons so far, each a test run to open: `reference` (the version as it is, on each part: what the proof is held to, case by case), each `candidate` (the block and the values it changed, on the search part: what picks the change to suggest), and the `proof` (the suggested change, on `all` the cases at the reference’s repetitions: what keeps it or not; an Improve run from before 0.4 ran its proof on the hold-out part). Absent from older servers.

Array\<object>

object

**testRunId**

string format: uuid

**role**

required

string

Allowed values: reference candidate proof

**part**

required

string

Allowed values: search hold-out all

**blockId**

string

**changed**

object

**_key_**

additional properties

any

**score**

number | null

**failed**

string

**refused**

For a drafted template that was never compared: why the check refused it (what it reads or names that the agent doesn’t have, or its size).

Array\<object>

object

**path**

required

string

**message**

required

string

**why**

For a drafted template: what the drafter meant it to change.

string

**trigger**

The improve schedule and fire that started it (`GET /v1/schedules/{triggerId}/fires`); absent for an Improve run a person started.

object

**triggerId**

required

string

**fireId**

required

string

**createdAt**

required

string format: date-time

**updatedAt**

required

string format: date-time

**finishedAt**

string format: date-time

**hasMore**

required

boolean

**nextCursor**

string

##### Example

```json
{
  "data": [
    {
      "startsFrom": {
        "follows": "pin"
      },
      "tiers": [
        "settings"
      ],
      "objective": "passRate",
      "groupWeights": "as-recorded",
      "status": "running",
      "outcome": {
        "kind": "suggested"
      },
      "comparisons": [
        {
          "role": "reference",
          "part": "search"
        }
      ]
    }
  ]
}
```

### 400

`bad-input`: `projectId` is not a UUID, or `status` is not a status.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 501

`improve-unsupported`: this runtime runs no Improve runs.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 503

The database was too busy to answer in time (`database-busy`); `Retry-After` (whole seconds) says when to try again.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`POST /v1/improve-runs`: Start an Improve run](https://docs.kindgi.com/v0.4.0/reference/api/operations/improverunsstart.md)
- [Kindgi 0.4.0](https://docs.kindgi.com/v0.4.0/releases/0.4.0.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.4.0/reference/errors.md#bad-input)
- [Error code `database-busy`](https://docs.kindgi.com/v0.4.0/reference/errors.md#database-busy)
- [Error code `improve-unsupported`](https://docs.kindgi.com/v0.4.0/reference/errors.md#improve-unsupported)
- [Every error code](https://docs.kindgi.com/v0.4.0/reference/errors.md)