---
title: "Get a voice agent"
method: GET
path: "/v3/voice/agents/{id}"
tags: ["Voice"]
---

# Get a voice agent

`GET /v3/voice/agents/{id}`

## Request

- Base URL: `https://api.sent.dm`
- URL: `https://api.sent.dm/v3/voice/agents/{id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

The agent as stored, without its signing secret.

## Path parameters

- `id` string, required

## Headers

- `x-profile-id` string, uuid

## Response `200`

The agent

- SentDmServicesEndpointsCustomerAPIv3SharedApiResponseOfVoiceAgentResponse: Standard API response envelope for all v3 endpoints
  - `success` boolean: Indicates whether the request was successful
  - `data` SentDmServicesCommonServicesVoiceContractsVoiceAgentResponse: A voice agent as stored: what was written with every default filled in, plus the signing secret the one time it is shown (on create, and on rotate). The one shape every read of an agent answers with, on /v3/voice/agents and on the admin API the dashboard uses, so the two cannot drift.
    - `id` string: The agent's id, agent_ and a UUID. It is also what the agent connects to the gateway as.
    - `name` string
    - `session_type` string: text or audio.
    - `websocket_url` string, nullable: Where the gateway dials the agent; null when the agent dials in with your API key.
    - `speech` SentDmServicesCommonServicesVoiceVoiceAgentSpeech
      - `setting` string
      - `voice` string
      - `language` string
    - `audio` SentDmServicesCommonServicesVoiceVoiceAgentAudio
      - `sample_rate` integer
    - `greeting` string, nullable
    - `tools` string[]
    - `transfer_targets` SentDmServicesCommonServicesVoiceVoiceAgentParty[]
      - `kind` string
      - `value` string
    - `fallback` SentDmServicesCommonServicesVoiceVoiceAgentParty
      - `kind` string
      - `value` string
    - `limits` SentDmServicesCommonServicesVoiceVoiceAgentLimits
      - `max_call_seconds` integer
      - `max_concurrent_calls` integer
      - `allowed_countries` string[], nullable
    - `transcripts` SentDmServicesCommonServicesVoiceVoiceAgentTranscripts
      - `store` boolean
      - `retention_days` integer
    - `signing_secret` string, nullable: The whsec_ secret the gateway signs its handshake to websocket_url with. Present on create and after a rotate-secret; absent on every other read. Store it now.
    - `created_at` string, date-time
    - `updated_at` string, date-time, nullable
  - `error` SentDmServicesEndpointsCustomerAPIv3SharedApiError: Error information
    - `code` string: Machine-readable error code (e.g., "RESOURCE_001")
    - `message` string: Human-readable error message
    - `details` object, nullable: Additional validation error details (field-level errors)
    - `doc_url` string, nullable: URL to documentation about this error
  - `meta` SentDmServicesEndpointsCustomerAPIv3SharedApiMeta: Request and response metadata
    - `request_id` string: Unique identifier for this request (for tracing and support)
    - `timestamp` string, date-time: Server timestamp when the response was generated
    - `version` string: API version used for this request

## Other responses

- `400`: id is not an agent id
- `401`: Unauthorized - Invalid API credentials
- `403`: Forbidden
- `404`: This account has no such agent

## Changes

- **2026-10-28** `41acb2ceb84d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/changes/v3/voice/agents/:id/get.md)

---

[API](https://skmtc.dev/sentdm/apis/sent-dm-api-v3.md) - [All operations](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/sentdm/apis/sent-dm-api-v3/revisions/bdcca958cac7?raw)