---
title: "List the BotInstances of an AI Agent (v2)"
method: GET
path: "/v2/agents/{idOrAddress}/bot-instances"
tags: ["Agents"]
---

# List the BotInstances of an AI Agent (v2)

`GET /v2/agents/{idOrAddress}/bot-instances`

## Request

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

A BotInstance is the agent's embodiment in one App (its bot user and
XMPP account there). Supports `User JWT` and `B2B Server JWT`.

A private agent's list is readable by its owner only. For an agent
the caller does not own (a public agent, the Support Agent template
above all, has bots in many accounts' Apps) only bots in Apps the
caller created are returned; platform readers (`isSuperAdmin.read`)
see all of them.

## Path parameters

- `idOrAddress` string, required

## Response `200`

```
{
  ok: true,
  items: [
    {
      id: string,
      agentId: string,
      appId: string,
      appName: string,            // the App's displayName, '' when unknown
      isAppWidgetBot: boolean,    // the App's website widget answers with this bot
      userId: string,             // the bot user
      xmppUsername: string,
      status: 'on'|'off',
      joinedRooms: string[],      // room JIDs
      joinedRoomsDetails: [{ jid: string, name: string, title: string }],
      lastActiveAt: ISODate|null,
      createdAt: ISODate,
      updatedAt: ISODate
    }
  ],
  results: [...same as items...],
  pagination: {}
}
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Private agent of another owner. ``` { error: 'Forbidden', code: 'FORBIDDEN' } ```
- `404`: ``` { error: 'Agent not found', code: 'AGENT_NOT_FOUND' } ```
- `422`: Unprocessable Entity
- `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)