Get Disposition Test Run
curl --request GET \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id} \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_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}', 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}",
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}"
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}")
.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}")
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": {
"id": "56294c6b-883b-48ff-92bd-a36b09064859",
"dispositionId": "386f4dfc-7f6c-4dbe-be10-5fa14924c894",
"target": "published",
"configurationSource": "published",
"executionSla": "realtime",
"replaySourceRunId": null,
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "immediate",
"values": [
{
"id": "2b462fd0-36b3-4cd7-9a60-1736613c0a65",
"key": "booked",
"label": "Appointment booked",
"schema": { "kind": "boolean" },
"source": {
"kind": "variable_extraction",
"variableKey": "appointment_booked",
"execution": { "reasoningEffort": "auto" }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"booked": { "kind": "value", "valueId": "2b462fd0-36b3-4cd7-9a60-1736613c0a65" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
},
"population": { "environment": "production", "requestedSize": 50 },
"status": "complete",
"requestedSize": 50,
"resolvedSize": 50,
"completedSize": 49,
"failedSize": 1,
"evalRunId": null,
"mode": "recent",
"inputSetHash": null,
"definitionHash": "fc3b269ec69e90bf999e69412ffbc45badaba61f2da5b13cbe6625e729be5a8d",
"draftRevision": null,
"dispositionVersionId": "0983ec20-8ccc-4603-bdad-f9b8eaa15285",
"summary": {
"caseCount": 50,
"failedCaseCount": 1,
"producedValueCount": 47,
"totalValueCount": 49,
"correctionCount": 3
},
"error": null,
"createdAt": "2026-09-09T12:01:08.417Z",
"startedAt": "2026-09-09T12:01:09.655Z",
"completedAt": "2026-09-09T12:09:51.208Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Test run not found"
}
]
}
Test Runs
Get Disposition Test Run
Retrieve a test run with live progress counts.
GET
/
v2
/
agents
/
{agent_id}
/
dispositions
/
{disposition_id}
/
runs
/
{run_id}
Get Disposition Test Run
curl --request GET \
--url https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_id} \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/dispositions/{disposition_id}/runs/{run_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}', 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}",
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}"
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}")
.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}")
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": {
"id": "56294c6b-883b-48ff-92bd-a36b09064859",
"dispositionId": "386f4dfc-7f6c-4dbe-be10-5fa14924c894",
"target": "published",
"configurationSource": "published",
"executionSla": "realtime",
"replaySourceRunId": null,
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "immediate",
"values": [
{
"id": "2b462fd0-36b3-4cd7-9a60-1736613c0a65",
"key": "booked",
"label": "Appointment booked",
"schema": { "kind": "boolean" },
"source": {
"kind": "variable_extraction",
"variableKey": "appointment_booked",
"execution": { "reasoningEffort": "auto" }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"booked": { "kind": "value", "valueId": "2b462fd0-36b3-4cd7-9a60-1736613c0a65" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
},
"population": { "environment": "production", "requestedSize": 50 },
"status": "complete",
"requestedSize": 50,
"resolvedSize": 50,
"completedSize": 49,
"failedSize": 1,
"evalRunId": null,
"mode": "recent",
"inputSetHash": null,
"definitionHash": "fc3b269ec69e90bf999e69412ffbc45badaba61f2da5b13cbe6625e729be5a8d",
"draftRevision": null,
"dispositionVersionId": "0983ec20-8ccc-4603-bdad-f9b8eaa15285",
"summary": {
"caseCount": 50,
"failedCaseCount": 1,
"producedValueCount": 47,
"totalValueCount": 49,
"correctionCount": 3
},
"error": null,
"createdAt": "2026-09-09T12:01:08.417Z",
"startedAt": "2026-09-09T12:01:09.655Z",
"completedAt": "2026-09-09T12:09:51.208Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Test run not found"
}
]
}
Overview
Dispositions are enabled per organization. If your organization does not have access, these endpoints return
404.running, completedSize and failedSize are counted live from the per-call rows; once it finishes they are the final tally. Poll this endpoint after Create Disposition Test Run, then read results with Get Test Run Rows or Export Test Run CSV.
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.Response
object
The test run.
Show test run object
Show test run object
string
Unique identifier for the test run.
string
The disposition this run belongs to.
string
draft or published: which definition the run was started from. A replay keeps its source run’s target.string
draft, published, or frozen_run (a replay of an earlier run’s frozen snapshot).string
realtime or queued.string | null
The run this one replays, or
null.object
The immutable definition snapshot this run executes. Same shape as the
definition body parameter of Create Disposition.object
{ "environment": "production", "requestedSize" }.string
queued, running, complete, partial (finished with some failed calls), failed, or cancelled. Corrections and alignment require complete, partial, or failed.number
Calls requested.
number
Calls admitted once the cohort resolved.
0 until execution starts.number
Calls that finished successfully. Counted live while
running.number
Calls that failed or were cancelled. Counted live while
running.null
Always
null. Retained for compatibility.string
recent (sampled) or calls (explicit call ids).null
Always
null. Retained for compatibility.string
SHA-256 hex digest of the definition snapshot.
number | null
The draft revision the run was started from, or
null for a published target.string | null
The published version the run was started from, or
null for a draft target.object
Counts computed from the per-call rows:
caseCount, failedCaseCount, producedValueCount, totalValueCount, and correctionCount (correction revisions saved against the run).object | null
{ "code", "message" } when the run as a whole failed, otherwise null. Codes include test_run_cancelled, test_run_stale, in_flight_cap_exceeded, empty_cohort, billing_not_allowed, test_run_execution_failed, and disposition_failed.string
ISO 8601 timestamp of creation.
string | null
When execution began, or
null while queued.string | null
When the run reached a final status, or
null.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"id": "56294c6b-883b-48ff-92bd-a36b09064859",
"dispositionId": "386f4dfc-7f6c-4dbe-be10-5fa14924c894",
"target": "published",
"configurationSource": "published",
"executionSla": "realtime",
"replaySourceRunId": null,
"definition": {
"name": "Appointment outcome",
"description": "Did the caller book an appointment?",
"timing": "immediate",
"values": [
{
"id": "2b462fd0-36b3-4cd7-9a60-1736613c0a65",
"key": "booked",
"label": "Appointment booked",
"schema": { "kind": "boolean" },
"source": {
"kind": "variable_extraction",
"variableKey": "appointment_booked",
"execution": { "reasoningEffort": "auto" }
}
}
],
"transformation": {
"version": 1,
"root": {
"kind": "object",
"fields": {
"booked": { "kind": "value", "valueId": "2b462fd0-36b3-4cd7-9a60-1736613c0a65" }
}
}
},
"postCallWebhook": { "mode": "emit_followup" }
},
"population": { "environment": "production", "requestedSize": 50 },
"status": "complete",
"requestedSize": 50,
"resolvedSize": 50,
"completedSize": 49,
"failedSize": 1,
"evalRunId": null,
"mode": "recent",
"inputSetHash": null,
"definitionHash": "fc3b269ec69e90bf999e69412ffbc45badaba61f2da5b13cbe6625e729be5a8d",
"draftRevision": null,
"dispositionVersionId": "0983ec20-8ccc-4603-bdad-f9b8eaa15285",
"summary": {
"caseCount": 50,
"failedCaseCount": 1,
"producedValueCount": 47,
"totalValueCount": 49,
"correctionCount": 3
},
"error": null,
"createdAt": "2026-09-09T12:01:08.417Z",
"startedAt": "2026-09-09T12:01:09.655Z",
"completedAt": "2026-09-09T12:09:51.208Z"
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Test run not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?