List Test Run Correction Revisions

curl --request GET \
  --url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id} \
  --header 'authorization: <authorization>'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}"

headers = {"authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}")
  .header("authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "annotations": [
      {
        "id": "71401be8-f0db-412c-9621-6fcc3a50195c",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 2,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "no_value"
        },
        "explanation": "On a second listen the caller only asked about availability and never committed to a time, so there is no booking outcome to record.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T21:02:15.114Z"
      },
      {
        "id": "2b34fbbf-d3cb-45fc-ad3f-cbfa95f2afbd",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 1,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": true
        },
        "explanation": "The caller agreed to the slot at the very end of the call, after the agent's recap.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T20:14:33.870Z"
      }
    ],
    "truncated": false
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Test run case not found"
    }
  ]
}

GET

agents

{agent_id}

dispositions

{disposition_id}

runs

{run_id}

cases

{call_id}

annotations

{value_id}

List Test Run Correction Revisions

curl --request GET \
  --url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id} \
  --header 'authorization: <authorization>'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}"

headers = {"authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {authorization: '<authorization>'}};

fetch('https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}")
  .header("authorization", "<authorization>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id}/cases/{call_id}/annotations/{value_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "annotations": [
      {
        "id": "71401be8-f0db-412c-9621-6fcc3a50195c",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 2,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "no_value"
        },
        "explanation": "On a second listen the caller only asked about availability and never committed to a time, so there is no booking outcome to record.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T21:02:15.114Z"
      },
      {
        "id": "2b34fbbf-d3cb-45fc-ad3f-cbfa95f2afbd",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 1,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": true
        },
        "explanation": "The caller agreed to the slot at the very end of the call, after the agent's recap.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T20:14:33.870Z"
      }
    ],
    "truncated": false
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Test run case not found"
    }
  ]
}

Overview

Dispositions are enabled per organization. If your organization does not have access, these endpoints return 404.

Returns the correction history for one value on one call of a test run, newest revision first, up to 50 entries. Corrections are written with Correct Test Run Value; only the newest revision counts as the current correction on Get Test Run Rows and in the CSV export.

Headers

string

required

Your API key for authentication.

Path Parameters

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.

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.

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.

string

required

The call. 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.

string

required

The definition value. 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.

Response

array

Correction revisions ordered by revision descending, at most 50. Empty if the cell was never corrected.

Show correction object

string

Unique identifier for this revision.

string

The test run.

string

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

string

The call.

string

The definition value.

number

1 for the first correction, incrementing with each later one.

object

The engine’s result as it stood when the correction was saved: valueId, state, and, when present, value, error, rationale, evidence, and executedVia.

object

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

string

The explanation supplied with the correction.

string | null

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

string

ISO 8601 timestamp of the correction.

boolean

true when more than 50 revisions exist and older ones were cut from the list.

null | array

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

{
  "data": {
    "annotations": [
      {
        "id": "71401be8-f0db-412c-9621-6fcc3a50195c",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 2,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "no_value"
        },
        "explanation": "On a second listen the caller only asked about availability and never committed to a time, so there is no booking outcome to record.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T21:02:15.114Z"
      },
      {
        "id": "2b34fbbf-d3cb-45fc-ad3f-cbfa95f2afbd",
        "testRunId": "77216b1c-2a91-496f-84df-76be610c8510",
        "testRunCaseId": "b3caa112-96c4-4bfc-b62f-20406b1f961f",
        "callId": "66a9ec46-33ea-4b56-bd4a-970706c652e8",
        "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
        "revision": 1,
        "originalResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": false,
          "rationale": "No appointment time was agreed before the caller hung up."
        },
        "correctedResult": {
          "valueId": "d7e20249-0c03-49dd-9b28-70797904c6b4",
          "state": "produced",
          "value": true
        },
        "explanation": "The caller agreed to the slot at the very end of the call, after the agent's recap.",
        "createdBy": "8367c610-f081-47f5-ba7d-2f9c89d26e47",
        "createdAt": "2026-09-10T20:14:33.870Z"
      }
    ],
    "truncated": false
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Test run case not found"
    }
  ]
}

Docs for agents: llms.txt

Get Started

Agents

Versions

Phone Numbers

Identity

Memory

Environments and Releases

Branches

Variables

Checks

Experiments

Library

Migration

Dispositions

List Test Run Correction Revisions

Overview

Headers

Path Parameters

Response

​Overview

​Headers

​Path Parameters

​Response

Overview

Headers

Path Parameters

Response