---
title: "List Voice Agents"
method: GET
path: "/v2/voice-agents"
---

# List Voice Agents

`GET /v2/voice-agents`

Retrieves a paginated list of voice agents with filtering and sorting options.

## Query parameters

- `skip` integer
- `take` integer
- `search` string
- `sortField` 'createdAt'
- `sortOrder` 'asc' | 'desc'
- `type` string[]
- `language` string[]

## Response `200`

Successful response

- ListVoiceAgentsV2Response
  - `success` boolean
  - `data` object
    - `total` integer — Total count of voice agents matching the filters.
    - `filtered` integer — Number of voice agents in the current page.
    - `voiceAgents` VoiceAgentV2Data[]
      - `id` string, uuid
      - `type` string, nullable
      - `name` string
      - `conversation` object
        - `greetingMessage` string
        - `greetingMessageType` string, nullable
        - `preamble` string
        - `pokeMessages` string[]
        - `params` object
        - `alignment` object
          - `greetingMessage` string
          - `preamble` string
      - `voice` object
        - `voiceId` string, nullable
        - `voiceRecordId` string, nullable
        - `voiceRecord` object, nullable — TTS voice details
          - `id` string, uuid
          - `name` string
          - `provider` string
          - `language` string
          - `image` string, nullable
          - `languageCode` string, nullable
          - `voiceRecord` object, nullable
        - `lang` string, nullable
        - `ttsParams` object, nullable
      - `llm` object
        - `provider` string
        - `model` string
        - `temperature` number
        - `baseUrl` string, nullable
        - `apiKey` string, nullable
      - `callSettings` object
        - `noiseCancellation` string
        - `cancelNoisePer` string, nullable
        - `interrupt` boolean
        - `responseDelay` number
        - `userInactivityTimeout` number
        - `maxCallDuration` number
        - `silenceThreshold` number
        - `backgroundNoise` boolean
        - `thinkingVoice` boolean
        - `speakerIdentification` boolean
        - `agenticRag` boolean
        - `languageDialectSwitcher` boolean
        - `minInterruptionDuration` number
        - `vadActivationThreshold` number
        - `enableAutoGainControl` boolean
        - `sendDenoisedToStt` boolean
        - `genderDetection` boolean
        - `smartCallEnd` boolean
        - `waitForUserToSpeakFirst` number
      - `tools` object[], nullable — Agent tools configuration
      - `knowledgeBaseItemsIds` string[]
      - `voiceDictionaryIds` string[]
      - `phoneNumber` object, nullable
        - `type` string
        - `id` string, uuid
      - `webhookUrl` string, nullable
      - `webhookAuth` object, nullable
      - `workflow` Workflow — Flow Agent workflow graph. Stored on the agent and only meaningful when `type` is `"Flow Agent"`. Holds the graph `nodes`, the `edges` connecting them, and workflow-level `customVariables`. Agent-level configuration (voice, llm, call settings, tools, webhooks) lives in the top-level agent fields, **not** inside this object.
        - `nodes` WorkflowNode[], required — The workflow nodes (the flow graph).
          - union — A workflow node. The concrete shape depends on the `type` discriminator.
            - WorkflowConversationNode — Conversation node — the agent speaks/listens.
              - …
            - WorkflowStartNode — Entry node of the workflow.
              - …
            - WorkflowToolNode — Function-tool execution node.
              - …
            - WorkflowWebToolNode — Web-tool execution node.
              - …
            - WorkflowTransferCallNode — Transfer the call to a phone number.
              - …
            - WorkflowEndCallNode — End the call.
              - …
            - WorkflowTransferAgentNode — Hand off to another voice agent.
              - …
            - WorkflowRouterNode — Routes to a branch based on its transitions.
              - …
            - WorkflowSetLocalVariablesNode — Sets local/static variables (see base `staticVariables`).
              - …
            - WorkflowChangeAgentSettingsNode — Overrides agent settings mid-flow.
              - …
        - `edges` WorkflowEdge[], required — Edges connecting nodes in the builder canvas.
          - `id` string, required — Edge id (nanoid or UUID).
          - `source` string, required — Source node id.
          - `target` string, required — Target node id.
          - `sourceHandle` string
          - `targetHandle` string
          - `type` string — Edge render type (custom ReactFlow types like `deletable` are allowed).
          - `selected` boolean — Canvas selection state.
          - `animated` boolean
          - `hidden` boolean
          - `metadata` object
            - `transitionId` string
            - `label` string
            - `style` object
        - `customVariables` WorkflowVariable[] — Workflow-level variables available across nodes.
          - `id` string, required — Variable id — nanoid or author slug (e.g. `out_var_flights`).
          - `name` string, required — Variable name (snake_case).
          - `description` string
          - `dataType` 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object', required
          - `enumValues` WorkflowEnumValue[]
            - `value` string, required
            - `label` string
          - `isEnumEnabled` boolean
          - `isRequired` boolean
          - `defaultValue` unknown
          - `extractionPrompt` string
          - `sourceNodeId` string
          - `sourceNodeType` string
          - `properties` WorkflowVariable[] — Child variables (for `object` types).
          - `item` WorkflowVariable — recursive
      - `outcomeResponseShape` object, nullable — Expected outcome response structure
      - `resolvedWebTools` object[], nullable — Resolved web tools with overrides applied
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `account` object — User account plan information
        - `plan` string, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `500` — Server Side Error

---

[API](https://skmtc.net/tryhamsa/apis/hamsa-api.md) · [All operations](https://skmtc.net/tryhamsa/apis/hamsa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryhamsa/hamsa-api/versions/ecbeb5d8dc13/schema)