Skip to content
Kindgi

Fetch an improvement pass

GET
/v1/improvement-passes/{passId}
curl --request GET \
  --url https://example.com/v1/improvement-passes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
passId
required
string format: uuid

The improvement pass id (a UUID).

Responses

Section titled “Responses”

200

Section titled “200”

The pass.

Media typeapplication/json

An improvement pass: the runtime looking for better values for an agent version’s tunable settings (x-kindgi-tunable) on a test set, within a budget. Its best candidate becomes an improvement proposal.

object
id
required
string format: uuid
agentId
required
string
fromVersion
required

The version whose settings it tunes.

string
scope
required
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
suiteId
required

The test set it searches and proves on.

string
tiers
required
Array<string>
Allowed values: settings prompt
objective
required
string
Allowed values: weightedYesShare weightedPrecisionAtK
classWeights

Which judgments its comparisons count. Absent from older servers: restricted-only.

string
Allowed values: as-recorded restricted-only
model

For a prompt pass: the provider and model that drafts the templates.

object
providerId
required
string
model
required
string
candidates

For a prompt pass: how many templates it drafts.

integer
>= 1 <= 5
budget
required
object
maxCostUsd
required

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

number
> 0 <= 100
maxCandidates
required

The most candidates it compares.

integer
>= 1 <= 200
requestedBy
required
string
status
required
string
Allowed values: running completed failed cancelled
candidatesEvaluated
required
integer
costUsd
required

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

string
outcome

What a finished pass found. proposed: its best candidate beat the current values on the test set’s hold-out part, so it wrote an improvement proposal (proposalId) for a reviewer to decide. nothing-found: no candidate beat them by more than the noise, or within the budget (reason; holdOut has the best candidate’s numbers when one got that far). failed: message says why.

object
kind
required
string
Allowed values: proposed nothing-found failed
proposalId
string format: uuid
reason
string
holdOut
object
baseline
required
number | null
candidate
required
number | null
delta
required
number | null
spread
number
message
string
comparisons

Its comparisons so far, each an eval run to open: reference (the version as it is, on the search part), each candidate (the block and the values it changed, on the search part), and the proof (the proposal, on the hold-out part). Absent from older servers.

Array<object>
object
evalRunId
string format: uuid
role
required
string
Allowed values: reference candidate proof
part
required
string
Allowed values: search hold-out
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
hypothesis

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 a pass 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
Example
{
  "scope": {
    "kind": "tenant"
  },
  "tiers": [
    "settings"
  ],
  "objective": "weightedYesShare",
  "classWeights": "as-recorded",
  "status": "running",
  "outcome": {
    "kind": "proposed"
  },
  "comparisons": [
    {
      "role": "reference",
      "part": "search"
    }
  ]
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No such pass (or none the caller can read).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

Section titled “501”

improve-unsupported: this runtime runs no improvement passes.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}