---
title: "List BotInstances (v2)"
method: GET
path: "/v2/bot-instances"
tags: ["Agents"]
---

# List BotInstances (v2)

`GET /v2/bot-instances`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/bot-instances`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Lists BotInstances (an agent's embodiment in one App), most recently
updated first, at most 200. Supports `User JWT` and `B2B Server JWT`.

With no filter the caller's own App is listed. Filters:
- `agentId`: bots of this agent. The agent must be `public` or
  `unlisted`, or owned by the caller. For someone else's agent only
  its bots in Apps the caller created (or, with a B2B Server JWT, in
  the token's App and its child Apps) are listed.
- `appId`: bots in this App. Allowed for whoever manages the App (its
  creator, an admin with `appSettings.read`, a B2B Server JWT for it),
  users of that App and `isSuperAdmin.read`; 403 otherwise.
- `chatJid`: only bots currently in this room.

## Query parameters

- `appId` string
- `agentId` string
- `chatJid` string

## Response `200`

```
{
  ok: true,
  items: [
    {
      id: string,
      agentId: string,
      appId: string,
      userId: string,
      xmppUsername: string,
      status: 'on'|'off',
      joinedRooms: string[],
      lastActiveAt: ISODate|null,
      createdAt: ISODate,
      updatedAt: ISODate
    }
  ],
  results: [...same as items...],
  pagination: {}
}
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: ``` { error: 'Forbidden', code: 'FORBIDDEN' } ```
- `404`: Not Found
- `422`: ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)