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

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](https://docs.bland.ai/api-v2/get/agents-id-dispositions-disposition-id-draft.md). Create one with [Create Disposition](https://docs.bland.ai/api-v2/post/agents-id-dispositions.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.

### Response

**data.dispositions** `array`

Disposition summaries ordered by `createdAt` ascending.

**disposition object**

**id** `string`

Unique identifier for the disposition.

**agentId** `string`

The agent this disposition belongs to.

**key** `string`

Stable slug, unique per agent. Set at creation and never changes.

**state** `string`

`disabled` or `enabled`. A new disposition starts `disabled`. [Publish Disposition](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-publish.md) sets `enabled`; [Disable Disposition](https://docs.bland.ai/api-v2/post/agents-id-dispositions-disposition-id-disable.md) sets `disabled` again.

**publishedVersionId** `string | null`

The most recently published version, or `null` if never published.

**publishedVersionNumber** `number | null`

Sequential number of that version, starting at `1`, or `null` if never published.

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

**draftValueCount** `number`

Number of values in the current draft definition.

**hasUnpublishedChanges** `boolean`

`true` when the draft differs from the published version, or when nothing has been published yet.

**name** `string`

The draft definition's name.

**description** `string`

The draft definition's description. May be an empty string.

**createdAt** `string`

ISO 8601 timestamp of creation.

**updatedAt** `string`

ISO 8601 timestamp of the last update.

**errors** `null | array`

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

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

***

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.