# Estimate an improvement pass POST /v1/proposals/improve/estimate ```sh curl --request POST \ --url https://example.com/v1/proposals/improve/estimate \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "agentId": "example", "fromVersion": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "kind": "tenant" }, "suiteId": "example", "tiers": [ "settings" ], "model": { "providerId": "example", "model": "example" }, "candidates": 3, "classWeights": "as-recorded", "objective": "weightedYesShare", "budget": { "maxCostUsd": 1, "maxCandidates": 1 } }' ``` What a pass this input would start is estimated to cost, before you start it. The body is the start body of `POST /v1/proposals/improve`, resolved and reach-checked the same way: an unknown or inactive `fromVersion` (or the version serving the scope) answers `404 agent-version-not-found`, and a test set or scope the pass’s project doesn’t reach answers `400 reference-out-of-scope`, exactly as `improve` would. `estimatedCostUsd` is `min(budget.maxCostUsd, the replay count times the version's mean cost over its recent completed runs)` — clamped to the budget cap — and is absent when the version has no cost history; `basis` gives the unclamped inputs: the replay count, and that mean when there is one. 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 the estimate leaves out a prompt pass’s one-off drafting of its templates — a pass can cost more than the estimate. Because `estimatedCostUsd` is clamped to `budget.maxCostUsd`, an estimate at the cap means the pass is expected to spend its whole budget; the pass checks its cost before each comparison, so the one already running can take it a little over, and it starts no more once the cost reaches `budget.maxCostUsd`. It changes nothing (no pass starts) and takes no Idempotency-Key. Needs `publish` on the agent, and `write` on the pass’s project when it isn’t the version’s. Without improvement passes in this runtime, `501 improve-unsupported`. ## Authorizations - **[bearerAuth](https://docs.kindgi.com/v0.3.0/reference/api.md#bearerauth)** ## Request Bodyrequired application/json Start an improvement pass. object **agentId** required string **fromVersion** The version whose settings it tunes. Default: the one serving `scope`. string **projectId** The project the pass works in: `suiteId` must be a test set it reaches, the version must reach it, and the pass’s eval runs run there. A `project` or `segment` scope must be in it. Default, as an improve schedule’s: the scope’s project, else (a `tenant` or `org` scope) the agent version’s. A project other than the version’s needs `write` there. string format: uuid **scope** required One of: discriminator: kind - **object** The agent’s default for the whole tenant. object **kind** required string Allowed values: tenant - **object** An org’s projects. object **kind** required string Allowed values: org **orgId** required string format: uuid - **object** One project. object **kind** required string Allowed values: project **projectId** required string format: uuid - **object** A segment path within a project: it covers every run whose path starts with it. object **kind** required string Allowed values: segment **projectId** required string format: uuid **path** required Array\