> ## 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 Call Disposition Runs

> Get the latest production disposition results for up to 100 of an agent's calls, with each run's values, status, and delivery timing.

### Overview

<Note>
  Dispositions are enabled per organization. If your organization does not have access, these endpoints return `404`.
</Note>

Returns the disposition results for a set of the agent's calls. Use it to read what your published dispositions produced on real calls, for example to sync results into your own reporting. The dashboard's Conversations page reads the same data.

Only production runs are returned. Test runs are listed with [Get Test Run Rows](/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-rows). For each call, you get the newest run of each disposition. Each run is labelled with the published version it executed, so renaming or editing a disposition later does not change how past results read.

Results carry values only. Rationale and evidence are omitted.

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

### Query Parameters

<ParamField query="callIds" type="string" required>
  Comma-separated call IDs, up to 100. Duplicates are ignored. Returns `400` with `callIds is required` when empty, `callIds accepts at most 100 ids` when over the limit, or `callIds must be valid UUIDs` when any ID is not a UUID. Calls that belong to another agent, or that have no disposition runs, are left out of the response.
</ParamField>

### Response

<ResponseField name="data.runs" type="array">
  One entry per call and disposition, oldest first. Empty when none of the calls have runs.

  <Expandable title="run object">
    <ResponseField name="id" type="string">
      The run's unique identifier.
    </ResponseField>

    <ResponseField name="callId" type="string">
      The call the run executed against.
    </ResponseField>

    <ResponseField name="dispositionId" type="string">
      The disposition that ran.
    </ResponseField>

    <ResponseField name="dispositionKey" type="string">
      The disposition's key.
    </ResponseField>

    <ResponseField name="name" type="string">
      The disposition's name as of the executed version.
    </ResponseField>

    <ResponseField name="versionNumber" type="number | null">
      The published version that ran, or `null` if unknown.
    </ResponseField>

    <ResponseField name="status" type="string">
      `pending`, `queued`, or `running` while in progress. `complete`, `failed`, or `cancelled` once finished.
    </ResponseField>

    <ResponseField name="timing" type="string | null">
      The executed version's delivery timing: `immediate` or `within_24h`. `null` when the version is unknown.
    </ResponseField>

    <ResponseField name="values" type="array">
      The values defined on the executed version.
    </ResponseField>

    <ResponseField name="values[].id" type="string">
      The value's identifier. Matches `results[].valueId`.
    </ResponseField>

    <ResponseField name="values[].key" type="string">
      The value's key.
    </ResponseField>

    <ResponseField name="values[].label" type="string">
      The value's label, or its key when it has none.
    </ResponseField>

    <ResponseField name="values[].kind" type="string">
      The value's source: `variable_extraction`, `structured_extraction`, `judge`, or `custom_code`.
    </ResponseField>

    <ResponseField name="values[].reasoningEffort" type="string | null">
      The reasoning effort the value ran at: `auto`, `low`, `medium`, or `high`. `null` for `custom_code`, which runs no model.
    </ResponseField>

    <ResponseField name="results" type="array">
      One result per value produced so far. Empty until the run produces values.
    </ResponseField>

    <ResponseField name="results[].valueId" type="string">
      The value this result belongs to.
    </ResponseField>

    <ResponseField name="results[].state" type="string">
      `produced`, `no_value` (the value could not be determined from the call), or `error`.
    </ResponseField>

    <ResponseField name="results[].value" type="any">
      Present when `state` is `produced`. Shaped by the value's `schema`.
    </ResponseField>

    <ResponseField name="results[].error" type="object">
      Present when `state` is `error`: `{ "code", "message" }`. Uses the same codes as [Get Test Run Rows](/api-v2/get/agents-id-dispositions-disposition-id-runs-run-id-rows).
    </ResponseField>

    <ResponseField name="results[].executedVia" type="object">
      How the value was executed: `{ "lane", "priceMultiplier", "durationMs" }`. Omitted when not recorded.
    </ResponseField>

    <ResponseField name="error" type="object | null">
      Set when `status` is `failed` or `cancelled`: `{ "code", "message" }`. `message` is `Disposition execution could not be completed.` Otherwise `null`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      When the run was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="completedAt" type="string | null">
      When the run finished, or `null` while it is in progress.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={null}
  curl -G "https://api.bland.ai/v2/agents/3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f/dispositions/call-runs" \
    -H "authorization: YOUR_API_KEY" \
    --data-urlencode "callIds=e1739a2c-9137-4e85-925d-1efbb6925bc4,2f5e1dc9-f0ac-408a-b9b4-ba3adc971170"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "runs": [
        {
          "id": "0b8f3c52-6e1d-4a7b-9c2e-5d4f6a7b8c9d",
          "callId": "e1739a2c-9137-4e85-925d-1efbb6925bc4",
          "dispositionId": "a4d2c7e9-1b3f-4e5a-8c6d-7f9e0a1b2c3d",
          "dispositionKey": "appointment_outcome",
          "name": "Appointment outcome",
          "versionNumber": 3,
          "status": "complete",
          "timing": "immediate",
          "values": [
            {
              "id": "594742b5-3aed-406c-8411-f243391eb225",
              "key": "booked",
              "label": "Booked",
              "kind": "judge",
              "reasoningEffort": "low"
            }
          ],
          "results": [
            {
              "valueId": "594742b5-3aed-406c-8411-f243391eb225",
              "state": "produced",
              "value": true,
              "executedVia": { "lane": "sync", "priceMultiplier": 1 }
            }
          ],
          "error": null,
          "createdAt": "2026-09-28T17:02:11.412Z",
          "completedAt": "2026-09-28T17:02:19.087Z"
        },
        {
          "id": "7c2a9e14-3f5b-4d6c-8a1e-2b3c4d5e6f70",
          "callId": "2f5e1dc9-f0ac-408a-b9b4-ba3adc971170",
          "dispositionId": "a4d2c7e9-1b3f-4e5a-8c6d-7f9e0a1b2c3d",
          "dispositionKey": "appointment_outcome",
          "name": "Appointment outcome",
          "versionNumber": 3,
          "status": "running",
          "timing": "immediate",
          "values": [
            {
              "id": "594742b5-3aed-406c-8411-f243391eb225",
              "key": "booked",
              "label": "Booked",
              "kind": "judge",
              "reasoningEffort": "low"
            }
          ],
          "results": [],
          "error": null,
          "createdAt": "2026-09-28T17:05:40.221Z",
          "completedAt": null
        }
      ]
    },
    "errors": null
  }
  ```

  ```json Bad Request theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "BAD_REQUEST",
        "message": "callIds accepts at most 100 ids"
      }
    ]
  }
  ```
</ResponseExample>

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.