---
title: "Get PAL"
method: GET
path: "/v2/pals/{pal_id}"
tags: ["PALs"]
---

# Get PAL

`GET /v2/pals/{pal_id}`

Returns a single PAL by its unique identifier.

By default this endpoint returns the **live** PAL — the version that powers conversations, deployments, and the public API. If the PAL has an active [PAL Builder](https://maker.tavus.io/dev) draft with unpublished changes, add `?source=draft` to read the draft body without publishing it. See [Draft vs live PALs](/sections/conversational-video-interface/pal/draft-and-live) for the full model.

Regardless of `source`, `layers.conferencing` is always returned from the live PAL, because conferencing is deployment config that is owned by the live row (see [PATCH PAL](/api-reference/pals/patch-pal)).

## Query parameters

- `source` 'draft' | 'live'

## Response `200`

- object
  - `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
      - `headers` object — Optional headers to provide to your custom LLM
      - `extra_body` object — Optional parameters to customize the LLM request. For Tavus-hosted models, you can pass `temperature` and `top_p`: - `temperature`: Controls randomness in the model's output. Range typically 0.0 to 2.0. Lower values make output more deterministic and focused, higher values make it more creative and varied. - `top_p`: Controls diversity via nucleus sampling. Range 0.0 to 1.0. Lower values make output more focused on high-probability tokens, higher values allow more diverse token selection. For custom LLMs, you can pass any parameters that your LLM provider supports (e.g., `temperature`, `top_p`, `frequency_penalty`, etc.).
    - `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 (`<username>@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.
  - `is_draft_view` boolean — Present and `true` only when you called this endpoint with `?source=draft` **and** the PAL has an active PAL Builder draft with unpublished changes. Absent otherwise. Signals that the response body is the draft — not the live PAL that powers running conversations.
  - `has_unpublished_changes` boolean — Present with `is_draft_view=true`. `true` when the draft has edits that have not been published to the live PAL.
  - `live_pal_id` string — Present with `is_draft_view=true`. The id of the live PAL that this draft belongs to. This is the same id you queried when using `?source=draft` against a live PAL id.
  - `draft_pal_id` string — Present with `is_draft_view=true`. The id of the underlying draft row. You do not normally need this — patching or publishing the live id routes to the draft automatically — but it is exposed for tooling that wants to address the draft row directly.
  - `published_view_url` string — Present with `is_draft_view=true`. Convenience path for re-reading the live body: `/v2/pals/{live_pal_id}?source=live`.
  - `publish_url` string — Present with `is_draft_view=true`. The PAL endpoint that publishes this draft to live.
  - `routing_message` string — Present with `is_draft_view=true`. Human-readable summary explaining that the body is the unpublished draft and that live traffic still uses the published version until you call `POST /v2/pals/{pal_id}/publish`.

## Other responses

- `400` — Bad Request
- `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)