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

# List agent profiles

`GET /v1/agents`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/agents`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

All active agent profiles in your organization. Agent profiles are optional pre-stored Omni session config; they are not required to open an Omni session. Requires the `omni:session` scope.

## Response `200`

Agents

- AgentList
  - `object` string
  - `data` Agent[]
    - `object` string
    - `agent_id` string
    - `name` string
    - `persona_system_prompt` string, nullable
    - `greeting` string, nullable
    - `greeting_variants` string[]
    - `voice_id` string, nullable
    - `voice_instruct` string: Effective TTS delivery direction for instruct-capable voice tiers. Renders PyAI's natural conversational pace when no override is stored.
    - `brain_model` string
    - `barge_sensitivity` string, nullable
    - `ack_mode` string, nullable
    - `idle_check_in` 'auto' | 'patient' | 'off': Idle check-in patience. Renders `auto` when unset, except support agents render `patient`.
    - `persona_perspective` 'agent' | 'caller': Which side of the call the persona is on. Renders the effective default (`agent`) when unset.
    - `mode` 'default' | 'receptionist' | 'sales' | 'collections': Read-only runtime mode derived from the agent's role (`default`, `receptionist`, `sales`, or `collections`). Set indirectly via the writable `role` field.
    - `role` string, nullable: Role archetype the agent runs as, or null. Writable on create and update.
    - `continuity` boolean: Whether this agent reuses a prior-call caller card when a caller key is available. Default false.
    - `recordings_enabled` boolean
    - `consent_line` string, nullable
    - `language` 'en' | 'fr' | 'es' | 'de' | 'hi' | 'zh' | 'it' | 'pt' | 'ja' | 'ko': Session language for this agent's calls. Renders the effective default (`en`) when unset. Canonical staged route identifiers remain excluded from the public enum until qualification.
    - `vocabulary` string[]: Sanitized Agent vocabulary. An empty list means speech-recognition biasing is off.
    - `keyterms` string[]
    - `goals` string[]
    - `metadata` object
    - `extraction_schema` object, nullable: Post-call extraction JSON Schema, or null.
    - `extraction_webhook_url` string, nullable: Signed delivery target for post-call extraction, or null.
    - `tools` AgentToolBinding[]
      - `tool_id` string, required
      - `enabled` boolean
      - `config` object: Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value.
      - `name` string: Present on agent reads when the tool resolves.
      - `description` string
      - `input_schema` object: Per-call model argument schema. Present on agent reads when the tool resolves.
      - `execution` 'hosted' | 'server' | 'engine' | 'client': Resolved execution mode. Present on agent reads when the tool resolves.
    - `created_at` integer: Unix seconds.
  - `has_more` boolean

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)
- `403`: Key lacks the required scope or the origin is not allow-listed (`code: forbidden | origin_not_allowed`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)