---
title: "Get an agent"
method: GET
path: "/v1/agents/{id}"
tags: ["Agents"]
---

# Get an agent

`GET /v1/agents/{id}`

## Request

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

## Path parameters

- `id` string, required

## Response `200`

Agent

- 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.

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: No such agent

---

[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)