List Agents API Definition
The List Agents API enables you to retrieve a paginated list of all agents available to the authenticated user. This is useful for managing and monitoring agent deployments across use cases and environments.
List Agents Request and Response
To list agents, send a GET request to /v2/agents. You can include the following optional query parameters to filter and paginate results:
filter(string, optional): Regular expression pattern to match against agent names and descriptionsenabled(boolean, optional): Filter agents by their enabled status (true for active agents only)limit(integer, optional): Maximum number of agents to return (default: 10, maximum: 100)page_key(string, optional): Pagination token for retrieving subsequent pages of results
The response includes an array of agent objects and pagination metadata for accessing additional results when available.
Example Request
GET /v2/agents?filter=support.*&enabled=true&limit=25
Example Response
LIST AGENTS RESPONSE
1
Error Responses
The API returns standard HTTP error codes with detailed error information:
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Invalid query parameters or malformed request |
| 401 | unauthorized | Invalid or missing API key |
| 403 | forbidden | Insufficient permissions for listing agents |
| 429 | rate_limit_exceeded | Request rate limit exceeded |