> ## 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. # List Disposition Test Runs > List test runs for a disposition. ### Overview > [!NOTE] > > Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`. Returns the disposition's test runs, newest first, each with its frozen definition, progress counts, and a summary computed from its per-call rows. Start one with [Create Disposition Test Run](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-runs.md); read a single run's live state with [Get Disposition Test Run](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id.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. ### Query Parameters **limit** `integer` (default: 25) Maximum number of runs to return. Minimum `1`, maximum `100`. Values outside that range are clamped; a non-numeric value falls back to `25`. There is no cursor: the newest `limit` runs are returned. ### Response **data.runs** `array` Test run objects ordered by `createdAt` descending. **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" }`. `requestedSize` is the sample size asked for, or the number of explicit call ids. **status** `string` `queued`, `running`, `complete`, `partial` (finished with some failed calls), `failed`, or `cancelled`. **requestedSize** `number` Calls requested. **resolvedSize** `number` Calls admitted once the cohort resolved. `0` until execution starts. **completedSize** `number` Calls that finished successfully. Counted live from the per-call rows while `running`; the final tally afterwards. **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. Runs with equal hashes executed identical definitions. **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` (calls with a row), `failedCaseCount`, `producedValueCount` (value results in state `produced`), `totalValueCount` (all value results), 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": { "runs": [ { "id": "429f5de4-ae9b-470f-be68-7390899af9b5", "dispositionId": "dfe4e15d-01aa-4dfd-94d8-09e32fc6e875", "target": "draft", "configurationSource": "draft", "executionSla": "realtime", "replaySourceRunId": null, "definition": { "name": "Appointment outcome", "description": "Did the caller book an appointment?", "timing": "immediate", "values": [ { "id": "e3d3b96a-39d3-4e5e-9ba6-cdfaa0efb92b", "key": "booked", "label": "Appointment booked", "schema": { "kind": "boolean" }, "source": { "kind": "variable_extraction", "variableKey": "appointment_booked", "execution": { "reasoningEffort": "auto" } } } ], "transformation": { "version": 1, "root": { "kind": "value", "valueId": "e3d3b96a-39d3-4e5e-9ba6-cdfaa0efb92b" } }, "postCallWebhook": { "mode": "emit_followup" } }, "population": { "environment": "production", "requestedSize": 25 }, "status": "running", "requestedSize": 25, "resolvedSize": 25, "completedSize": 11, "failedSize": 1, "evalRunId": null, "mode": "recent", "inputSetHash": null, "definitionHash": "a5d6152e751530b817c530df32d908ea058ad72769c1eacccbf0eb42517e1efa", "draftRevision": 6, "dispositionVersionId": null, "summary": { "caseCount": 25, "failedCaseCount": 1, "producedValueCount": 11, "totalValueCount": 11, "correctionCount": 0 }, "error": null, "createdAt": "2026-09-10T19:12:44.902Z", "startedAt": "2026-09-10T19:12:46.130Z", "completedAt": null }, { "id": "ef1c2354-dc5b-4993-8bcd-283836c23e69", "dispositionId": "dfe4e15d-01aa-4dfd-94d8-09e32fc6e875", "target": "published", "configurationSource": "published", "executionSla": "realtime", "replaySourceRunId": null, "definition": { "name": "Appointment outcome", "description": "Did the caller book an appointment?", "timing": "immediate", "values": [ { "id": "e3d3b96a-39d3-4e5e-9ba6-cdfaa0efb92b", "key": "booked", "label": "Appointment booked", "schema": { "kind": "boolean" }, "source": { "kind": "variable_extraction", "variableKey": "appointment_booked", "execution": { "reasoningEffort": "auto" } } } ], "transformation": { "version": 1, "root": { "kind": "value", "valueId": "e3d3b96a-39d3-4e5e-9ba6-cdfaa0efb92b" } }, "postCallWebhook": { "mode": "emit_followup" } }, "population": { "environment": "production", "requestedSize": 50 }, "status": "complete", "requestedSize": 50, "resolvedSize": 50, "completedSize": 50, "failedSize": 0, "evalRunId": null, "mode": "recent", "inputSetHash": null, "definitionHash": "7a0e4daae110c7411448abc7a83a2066b5f3f553b6b67b0d2d9cd0a29a5c634e", "draftRevision": null, "dispositionVersionId": "d16bf596-21c7-4acb-8d72-2dced2790181", "summary": { "caseCount": 50, "failedCaseCount": 0, "producedValueCount": 48, "totalValueCount": 50, "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": "Disposition 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.