# Check an Improve run POST /v1/improve-runs/check ```sh curl --request POST \ --url https://example.com/v1/improve-runs/check \ --header 'Authorization: Bearer ' \ --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 - **[bearerAuth](https://docs.kindgi.com/v0.4.0/reference/api.md#bearerauth)** ## Request Bodyrequired application/json 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 **agentId** required string **projectId** required The project the Improve run works in. string format: uuid **tiers** 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. Array\ \>= 1 items <= 2 items unique items Allowed values: settings prompt **model** 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 **providerId** required string **model** required string **candidates** For the prompt tier: how many templates it drafts. Omit it for the runtime’s default. integer \>= 1 <= 5 **groupWeights** 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`). string Allowed values: as-recorded experts-only **objective** string default: passRate Allowed values: passRate weightedPrecisionAtK **budget** Default: $5 and 30 candidates. object **maxCostUsd** number \> 0 <= 100 **maxCandidates** integer \>= 1 <= 200 ## Responses ### 200 Its readiness, and the estimate. application/json 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 **ready** required boolean **startsFrom** 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 **items** required Every item, missing or not, in its order. Array\