---
title: "List AI Agents (v2)"
method: GET
path: "/v2/agents"
tags: ["Agents"]
---

# List AI Agents (v2)

`GET /v2/agents`

## Request

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

Lists Agents visible to the caller, most recently updated first.
Supports `User JWT` and `B2B Server JWT`. With a B2B Server JWT the
caller (and so the owner of agents it creates) is the token's tenant App.

`visibility` selects the set:
- omitted (default): the caller's own agents plus every `public` agent.
  `unlisted` agents of other owners are not listed.
- `public`: public agents only.
- `mine`: the caller's own agents, any visibility.
- `all` / `private`: platform readers (`isSuperAdmin.read`) get every
  agent, or every private agent across all owners. For anyone else
  these values fall back to the default set.

Each item is an Agent object (see `GET /v2/agents/{idOrAddress}`) with
`originAppName`, `botInstancesCount` and the live `totalSiteSourceSize`
filled in.

## Query parameters

- `visibility` 'public' | 'mine' | 'all' | 'private'
- `appId` string
- `category` 'customer-support' | 'persona' | 'entertainment' | 'worker'
- `limit` integer
- `offset` integer

## Response `200`

```
{
  ok: true,
  total: number,              // matching agents, ignoring limit/offset
  items: [Agent],
  results: [Agent],           // same as items
  pagination: { total: number }
}
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Invalid query parameter, or a category that is not on the list. ``` { 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)