> ## 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.

# Get Disposition Test Run

> Retrieve a test run with live progress counts.

### Overview

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

Returns one test run with its frozen definition, status, and counts. While the run is `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](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-runs.md), then read results with [Get Test Run Rows](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-rows.md) or [Export Test Run CSV](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-export-csv.md).

### 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.

### Response

**data** `object`

The test run.

**test run object**

**id** `string`

Unique identifier for the test run.

**dispositionId** `string`

The disposition this run belongs to.

**target** `string`

`draft` or `published`: which definition the run was started from. A replay keeps its source run's target.

**configurationSource** `string`

`draft`, `published`, or `frozen_run` (a replay of an earlier run's frozen snapshot).

**executionSla** `string`

`realtime` or `queued`.

**replaySourceRunId** `string | null`

The run this one replays, or `null`.

**definition** `object`

The immutable definition snapshot this run executes. Same shape as the `definition` body parameter of [Create Disposition](https://docs.bland.ai/api-v2/post/agents-id-dispositions.md).

**population** `object`

`{ "environment": "production", "requestedSize" }`.

**status** `string`

`queued`, `running`, `complete`, `partial` (finished with some failed calls), `failed`, or `cancelled`. Corrections and alignment require `complete`, `partial`, or `failed`.

**requestedSize** `number`

Calls requested.

**resolvedSize** `number`

Calls admitted once the cohort resolved. `0` until execution starts.

**completedSize** `number`

Calls that finished successfully. Counted live while `running`.

**failedSize** `number`

Calls that failed or were cancelled. Counted live while `running`.

**evalRunId** `null`

Always `null`. Retained for compatibility.

**mode** `string`

`recent` (sampled) or `calls` (explicit call ids).

**inputSetHash** `null`

Always `null`. Retained for compatibility.

**definitionHash** `string`

SHA-256 hex digest of the definition snapshot.

**draftRevision** `number | null`

The draft revision the run was started from, or `null` for a published target.

**dispositionVersionId** `string | null`

The published version the run was started from, or `null` for a draft target.

**summary** `object`

Counts computed from the per-call rows: `caseCount`, `failedCaseCount`, `producedValueCount`, `totalValueCount`, and `correctionCount` (correction revisions saved against the run).

**error** `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`.

**createdAt** `string`

ISO 8601 timestamp of creation.

**startedAt** `string | null`

When execution began, or `null` while queued.

**completedAt** `string | null`

When the run reached a final status, or `null`.

**errors** `null | array`

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

```json Response theme={null}
{
  "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
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Test run 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.