> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List assistants

> Page through the assistants in your workspace, most recently edited first, with an optional name search.

Returns the assistants in the workspace your API key belongs to, most recently edited first.

<Note>
  This read is a `POST` because a list query is a document: `page`, `size` and `search` arrive typed as themselves instead of being coerced from a query string. It changes nothing.
</Note>

## Body

<ParamField body="page" type="number" default="1">
  1-based page number. Pass back `pagination.next_cursor` from the previous response.
</ParamField>

<ParamField body="size" type="number" default="10">
  Page size, between `1` and `100`.
</ParamField>

<ParamField body="search" type="string">
  Case-insensitive substring of `agent_name`.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.verbeo.ai/v1/assistant/list" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "page": 1, "size": 20, "search": "support" }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.verbeo.ai/v1/assistant/list", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ page: 1, size: 20 }),
  });
  const { data, pagination } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.verbeo.ai/v1/assistant/list",
      headers={"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"},
      json={"page": 1, "size": 20},
  )
  body = res.json()
  assistants, pagination = body["data"], body["pagination"]
  ```
</CodeGroup>

## Response

`200 OK`. Standard envelope plus pagination — see [Responses](/api-reference/responses#list-responses-and-pagination). `next_cursor` is the next **page number**, or `null` on the last page. Stop there: a page past the last one is not an empty list. It answers `500 INTERNAL_ERROR`, and sending it again does not help.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_name": "Customer Support",
      "updated_at": "2026-01-22T14:00:00.000Z",
      "config": {
        "systemPrompt": "You are a friendly support agent for Acme…",
        "voice": { "voiceId": "Charon" }
      },
      "inbound_phone_number": "+15551234567",
      "outbound_phone_number": null
    }
  ],
  "pagination": { "total": 42, "count": 1, "next_cursor": "2" }
}
```

<ResponseField name="data[].config" type="object" required>
  A **two-key extract**, not the assistant's configuration: `systemPrompt` and `voice` only. The full document is every tool definition, analysis field and widget setting — too much to ship twenty of. Fetch [one assistant](/api-reference/assistants/get) for the whole thing.
</ResponseField>

<ResponseField name="data[].inbound_phone_number" type="string | null" required>
  The number routed to this assistant for incoming calls, if any.
</ResponseField>

<ResponseField name="data[].outbound_phone_number" type="string | null" required>
  The number this assistant places calls from, if any.
</ResponseField>

## Paging through every assistant

```javascript theme={null}
let page = 1;
const all = [];

while (page) {
  const res = await fetch("https://api.verbeo.ai/v1/assistant/list", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ page, size: 100 }),
  });
  const { data, pagination } = await res.json();
  all.push(...data);
  page = pagination.next_cursor ? Number(pagination.next_cursor) : null;
}
```


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