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

> List the dispositions defined on an agent.

### Overview

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

Returns every disposition on the agent, oldest first, as summary records with lifecycle state and draft and published pointers. The draft definition itself is not included; fetch it with [Get Disposition Draft](/api-v2/get/agents-id-dispositions-disposition-id-draft). Create one with [Create Disposition](/api-v2/post/agents-id-dispositions).

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

### Response

<ResponseField name="data.dispositions" type="array">
  Disposition summaries ordered by `createdAt` ascending.

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

    <ResponseField name="agentId" type="string">
      The agent this disposition belongs to.
    </ResponseField>

    <ResponseField name="key" type="string">
      Stable slug, unique per agent. Set at creation and never changes.
    </ResponseField>

    <ResponseField name="state" type="string">
      `disabled` or `enabled`. A new disposition starts `disabled`. [Publish Disposition](/api-v2/post/agents-id-dispositions-disposition-id-publish) sets `enabled`; [Disable Disposition](/api-v2/post/agents-id-dispositions-disposition-id-disable) sets `disabled` again.
    </ResponseField>

    <ResponseField name="publishedVersionId" type="string | null">
      The most recently published version, or `null` if never published.
    </ResponseField>

    <ResponseField name="publishedVersionNumber" type="number | null">
      Sequential number of that version, starting at `1`, or `null` if never published.
    </ResponseField>

    <ResponseField name="draftRevision" type="number">
      Optimistic-concurrency counter for the draft. Starts at `1` and increments on every draft update and publish. Pass it back as `expectedDraftRevision` when writing.
    </ResponseField>

    <ResponseField name="draftValueCount" type="number">
      Number of values in the current draft definition.
    </ResponseField>

    <ResponseField name="hasUnpublishedChanges" type="boolean">
      `true` when the draft differs from the published version, or when nothing has been published yet.
    </ResponseField>

    <ResponseField name="name" type="string">
      The draft definition's name.
    </ResponseField>

    <ResponseField name="description" type="string">
      The draft definition's description. May be an empty string.
    </ResponseField>

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

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of the last update.
    </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": {
      "dispositions": [
        {
          "id": "a2eb0578-7b5b-4dbf-9ef9-47c9612208cf",
          "agentId": "93431be6-4e2b-489d-96b3-2de573e1a11e",
          "key": "appointment_outcome",
          "state": "enabled",
          "publishedVersionId": "139e85f9-81e8-4371-92b6-649922bc32d1",
          "publishedVersionNumber": 3,
          "draftRevision": 7,
          "draftValueCount": 2,
          "hasUnpublishedChanges": false,
          "name": "Appointment outcome",
          "description": "Did the caller book, and did they ask for a callback?",
          "createdAt": "2026-08-30T15:21:04.118Z",
          "updatedAt": "2026-09-09T11:47:52.903Z"
        },
        {
          "id": "1019d89e-7d92-4087-aaf0-520e4ad21577",
          "agentId": "93431be6-4e2b-489d-96b3-2de573e1a11e",
          "key": "escalation_reason",
          "state": "disabled",
          "publishedVersionId": null,
          "publishedVersionNumber": null,
          "draftRevision": 2,
          "draftValueCount": 1,
          "hasUnpublishedChanges": true,
          "name": "Escalation reason",
          "description": "",
          "createdAt": "2026-09-08T09:02:33.560Z",
          "updatedAt": "2026-09-08T09:15:10.221Z"
        }
      ]
    },
    "errors": null
  }
  ```

  ```json Not Found theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "NOT_FOUND",
        "message": "Agent not found"
      }
    ]
  }
  ```
</ResponseExample>

***

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