Estimate an improvement pass
const url = 'https://example.com/v1/proposals/improve/estimate';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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}}'};
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/proposals/improve/estimate \ --header 'Authorization: Bearer <token>' \ --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
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Start an improvement pass.
object
The version whose settings it tunes. Default: the one serving scope.
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.
The agent’s default for the whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
The test set (a judged eval suite). The pass splits it into a search part and a hold-out part, and proves its best candidate on the hold-out part.
['settings']: values for the tunable settings keys. ['prompt']: a model drafts templates for the prompt block (needs model); a template that reads or names anything the agent doesn’t have is refused, and a drafted proposal always waits for a reviewer.
For a prompt pass: the tenant’s provider and model that drafts the templates.
object
For a prompt pass: how many templates it drafts.
Which judgments the pass learns from. Omit it for the default: everyone’s (as-recorded) until the tenant, the project the pass reads its judgments from (its test set’s project, which can differ from where the agent is made), or the agent improved in that project has a restricted judge class, then only judgments recorded under one (restricted-only).
Default: $5 and 30 candidates.
object
Responses
Section titled “Responses”The estimated cost.
What a pass this input would start is estimated to cost: the budget cap it’s clamped to, and — when the version has cost history — the estimate itself.
object
The estimate (US dollars): basis.replays times basis.meanRunCostUsd, or maxCostUsd when that’s smaller. Absent when the version has no cost history.
The budget cap the estimate is clamped to (budget.maxCostUsd, US dollars).
What the estimate is built from.
object
How many replay runs the pass’s comparisons would make.
The version’s mean cost over its recent completed runs (US dollars). Absent with no cost history.
Examplegenerated
{ "estimatedCostUsd": "example", "maxCostUsd": "example", "basis": { "replays": 1, "meanRunCostUsd": "example" }}Malformed request body (bad-input), or a project or segment scope that isn’t in projectId. Or reference-out-of-scope: a project or segment scope doesn’t reach the agent, the version doesn’t reach the pass’s project (/fromVersion), or the test set isn’t one that project reaches (details.issues).
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" }}fromVersion (or the version serving the scope) is not an active version (agent-version-not-found); or 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" }}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 improvement passes.
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" }}