> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Retrieve a paginated list of agent configurations with optional filtering and sorting. ## OpenAPI ````yaml /api-reference/v1/agents-v1.yaml get /agents openapi: 3.0.3 info: title: Coval Agents API version: 1.0.0 description: | Manage configurations for simulations and evaluations. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Agents description: CRUD operations for AI agent configurations paths: /agents: get: tags: - Agents summary: List agents description: >- Retrieve a paginated list of agent configurations with optional filtering and sorting. operationId: listAgents parameters: - name: filter in: query required: false schema: type: string description: > Filter expression syntax. **Supported fields:** `model_type`, `display_name`, `create_time`, `update_time` **Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., `display_name="Support Agent"`). **Date format:** ISO 8601 (e.g., `2025-10-01T00:00:00Z`) examples: byModelType: value: model_type=MODEL_TYPE_VOICE summary: Filter by model type byDisplayName: value: display_name="Support Agent" summary: Filter by display name (quoted - contains space) combined: value: model_type=MODEL_TYPE_VOICE AND display_name="Support Agent" summary: Combined filters dateRange: value: >- create_time>="2025-10-01T00:00:00Z" AND create_time<="2025-10-31T23:59:59Z" summary: Date range filter - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum number of results per page example: 50 - name: page_token in: query required: false schema: type: string description: | Opaque pagination token from previous response. Do not decode or modify this token. example: eyJvZmZzZXQiOjUwfQ== - name: order_by in: query required: false schema: type: string default: '-create_time' description: > Sort order specification. **Formats:** 1. Dash-prefix: `-create_time` (descending), `display_name` (ascending) 2. Space-separated: `create_time desc`, `display_name asc` **Sortable fields:** `create_time`, `update_time`, `display_name`, `model_type` examples: descending: value: '-create_time' summary: Newest first (default) ascending: value: display_name summary: Alphabetical by name spaceSeparated: value: create_time desc summary: Space-separated format - name: tag_filters in: query required: false style: form explode: true schema: type: array items: type: string maxItems: 20 description: > Filter agents by tags. A resource matches when it has ALL the listed tags (AND-semantics). Repeat the parameter for each tag (e.g., `?tag_filters=production&tag_filters=voice`). example: - production responses: '200': description: Agents retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListAgentsResponse' examples: success: $ref: '#/components/examples/ListAgentsSuccess' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidFilter: $ref: '#/components/examples/InvalidFilterError' invalidPageSize: $ref: '#/components/examples/InvalidPageSizeError' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: ListAgentsResponse: type: object required: - agents properties: agents: type: array description: List of agent resources items: $ref: '#/components/schemas/AgentResource' next_page_token: type: string nullable: true description: Token for fetching next page (null if no more results) example: eyJvZmZzZXQiOjUwfQ== ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Error code enum enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - ALREADY_EXISTS - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field name that caused the error example: page_size description: type: string description: Detailed error description example: page_size must be between 1 and 100 AgentResource: type: object description: > Agent configuration resource. Note: The `active` field (soft delete status) is managed internally and not exposed in API responses. required: - customer_agent_id properties: id: type: string description: Agent resource ID pattern: ^[A-Za-z0-9]{22}$ example: abc123def456ghi789jklm customer_agent_id: type: string description: >- Customer-supplied external id for the agent. Defaults to `id` when not set at creation. example: my-support-agent display_name: type: string description: Human-readable agent name minLength: 1 maxLength: 200 example: Customer Support Agent model_type: $ref: '#/components/schemas/SimulatorType' phone_number: type: string nullable: true description: Phone number in E.164 format or SIP address for voice/SMS agents maxLength: 200 example: '+1234567890' endpoint: type: string nullable: true description: Custom API endpoint URL maxLength: 200 example: https://api.example.com/agent prompt: type: string nullable: true description: Agent instructions/system prompt example: You are a helpful customer support agent... language: type: string nullable: true description: Primary language for the agent example: en attributes: type: object nullable: true description: >- Free-form agent attributes; referenceable in metric prompts as `{{agent.}}`. additionalProperties: true example: company_name: Acme Corp tier: enterprise metadata: type: object description: Simulator-specific configuration (JSONB) additionalProperties: true example: voice: alloy model: gpt-realtime-2 workflows: type: object description: Workflow configuration (JSONB) additionalProperties: true example: {} metric_ids: type: array description: Associated metric IDs items: type: string example: - abc123def456ghi789jklm - def456ghi789jklmabc123 test_set_ids: type: array description: Associated test set IDs items: type: string example: - gT5wq2Hn knowledge_base_ids: type: array description: >- Associated knowledge base entry IDs (read-only, derived from reverse FK) readOnly: true items: type: string example: [] tags: type: array description: Tags associated with this agent items: type: string default: [] example: - production - voice create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: '2025-10-15T14:30:00Z' SimulatorType: type: string description: > Agent type. Active types that can be created via the v1 API: - **MODEL_TYPE_VOICE**: Inbound voice calls (requires phone_number in E.164 format or SIP address) - **MODEL_TYPE_OUTBOUND_VOICE**: Outbound voice calls (requires endpoint webhook URL) - **MODEL_TYPE_CHAT**: Text-based chat agents (requires metadata.chat_endpoint) - **MODEL_TYPE_CHAT_A2A**: A2A JSON-RPC chat agents (requires metadata.chat_endpoint) - **MODEL_TYPE_CHAT_WEBSOCKET**: Text chat over WebSocket (requires metadata.endpoint in direct mode) - **MODEL_TYPE_SMS**: SMS messaging agents (requires phone_number in E.164 format) - **MODEL_TYPE_WEBSOCKET**: WebSocket voice agents (requires metadata.endpoint wss:// URL in direct mode; metadata.initialization_json is optional) - **MODEL_TYPE_OPENAI_REALTIME**: OpenAI Realtime voice-to-voice agents - **MODEL_TYPE_GEMINI_REALTIME**: Gemini Live voice-to-voice agents - **MODEL_TYPE_GROK_REALTIME**: Grok (xAI) Voice Agent voice-to-voice agents enum: - MODEL_TYPE_VOICE - MODEL_TYPE_OUTBOUND_VOICE - MODEL_TYPE_CHAT - MODEL_TYPE_CHAT_A2A - MODEL_TYPE_CHAT_WEBSOCKET - MODEL_TYPE_SMS - MODEL_TYPE_WEBSOCKET - MODEL_TYPE_OPENAI_REALTIME - MODEL_TYPE_GEMINI_REALTIME - MODEL_TYPE_GROK_REALTIME example: MODEL_TYPE_VOICE examples: ListAgentsSuccess: summary: Successful list response value: agents: - id: abc123def456ghi789jklm customer_agent_id: abc123def456ghi789jklm display_name: Customer Support Agent model_type: MODEL_TYPE_VOICE phone_number: '+1234567890' endpoint: https://api.example.com/agent prompt: You are a helpful customer support agent... metadata: voice: alloy model: gpt-realtime-2 workflows: {} metric_ids: - abc123def456ghi789jklm test_set_ids: - gT5wq2Hn knowledge_base_ids: [] create_time: '2025-10-14T12:00:00Z' update_time: '2025-10-15T14:30:00Z' next_page_token: eyJvZmZzZXQiOjUwfQ== InvalidFilterError: summary: Invalid filter expression value: error: code: INVALID_ARGUMENT message: Invalid filter expression details: - field: filter description: >- Unknown field 'invalid_field'. Valid fields: model_type, display_name, create_time, update_time InvalidPageSizeError: summary: Invalid page size value: error: code: INVALID_ARGUMENT message: Invalid page_size details: - field: page_size description: page_size must be between 1 and 100 responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: x-api-key description: Invalid or missing API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````