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

# List Botsify Agents — Search and Filter Your Workspace

> List all agents in your Botsify workspace with pagination, name search, and ownership filtering. Supports my and shared agent tabs for easy discovery.

Retrieve a paginated list of all agents available in your Botsify workspace. You can narrow results by searching for an agent by name or by filtering to show only agents you own (`my`) versus agents shared with you (`shared`). All query parameters are optional — omitting them returns the first page of all agents.

## Request

<ParamField query="page" type="integer">
  The page number to retrieve. Defaults to `1` when omitted.
</ParamField>

<ParamField query="query" type="string">
  A partial or full agent name to search for. Returns only agents whose names match the provided string.
</ParamField>

<ParamField query="tab" type="string">
  Filter agents by ownership. Accepted values:

  * `my` — return only agents you own
  * `shared` — return only agents shared with you
</ParamField>

<ParamField query="per-page" type="integer">
  The number of agents to return per page. Defaults to the server-side default when omitted.
</ParamField>

## Example

```bash theme={null}
curl --request GET \
  --url 'https://app.botsify.com/api/v1/list-agents?page=1&tab=my&per-page=20' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Search by name:

```bash theme={null}
curl --request GET \
  --url 'https://app.botsify.com/api/v1/list-agents?query=support&tab=my' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Response

A successful `200 OK` response returns a paginated list of agent objects.

| Field | Type | Description |
| - | - | - |
| `data` | array | Array of agent objects for the current page. |
| `total` | integer | Total number of agents matching the query. |
| `per_page` | integer | Number of agents returned per page. |
| `current_page` | integer | The current page number. |
| `last_page` | integer | The total number of available pages. |

```json theme={null}
{
  "data": [
    {
      "bot_id": "12345",
      "bot_name": "Support agent",
      "agent_type": "agent",
      "status": "active"
    }
  ],
  "total": 42,
  "per_page": 20,
  "current_page": 1,
  "last_page": 3
}
```


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