---
title: "List avatars"
method: GET
path: "/ai/avatars"
tags: ["Avatars"]
---

# List avatars

`GET /ai/avatars`

## Request

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

Returns a paginated list of the Telnyx stock avatars and custom avatars available to the authenticated organization. Custom avatars owned by other organizations are never returned. The `image_url` value is suitable for displaying a thumbnail and may be refreshed by listing or retrieving the avatar again. `suggested_voice_id` recommends a compatible Telnyx voice for stock avatars and is an empty string for custom avatars; it does not change an AI Assistant's voice automatically.

## Query parameters

- `page[size]` integer
- `page[number]` integer
- `filter[name]` string
- `filter[id]` string: 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.
- `filter[avatar_type]` 'stock' | 'custom': Whether the avatar is provided by Telnyx or was uploaded by the authenticated organization.

## Response `200`

A page of available avatars.

- AvatarListResponse
  - `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.
  - `meta` AvatarListMeta, required
    - `total_pages` integer, required: Total number of pages for the current filters.
    - `total_results` integer, required: Total number of matching avatars.
    - `page_number` integer, required: Current page number.
    - `page_size` integer, required: Maximum number of avatars returned on each page.

## Other responses

- `400`: The request body, path parameter, or query parameter failed validation.
- `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 `query` request parameter `filter[id]`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$` to the `query` request parameter `filter[id]`
  - the `data/items/id` response's property type changed from no type to `string` for status `200`
  - for the `query` request parameter `filter[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/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)