---
title: "List agents"
method: GET
path: "/agents"
tags: ["Agents"]
---

# List agents

`GET /agents`

## Request

- Base URL: `https://api.coval.dev/v1`
- URL: `https://api.coval.dev/v1/agents`
- Auth: API key in header `x-api-key`

Retrieve a paginated list of agent configurations with optional filtering and sorting.

## Query parameters

- `filter` string
- `page_size` integer
- `page_token` string
- `order_by` string
- `tag_filters` string[]

## Response `200`

Agents retrieved successfully

- ListAgentsResponse
  - `agents` AgentResource[], required: List of agent resources
    - `created_at` string, date-time, nullable, required: Authoring timestamp; null when unknown.
    - `created_by` string, nullable, required: Canonical author user ID; null when unknown.
    - `updated_at` string, date-time, nullable, required: Authoring timestamp; null when unknown.
    - `updated_by` string, nullable, required: Canonical author user ID; null when unknown.
    - `id` string, required: Agent resource ID
    - `customer_agent_id` string, required: Customer-supplied external id for the agent. Defaults to `id` when not set at creation.
    - `display_name` string, required: Human-readable agent name
    - `model_type` 'MODEL_TYPE_VOICE' | 'MODEL_TYPE_OUTBOUND_VOICE' | 'MODEL_TYPE_CHAT' | 'MODEL_TYPE_CHAT_A2A' | 'MODEL_TYPE_CHAT_WEBSOCKET' | 'MODEL_TYPE_EMAIL' | 'MODEL_TYPE_SMS' | 'MODEL_TYPE_WEBSOCKET' | 'MODEL_TYPE_SDK_WEBSOCKET' | 'MODEL_TYPE_OPENAI_REALTIME' | 'MODEL_TYPE_GEMINI_REALTIME' | 'MODEL_TYPE_GROK_REALTIME' | 'MODEL_TYPE_DEEPGRAM_REALTIME' | 'MODEL_TYPE_TEXT' | 'MODEL_TYPE_LIVEKIT' | 'MODEL_TYPE_DAILY' | 'MODEL_TYPE_NOOP' | 'MODEL_TYPE_OPENAI_ENDPOINT' | 'MODEL_TYPE_TRANSCRIPTION' | 'MODEL_TYPE_TTS' | 'MODEL_TYPE_VOICE_TO_VOICE', required: Agent type returned by the API. Responses can include active types as well as legacy types retained for existing agents. Only values in `SimulatorType` can be supplied when creating or changing an agent type.
    - `phone_number` string, nullable: Phone number in E.164 format or SIP address for voice/SMS agents
    - `endpoint` string, nullable: Custom API endpoint URL
    - `prompt` string, nullable: Agent instructions/system prompt
    - `language` string, nullable: Primary language for the agent
    - `attributes` object, nullable: Free-form agent attributes; referenceable in metric prompts as `{{agent.<key>}}`.
    - `metadata` object: Simulator-specific configuration (JSONB)
    - `workflows` object: Workflow configuration (JSONB)
    - `metric_ids` string[]: Associated metric IDs
    - `test_set_ids` string[]: Associated test set IDs
    - `knowledge_base_ids` string[]: Associated knowledge base entry IDs (read-only, derived from reverse FK)
    - `tags` string[]: Tags associated with this agent
    - `create_time` string, date-time, required: Creation timestamp (ISO 8601)
    - `update_time` string, date-time, nullable: Last update timestamp (ISO 8601)
  - `next_page_token` string, nullable: Token for fetching next page (null if no more results)

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `500`: Internal server error

---

[API](https://skmtc.dev/coval/apis/coval-agents-api.md) - [All operations](https://skmtc.dev/coval/apis/coval-agents-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coval/apis/coval-agents-api/revisions/ba0291fe3911?raw)