---
title: "Get an avatar"
method: GET
path: "/ai/avatars/{avatar_id}"
tags: ["Avatars"]
---

# Get an avatar

`GET /ai/avatars/{avatar_id}`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/ai/avatars/{avatar_id}`
- Auth: HTTP bearer

Returns a Telnyx stock avatar or a custom avatar owned by the authenticated organization. A custom avatar belonging to another organization is returned as not found.

## Path parameters

- `avatar_id` string, required: Stable identifier returned by the Avatars API. Discover available stock IDs with GET /v2/ai/avatars and filter[avatar_type]=stock rather than maintaining a fixed list. Custom avatar IDs use the `avatar_` prefix and must belong to the authenticated organization. The service validates that the selected avatar is available.

## Response `200`

The avatar.

- AvatarResponse
  - `data` Avatar, required
    - `id` string, required: Stable identifier returned by the Avatars API. Discover available stock IDs with GET /v2/ai/avatars and filter[avatar_type]=stock rather than maintaining a fixed list. Custom avatar IDs use the `avatar_` prefix and must belong to the authenticated organization. The service validates that the selected avatar is available.
    - `name` string, required: Customer-facing avatar name.
    - `provider` 'telnyx', required: Avatar provider. The first release supports Telnyx avatars.
    - `avatar_type` 'stock' | 'custom', required: Whether the avatar is provided by Telnyx or was uploaded by the authenticated organization.
    - `hosted` true, required: Indicates that avatar rendering runs on Telnyx-operated infrastructure.
    - `image_url` string, uri, required: HTTPS image URL suitable for an avatar selection thumbnail. If the URL expires, list or retrieve the avatar again to refresh it.
    - `image_url_expires_at` string, date-time: Expiration time of `image_url`. Omitted when the URL does not expire.
    - `suggested_voice_id` string: Optional recommended Telnyx text-to-speech voice for this avatar. An omitted field or empty string means no recommendation is available. Custom avatars have no suggested voice. It is informational and selecting the avatar does not automatically change the AI Assistant's configured voice.
    - `content_type` 'image/jpeg' | 'image/png' | 'image/webp': MIME type of a custom avatar image.
    - `size_bytes` integer: Size of a custom avatar image in bytes.
    - `width_px` integer: Decoded width of a custom avatar image.
    - `height_px` integer: Decoded height of a custom avatar image.
    - `created_at` string, date-time: Time when the custom avatar was created.
    - `updated_at` string, date-time: Time when the custom avatar was last updated.

## Other responses

- `400`: The request body, path parameter, or query parameter failed validation.
- `404`: The avatar does not exist or is not available to the authenticated organization.
- `503`: Avatar storage is temporarily unavailable. Retry the operation.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-15** `e33b4a326dda`: 3 breaking, 1 warning, 4 info
  - for the `path` request parameter `avatar_id`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$` to the `path` request parameter `avatar_id`
  - the `data/id` response's property type changed from no type to `string` for status `200`
  - for the `path` request parameter `avatar_id`, the maxLength was set to `128`
  - …4 more
- **2026-10-15** `da303e40b51e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/avatars/:avatar_id/get.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)