---
title: "List all avatars"
method: GET
path: "/avatars"
---

# List all avatars

`GET /avatars`

Returns an array of Avatar objects available for the user

## Query parameters

- `orientation` 'ASPECT_RATIO_16_9' | 'ASPECT_RATIO_9_16'
- `model` 'ARGIL_V1' | 'ARGIL_ATOM'
- `visibility` 'public' | 'private'

## Response `200`

An array of avatars

- Avatar[]
  - `id` string, uuid
  - `name` string
  - `actorName` string
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `gestures` object[] — A list of labelized gestures available for your avatar.
    - `label` string — A label for user readability. Can be setup from the app's UI.
    - `slug` string — Allows identifying the gesture when using it for a specific moment.
    - `startFrame` number — The startFrame of the source Avatar video to be used as start for the video template.
  - `status` 'NOT_TRAINED' | 'TRAINING' | 'TRAINING_FAILED' | 'IDLE' | 'REFUSED' — * NOT_TRAINED - Initial state after VIDEO mode avatar creation (before training starts) * TRAINING - Avatar is currently training. For IMAGE mode avatars, this is the initial status after creation. * TRAINING_FAILED - Training process failed * IDLE - Avatar is ready to use * REFUSED - Avatar was refused by moderation
  - `width` integer
  - `height` integer
  - `thumbnailUrl` string — The url of the thumbnail of the avatar (low resolution).
  - `coverImageUrl` string — The url of the cover image of the avatar (high resolution).
  - `extras` object — A dictionary of custom key-value pairs to extend the Avatar metadata. Maximum of 5 key-value pairs of 256 characters allowed.
  - `orientation` 'ASPECT_RATIO_16_9' | 'ASPECT_RATIO_9_16'
  - `model` 'ARGIL_V1' | 'ARGIL_ATOM'

## Other responses

- `400` — Unexpected error

## Changes

- **2026-03-06** `c4aa97f4077e` — 1 info
  - added the new optional `query` request parameter `visibility`
- **2025-12-03** `8deefa349e1d` — 1 warning, 1 info
  - removed the optional property `items/createAt` from the response with the `200` status
  - added the optional property `items/createdAt` to the response with the `200` status
- **2025-10-24** `9346a335d8ce` — 5 info
  - added the new optional `query` request parameter `model`
  - added the new optional `query` request parameter `orientation`
  - added the optional property `items/actorName` to the response with the `200` status
  - added the optional property `items/model` to the response with the `200` status
  - …1 more
- **2025-04-10** `0f305512c004` — 1 info
  - added the optional property `items/coverImageUrl` to the response with the `200` status

[Change history](https://skmtc.dev/argildotai/apis/argil-api/changes/avatars/get.md)

---

[API](https://skmtc.dev/argildotai/apis/argil-api.md) · [All operations](https://skmtc.dev/argildotai/apis/argil-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argildotai/argil-api/revisions/f3d0315da0f0/schema)