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

# List

> Retrieve a paginated list of the bots in a CometChat app using the REST API, with search and AI bot filtering.

`searchKey` matches the start of a bot's UID, not its name. Results are ordered by UID.

`perPage` defaults to 100 and is capped at 1000. Page through the results rather than assuming one response holds every bot.

### Listing AI bots

`isAIBot` defaults to `false`, so this endpoint returns standard bots only. Pass `isAIBot=true` to list bots flagged as AI bots instead — there is no call that returns both at once.

Agents created through [AI Agents](https://www.cometchat.com/docs/ai-agents.md) are not returned either way.

A `GET /bots?isAIBot=true` response looks like this:

```json theme={null}
{
  "data": [
    {
      "uid": "faq-bot",
      "webhookURL": "https://example.com/webhooks/faq-bot",
      "groupChatSetting": "mentionedMessages",
      "enabled": true,
      "isAIBot": true,
      "createdAt": 1763472000
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 100,
      "current_page": 1,
      "total_pages": 1
    }
  }
}
```

`isAIBot` appears only when it is `true`, because responses omit every property whose value is empty or `false`. That is also why `order-bot` in the response example has no `useBasicAuth`, `username` or `password`.

> [!WARNING]
>
> Every bot with a stored `password` returns it in this response, including bots whose `useBasicAuth` was later set to `false`. A single call can therefore expose the basic auth credentials of every bot in the app. The examples mask the value as `********`.

For the complete error reference, see [Error Guide](https://www.cometchat.com/docs/articles/error-guide.md).


## OpenAPI

````yaml get /bots
openapi: 3.0.0
info:
  title: Chat APIs
  description: Manage messages, users, groups for a particular app using our Chat API.
  version: '3.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: API Keys
    description: The API keys are used to authorise the APIs
  - name: Roles
    description: The roles are used to give user access rights
  - name: Users
    description: The REST collection for users.
  - name: Bots
    description: The bots relay messages from your app to a webhook.
  - name: Auth Tokens
    description: The auth tokens are used to login end users using client SDKs.
  - name: Blocked Users
    description: The REST collections for blocked users.
  - name: Friends
    description: List,add and remove friends by passing UID in path variables
  - name: Groups
    description: The REST collections for groups.
  - name: Banned Users
    description: Ban and Unban user by passing other UID in path variables.
  - name: Group Members
    description: The REST collections for group members.
  - name: Messages
    description: The REST collections for messages.
  - name: Conversations
    description: The REST collections for conversations.
  - name: Restrict Features
    description: Allows Restricting Features
  - name: Metrics
    description: Allows accessing Data Metrics
  - name: Triggers
    description: Allows adding triggers to a webhook.
  - name: Webhooks
    description: Allows accessing Webhooks.
  - name: Notifications
    description: Allows configuring Notifications core.
  - name: Moderation
    description: The REST collections for Moderations.
paths:
  /bots:
    get:
      tags:
        - Bots
      summary: List
      description: Lists the bots of an app
      operationId: list-bots
      parameters:
        - name: searchKey
          in: query
          description: >-
            Performs a LIKE% query, searching for bot UIDs starting with the
            specified characters.
          schema:
            type: string
        - name: isAIBot
          in: query
          description: >-
            Returns only bots flagged as AI bots instead of standard bots.
            Defaults to false. Agents created through AI Agents are not returned
            either way.
          schema:
            type: boolean
            default: false
        - name: perPage
          in: query
          description: >-
            Number of bots to be fetched in a request. The default value is 100
            and the maximum value is 1000.
          schema:
            type: integer
            default: '100'
        - name: page
          in: query
          description: Page Number.
          schema:
            type: integer
            default: '1'
      responses:
        '200':
          description: Lists the bots
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                type: object
              example:
                data:
                  - uid: order-bot
                    webhookURL: https://example.com/webhooks/order-bot
                    groupChatSetting: slashedMessages
                    enabled: true
                    createdAt: 1763472000
                  - uid: support-bot
                    webhookURL: https://example.com/webhooks/support-bot
                    groupChatSetting: mentionedMessages
                    useBasicAuth: true
                    username: support-bot
                    password: '********'
                    enabled: true
                    createdAt: 1763558400
                    updatedAt: 1763561000
                meta:
                  pagination:
                    total: 2
                    count: 2
                    per_page: 100
                    current_page: 1
                    total_pages: 1
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````

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