> ## 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`.
</Note>

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](/api-v2/post/agents-id-dispositions-disposition-id-runs), then read results with [Get Test Run Rows](/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-rows) or [Export Test Run CSV](/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-export-csv).

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="agent_id" type="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.
</ParamField>

<ParamField path="disposition_id" type="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.
</ParamField>

<ParamField path="run_id" type="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.
</ParamField>

### Response

<ResponseField name="data" type="object">
  The test run.

  <Expandable title="test run object">
    <ResponseField name="id" type="string">
      Unique identifier for the test run.
    </ResponseField>

    <ResponseField name="dispositionId" type="string">
      The disposition this run belongs to.
    </ResponseField>

    <ResponseField name="target" type="string">
      `draft` or `published`: which definition the run was started from. A replay keeps its source run's target.
    </ResponseField>

    <ResponseField name="configurationSource" type="string">
      `draft`, `published`, or `frozen_run` (a replay of an earlier run's frozen snapshot).
    </ResponseField>

    <ResponseField name="executionSla" type="string">
      `realtime` or `queued`.
    </ResponseField>

    <ResponseField name="replaySourceRunId" type="string | null">
      The run this one replays, or `null`.
    </ResponseField>

    <ResponseField name="definition" type="object">
      The immutable definition snapshot this run executes. Same shape as the `definition` body parameter of [Create Disposition](/api-v2/post/agents-id-dispositions).
    </ResponseField>

    <ResponseField name="population" type="object">
      `{ "environment": "production", "requestedSize" }`.
    </ResponseField>

    <ResponseField name="status" type="string">
      `queued`, `running`, `complete`, `partial` (finished with some failed calls), `failed`, or `cancelled`. Corrections and alignment require `complete`, `partial`, or `failed`.
    </ResponseField>

    <ResponseField name="requestedSize" type="number">
      Calls requested.
    </ResponseField>

    <ResponseField name="resolvedSize" type="number">
      Calls admitted once the cohort resolved. `0` until execution starts.
    </ResponseField>

    <ResponseField name="completedSize" type="number">
      Calls that finished successfully. Counted live while `running`.
    </ResponseField>

    <ResponseField name="failedSize" type="number">
      Calls that failed or were cancelled. Counted live while `running`.
    </ResponseField>

    <ResponseField name="evalRunId" type="null">
      Always `null`. Retained for compatibility.
    </ResponseField>

    <ResponseField name="mode" type="string">
      `recent` (sampled) or `calls` (explicit call ids).
    </ResponseField>

    <ResponseField name="inputSetHash" type="null">
      Always `null`. Retained for compatibility.
    </ResponseField>

    <ResponseField name="definitionHash" type="string">
      SHA-256 hex digest of the definition snapshot.
    </ResponseField>

    <ResponseField name="draftRevision" type="number | null">
      The draft revision the run was started from, or `null` for a published target.
    </ResponseField>

    <ResponseField name="dispositionVersionId" type="string | null">
      The published version the run was started from, or `null` for a draft target.
    </ResponseField>

    <ResponseField name="summary" type="object">
      Counts computed from the per-call rows: `caseCount`, `failedCaseCount`, `producedValueCount`, `totalValueCount`, and `correctionCount` (correction revisions saved against the run).
    </ResponseField>

    <ResponseField name="error" type="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`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation.
    </ResponseField>

    <ResponseField name="startedAt" type="string | null">
      When execution began, or `null` while queued.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null">
      When the run reached a final status, or `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="null | array">
  `null` on success, or a list of error objects if the request failed.
</ResponseField>

<ResponseExample>
  ```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"
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)