---
title: "Lists voices in a workspace"
method: GET
path: "/voices/v1/voices"
tags: ["VoiceService"]
---

# Lists voices in a workspace

`GET /voices/v1/voices`

Returns SYSTEM voices (visible to all workspaces) plus IVC voices owned by the calling workspace, with optional filtering, sorting, and pagination.

Calling with no parameters (no `filter`, `pageSize`, or `pageToken`) uses a legacy code path that returns the full list in a single response — existing clients continue to work without changes. The unpaginated path is capped at 2000 voices.

## Query parameters

- `filter` string
- `orderBy` string
- `pageSize` integer
- `pageToken` string
- `languages` string[]

## Response `200`

A successful response.

- Inworldvoicev1ListVoicesResponse — Response message for ListVoices.
  - `voices` Inworldvoicev1Voice[] — Voices for this page.
    - `voiceId` string — Voice ID. SYSTEM voices use a simple name (e.g. `Alex`); IVC voices are workspace-prefixed (`{workspace}__{voice}`).
    - `langCode` 'EN_US' | 'ZH_CN' | 'KO_KR' | 'JA_JP' | 'RU_RU' | 'AUTO' | 'IT_IT' | 'ES_ES' | 'PT_BR' | 'DE_DE' | 'FR_FR' | 'AR_SA' | 'PL_PL' | 'NL_NL' | 'HI_IN' | 'HE_IL' — Legacy enum encoding of the voice's language. The full accepted set is much larger than the values listed here: every supported locale has an enum name (the locale with `-` replaced by `_`, uppercased — `en-GB` becomes `EN_GB`). Prefer the `languageCode` string field on new integrations. `AUTO` (or omitting the language entirely) auto-detects the language.
    - `languageCode` string — Canonical wire form of the voice's primary language as a single string (e.g. `en-US`, `es-MX`, `vi`). Populated on every read alongside the legacy `langCode` enum. Immutable after creation.
    - `displayName` string — The human-readable name shown anywhere the voice is listed or selected.
    - `description` string — Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes.
    - `tags` string[] — Free-form labels for filtering, grouping, and discovery (e.g. `british`, `calm`).
    - `name` string — Resource name. Format: `workspaces/{workspace}/voices/{voice}`.
    - `source` 'SYSTEM' | 'IVC' | 'PVC' — Origin of the voice: - `SYSTEM`: Built-in voice provided by Inworld, visible to all workspaces. - `IVC`: Voice cloned from audio or created via Voice Design — owned by your workspace only. - `PVC`: Professional Voice Clone.
    - `gender` 'male' | 'female' | 'neutral' | '' — Voice gender (`male`, `female`, `neutral`). Empty string if unspecified. Voices with no gender are excluded when filtering with an explicit `gender =` predicate.
    - `ageGroup` 'young' | 'middle_aged' | 'elderly' | '' — Age group of the voice (`young`, `middle_aged`, `elderly`). Empty string if unspecified.
    - `categories` string[] — Use-case categories the voice belongs to. Filterable with the `:` (has) operator. Supported values: `companions`, `enterprise`, `education_training`, `developer_assistants`, `healthcare`, `interactive_media`.
    - `promptLanguages` string[] — Languages the voice can handle, in BCP-47 format (e.g. `en-US`). May differ from `langCode` for multilingual voices.
  - `totalSize` integer — Total number of voices matching the filter across all pages.
  - `nextPageToken` string — Opaque cursor to pass as `pageToken` to fetch the next page. Empty string when there are no more pages. **Note:** pagination is offset-based. Concurrent inserts or deletes during a multi-page walk may cause a voice to appear twice or be skipped.

## Other responses

- `400` — Invalid filter expression or unknown sort field.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/revisions/e79009799a0d/schema)