> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Correct Test Run Value

> Record a corrected value for one call in a test run.

### Overview

> [!NOTE]
>
> Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`.

Saves what the correct result should have been for one value on one call of a finished test run. Corrections are append-only: the engine's original result is never modified, and each call to this endpoint adds a new `revision` for that call and value. The run must be in a terminal status (`complete`, `partial`, or `failed`). Corrections show up on [Get Test Run Rows](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-rows.md), in the CSV export, and feed [Align Disposition Test Run](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-runs-run-id-align.md). An organization may submit at most 300 corrections per hour.

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**agent\_id** `string` *required*

The agent's unique identifier. Must be a UUID; otherwise returns `400` with the message `agentId must be a valid UUID`. Returns `404 Agent not found` if the agent is not in your organization.

**disposition\_id** `string` *required*

The disposition's unique identifier. Must be a UUID; otherwise returns `400` with the message `dispositionId must be a valid UUID`. Returns `404 Disposition not found` if it does not belong to this agent.

**run\_id** `string` *required*

The test run's unique identifier. Must be a UUID; otherwise returns `400` with the message `runId must be a valid UUID`. Returns `404 Test run not found` if it does not belong to this disposition, and `409 CONFLICT` with the message `Corrections require a terminal test run` if the run is still `queued` or `running`, or was `cancelled`.

**call\_id** `string` *required*

The call whose result you are correcting. Must be a UUID; otherwise returns `400` with the message `callId must be a valid UUID`. Returns `404` with the message `Test run case not found` if the call is not part of this run.

**value\_id** `string` *required*

The definition value you are correcting. Must be a UUID; otherwise returns `400` with the message `valueId must be a valid UUID`. Returns `404` with the message `Disposition value not found in this run` if the run's definition snapshot has no such value, or `Run result not found for this value` if the call produced no result for it.

### Body Parameters

Unknown fields are rejected with `400 BAD_REQUEST` and the message `Invalid request body`.

**state** `string` *required*

`produced` when you are supplying the right value, or `no_value` when the call genuinely offers no answer for this value.

**value** `any`

Required when `state` is `produced`; must be omitted when `state` is `no_value`. Must match the value's frozen `schema` exactly (a boolean for `boolean`, one of the option keys for `enum`, and so on), otherwise `400` with a message such as `Corrected value does not match the frozen boolean schema`. A string may be at most 4000 characters; an array or object may serialize to at most 16000 characters.

**explanation** `string` *required*

Why the engine's result was wrong, 40 to 4000 characters after trimming. Stored verbatim and used as training context by Align Disposition Test Run.

### Response

Returns `201` on success.

**data** `object`

The new correction revision.

**correction object**

**id** `string`

Unique identifier for this revision.

**testRunId** `string`

The test run.

**testRunCaseId** `string`

Identifier of this call's execution within the run. Matches the `run_id` column of the CSV export.

**callId** `string`

The call.

**valueId** `string`

The definition value.

**revision** `number`

`1` for the first correction of this call and value, incrementing with each further correction.

**originalResult** `object`

The engine's result as it stood when you corrected it: `valueId`, `state`, and, when present, `value`, `error`, `rationale`, `evidence`, and `executedVia`, in the same shape as `results[]` on Get Test Run Rows.

**correctedResult** `object`

`{ "valueId", "state" }` plus `value` when `state` is `produced`.

**explanation** `string`

The trimmed explanation you supplied.

**createdBy** `string | null`

ID of the user who saved the correction, or `null` when saved with an org-level key.

**createdAt** `string`

ISO 8601 timestamp of the correction.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "id": "1104a27d-55ca-4598-81bf-816ff21370b1",
    "testRunId": "9657e390-255f-4206-9bed-a05275cd0b94",
    "testRunCaseId": "c6fcc42a-f731-4521-b489-c0fd7e3ddfc9",
    "callId": "b9f0ebae-9698-4bd0-a86a-b4d031bf9e30",
    "valueId": "4a3d3d0e-4c73-4621-92a1-425676ccdb69",
    "revision": 1,
    "originalResult": {
      "valueId": "4a3d3d0e-4c73-4621-92a1-425676ccdb69",
      "state": "produced",
      "value": false,
      "rationale": "No appointment time was agreed before the caller hung up.",
      "executedVia": { "lane": "sync", "priceMultiplier": 1 }
    },
    "correctedResult": {
      "valueId": "4a3d3d0e-4c73-4621-92a1-425676ccdb69",
      "state": "produced",
      "value": true
    },
    "explanation": "The caller agreed to the slot at the very end of the call, after the agent's recap.",
    "createdBy": "0e9a481a-2920-4eef-b971-a36d9bbec695",
    "createdAt": "2026-09-10T20:14:33.870Z"
  },
  "errors": null
}
```

```json Invalid Correction theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Corrected value does not match the frozen boolean schema"
    }
  ]
}
```

```json Conflict theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CONFLICT",
      "message": "Corrections require a terminal test run"
    }
  ]
}
```

```json Rate Limited theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many disposition corrections submitted for this organization — please wait before submitting more."
    }
  ]
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Test run case not found"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.