Check an Improve run
const url = 'https://example.com/v1/improve-runs/check';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agentId":"example","projectId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","tiers":["settings"],"model":{"providerId":"example","model":"example"},"candidates":1,"groupWeights":"as-recorded","objective":"passRate","budget":{"maxCostUsd":1,"maxCandidates":1}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/improve-runs/check \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agentId": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "tiers": [ "settings" ], "model": { "providerId": "example", "model": "example" }, "candidates": 1, "groupWeights": "as-recorded", "objective": "passRate", "budget": { "maxCostUsd": 1, "maxCandidates": 1 } }'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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Start an Improve run for an agent in a project, or check one first. It starts from the version the project runs, learns from the project’s corrections, and searches and proves on the project’s test set. A field not listed here is refused (400 bad-input, naming it).
object
The project the Improve run works in.
What it tries: prompt (a model drafts new wording for the prompt block; a template that reads or names anything the agent doesn’t have is refused, and a drafted suggested change always waits for a reviewer) and settings (values for the settings Improve may tune). Omit it for every tier that’s ready.
For the prompt tier: the tenant’s provider and model that drafts the templates. Omit it for the model of the version’s own model-settings block.
object
For the prompt tier: how many templates it drafts. Omit it for the runtime’s default.
Which corrections the Improve run learns from. Omit it for the default: everyone’s (as-recorded) until the tenant, the project, or the agent in the project has an expert group, then only corrections recorded under one (experts-only).
Default: $5 and 30 candidates.
object
Responses
Section titled “Responses”Its readiness, and the estimate.
Whether the Improve run this input would start is ready, and what it’s estimated to cost. It’s ready when no item it needs is missing: with no tiers named, wording or settings is enough; a named tier needs its own.
object
The version an Improve run starts from: the one the project runs, pinned there (pin) or the agent’s latest (latest).
object
Every item, missing or not, in its order.
One thing an Improve run needs. In this order: wording (a prompt block to reword), settings (settings marked Improve may tune), test-cases (the project’s active cases for the agent, count), permission (publish on the agent), one-at-a-time (no Improve run of the agent running in the project) and project (a version of the agent runs in the project, and it isn’t suspended).
object
For test-cases: the project’s active cases for the agent.
For a missing one-at-a-time: the running Improve run.
For a missing item: where it’s fixed (repo: in the agent’s code, then a deploy; kindgi: in Kindgi) and how, in plain words.
object
What it’s estimated to cost: the budget, which caps its search, and, when the version has cost history, the estimate itself.
object
The estimate (US dollars): the search’s replays (basis.replays less basis.proofReplays) times basis.meanRunCostUsd, at most maxCostUsd, plus the proof’s replays times the same mean, which the budget doesn’t cap. Without basis.proofReplays, every replay counts as the search’s. Absent when the version has no cost history.
The budget (budget.maxCostUsd, US dollars): it caps the search’s share of the estimate, and the proof’s comes on top.
What the estimate is built from.
object
How many replay runs the Improve run’s comparisons would make, its search’s and its proof’s.
Of replays, the proof’s: the best change on every test case, and the version it starts from on the set-aside ones. The budget caps the search, not the proof. Absent when the runtime doesn’t count them apart.
The version’s mean cost over its recent completed runs (US dollars). Absent with no cost history.
With an Improve schedule on the agent and project: this UTC month’s spend on their Improve runs, started by hand or by the schedule, against the schedule’s monthly cap (US dollars). Only the schedule stops at the cap; a run started by hand isn’t refused.
object
Example
{ "startsFrom": { "follows": "pin" }, "items": [ { "key": "wording", "fix": { "where": "repo" } } ]}Malformed request body (bad-input): no projectId, or a field the body doesn’t have (scope, testSetId and fromVersion among them), named in the message.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The body’s projectId names no project of this tenant (project-not-found).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}registry-read-only: the agent registry is read-only and takes no versions an Improve run makes; the message says why.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}improve-unsupported: this runtime runs no Improve runs.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}