# Cancel an Improve run POST /v1/improve-runs/{improveRunId}/cancel ```sh curl --request POST \ --url https://example.com/v1/improve-runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \ --header 'Authorization: Bearer ' ``` A running Improve run stops and ends `cancelled`, writing no suggested change. Needs `publish` on its agent. ## Authorizations - **[bearerAuth](https://docs.kindgi.com/reference/api.md#bearerauth)** ## Parameters ### Path Parameters **improveRunId** required string format: uuid The Improve run id (a UUID). ### Header Parameters **Idempotency-Key** string \>= 1 characters Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the workspace is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered `503 idempotency-store-unavailable` with `Retry-After`: nothing ran, so retry with the same key (from 0.3.0). ## Responses ### 200 The Improve run, cancelled. application/json An Improve run: the runtime looking for better wording or settings values for an agent in a project, on the project’s test set, within a budget. A candidate that does better becomes a suggested change. object **id** required string format: uuid **agentId** required string **projectId** The project it works in. Absent from older servers, and on a run started for a workspace or an org before Improve runs worked in a project. string format: uuid **startsFrom** required 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 **testSetVersion** The version of the project’s test set it searches and proves on; absent until it’s frozen. string **setAside** The test set’s cases set aside for the proof: `cases` of `of`. None with fewer than five. Absent from older servers. object **cases** required integer **of** required integer **tiers** required The tiers it tries, the prompt tier first. Array\ Allowed values: settings prompt **objective** required string Allowed values: passRate weightedPrecisionAtK **groupWeights** required Which corrections its comparisons count. string Allowed values: as-recorded experts-only **model** For the prompt tier: the provider and model that drafts the templates. object **providerId** required string **model** required string **candidates** For the prompt tier: how many templates it drafts. integer \>= 1 <= 5 **budget** required object **maxCostUsd** required The most the Improve run’s comparisons may cost, in US dollars. number \> 0 <= 100 **maxCandidates** required The most candidates it compares. integer \>= 1 <= 200 **requestedBy** required `user:` or `service:`. string **status** required string Allowed values: running completed failed cancelled **tried** required Candidates tried so far. integer **costUsd** required What its comparisons have cost so far (US dollars). string **outcome** One of: discriminator: kind - **object** A change passed more cases than the version the run started from, and failed none that passed: the run wrote it as a suggested change for a reviewer to decide. object **kind** required string Allowed value: suggested **suggestedChangeId** required string format: uuid - **object** No change the run tried did better: `reason` says why, and `holdOut` has the best change’s numbers when one got that far. object **kind** required string Allowed value: nothing-better **reason** required string **holdOut** The best change’s proof numbers, when one got that far: on every case, or on the set-aside part for a run stored before that. object **baseline** required number | null **candidate** required number | null **delta** required number | null **spread** number - **object** The run reached its budget with nothing kept. object **kind** required string Allowed value: cost-cap **spentUsd** required What it spent, in US dollars. string - **object** The run failed: `message` says why. object **kind** required string Allowed value: failed **message** required string **takes** The ids of the corrections it took when it started. Absent from older servers. Array\ **cancelReason** Why a `cancelled` Improve run stopped when nobody cancelled it: a comparison’s test run was cancelled for it (that run’s `cancelReason`, e.g. `project-suspended`). It wrote no suggested change. Absent when it was cancelled. string **comparisons** Its comparisons so far, each a test run to open: `reference` (the version as it is, on each part: what the proof is held to, case by case), each `candidate` (the block and the values it changed, on the search part: what picks the change to suggest), and the `proof` (the suggested change, on `all` the cases at the reference’s repetitions: what keeps it or not; an Improve run from before 0.4 ran its proof on the hold-out part). Absent from older servers. Array\ object **testRunId** string format: uuid **role** required string Allowed values: reference candidate proof **part** required string Allowed values: search hold-out all **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 **path** required string **message** required string **why** 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 an Improve run 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 ```json { "startsFrom": { "follows": "pin" }, "tiers": [ "settings" ], "objective": "passRate", "groupWeights": "as-recorded", "status": "running", "outcome": { "kind": "suggested" }, "comparisons": [ { "role": "reference", "part": "search" } ] } ``` ### 400 Malformed request body. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 401 Missing / malformed / expired / revoked bearer token. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 404 No such Improve run. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 409 `improve-run-finished`: it has ended already. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 500 Server error (unmapped domain code or framework crash). application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 501 `improve-unsupported`: this runtime runs no Improve runs. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 503 The `Idempotency-Key` store couldn’t be read before the request ran (`idempotency-store-unavailable`), so nothing was changed; `Retry-After` (whole seconds) says when to try again with the same key. application/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 ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/improve-runs/{improveRunId}`: Fetch an Improve run](https://docs.kindgi.com/reference/api/operations/improverunsget.md) - [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/reference/errors.md#idempotency-store-unavailable) - [Error code `improve-run-finished`](https://docs.kindgi.com/reference/errors.md#improve-run-finished) - [Error code `improve-unsupported`](https://docs.kindgi.com/reference/errors.md#improve-unsupported) - [Every error code](https://docs.kindgi.com/reference/errors.md)