--- title: "List PALs" method: GET path: "/v2/pals" tags: ["PALs"] --- # List PALs `GET /v2/pals` This endpoint returns a list of all PALs created by the account associated with the API Key in use. ## Query parameters - `limit` integer - `page` integer - `pal_type` 'user' | 'system' — Filter the PALs by type. Possible values: user, system. System PALs are PALs that have been created by Tavus. - `persona_type` 'user' | 'system' — **Legacy alias** for `pal_type`. Still accepted; use `pal_type` in new integrations. ## Response `200` - object - `data` object[] — PALs for the current page; use `total_count` for the full count under the applied filters. - `pal_id` string — A unique identifier for the PAL. - `pal_name` string — A name for the PAL. - `system_prompt` string — The system prompt that will be used by the llm. - `default_face_id` string — The default face_id associated with this PAL if one exists. - `conferencing_email` string, nullable — The PAL's invitable meeting email on `tavusinvite.com`, derived from `layers.conferencing.username`. Present when conferencing is configured. - `document_ids` string[] — Array of document IDs that the PAL has access to. These documents will be available to the PAL in all their conversations. The document_ids are returned in the response of the [Get Document](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints. - `document_tags` string[] — Array of document tags that the PAL has access to. Documents matching these tags will be available to the PAL in all their conversations. - `layers` object - `llm` object - `model` string — The model name that will be used by the llm. - `base_url` string — The base URL for the OpenAI compatible endpoint if you are using your own llm. - `api_key` string — The API key for the OpenAI compatible endpoint if you are using your own llm. - `tools` unknown[] — **Legacy.** Inline OpenAI-style function tools on the PAL. Deprecated - use [Create Tool](/api-reference/tools/create-tool) and [Attach Tools to PAL](/api-reference/pal-tools/attach-tools-to-pal). See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). - unknown - `tts` object - `api_key` string — The API key for the chosen TTS provider. Only required when using private voices. **ElevenLabs:** When using pronunciation dictionaries with your own ElevenLabs key, the key must have the `pronunciation_dictionaries_write` scope (or full account access). See [ElevenLabs API key scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create). - `tts_engine` 'tavus-auto' | 'cartesia' | 'elevenlabs' | 'azure' — The TTS engine that will be used. `tavus-auto` automatically selects the best TTS model for each conversation (recommended). - `external_voice_id` string — The voice ID used for the TTS engine when you want to customize your face's voice. Choose from Cartesia's stock voices by referring to their [Voice Catalog](https://docs.cartesia.ai/api-reference/voices/list), or if you want more options you can consider [ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all). - `voice_settings` object — Optional voice settings to customize TTS behavior. For Cartesia we support inline Cartesia SSML settings (https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags). For ElevenLabs we support: speed (0.7–1.2), stability (0.0–1.0), similarity_boost (0.0–1.0), style (0.0–1.0), use_speaker_boost (boolean). See https://elevenlabs.io/docs/api-reference/voices/settings/get. - `tts_emotion_control` boolean — If true, the TTS engine will be able to control the emotion of the voice. Defaults to true. - `tts_model_name` string — The model name that will be used by the TTS engine. Please double check this with the TTS provider you are using to ensure valid model names. - `pronunciation_dictionary_id` string — The unique identifier of the Tavus pronunciation dictionary attached to this PAL, if any. Provider-specific dictionary IDs are managed internally and are not exposed. - `perception` object - `perception_model` 'raven-1' | 'raven-0' | 'off' — The perception model to use. `raven-1` (default and recommended) provides real-time emotional understanding from user audio, more natural and human-like interactions, plus all visual capabilities from raven-0. `raven-0` (legacy settings [here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1)) offers advanced visual perception only. `off` disables all perception. - `visual_awareness_queries` string[] — Custom queries that Raven continuously monitors in the visual stream. These provide ambient visual context without requiring explicit prompting. - `visual_tool_prompt` string — A prompt that details how and when to use visual tools based on what Raven sees. This helps the PAL understand the context of the visual tools. - `visual_tools` object[] — **Legacy.** Inline vision tools on the PAL. Deprecated - use registry tools with `origin: vision`. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). - `name` string — The name of the tool to be called. - `description` string — A description of what the tool does and when it should be called. - `audio_awareness_queries` string[] — Custom queries that Raven-1 continuously monitors in the audio stream. These provide ambient audio context such as user tone and emotional state. Only available with `raven-1`. - `audio_tool_prompt` string — A prompt that details how and when to use audio tools based on what Raven-1 hears. Only available with `raven-1`. - `audio_tools` object[] — **Legacy.** Inline audio tools on the PAL. Deprecated - use registry tools with `origin: audio`. Raven-1 only. See [Legacy inline tool calling](/sections/troubleshooting#legacy-inline-tool-calling). - `name` string — The name of the tool to be called. - `description` string — A description of what the tool does and when it should be called. - `stt` object — **Note**: Turn-taking is now configured on the [Conversational Flow layer](/sections/conversational-video-interface/pal/conversational-flow). - `stt_engine` 'tavus-auto' | 'tavus-parakeet' | 'tavus-soniox' | 'tavus-whisper' | 'tavus-deepgram-medical' | 'tavus-advanced' — The STT engine used for transcription. `tavus-auto` (default, recommended) automatically selects the best model. `tavus-parakeet` offers highest throughput for English and European languages. `tavus-soniox` is purpose-built for Indian languages. `tavus-whisper` provides broad multilingual coverage. `tavus-deepgram-medical` is optimized for clinical vocabulary (English only). `tavus-advanced` is deprecated. - `hotwords` string — The hotwords that will be used for the STT engine. - `conferencing` ConferencingLayer — [Conferencing layer](/sections/conversational-video-interface/pal/meetings) settings. Provisions a `@tavusinvite.com` email identity so the PAL can be invited to Google Calendar events with Google Meet links and join automatically. Requires `default_face_id` on the PAL. - `username` string, required — Local part of the PAL's meeting email (`@tavusinvite.com`). Stored lowercase. Must start and end with an alphanumeric character; `.`, `_`, and `-` are allowed in between. Usernames matching `botN` (for example `bot1`, `bot42`) are reserved. Globally unique across `tavusinvite.com`. - `allowlist` string[] — Controls who may invite this PAL via calendar. Each entry is an exact email address or a regex matched against the organizer's email. Empty or omitted allows any sender. - `created_at` string — The date and time the PAL was created. - `updated_at` string — The date and time of when the PAL was last updated. - `total_count` integer — The total number of PALs given the filters provided. ## Other responses - `401` — UNAUTHORIZED --- [API](https://skmtc.net/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.net/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/versions/c878e2f6508d/schema)