> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Avatars

> List reusable AI Avatars available to your organization.

Returns avatars from your organization's primary workspace. Avatars created through the API are stored there so AI Avatar tiles in any workspace can use them.

Each avatar includes `status`. You can use avatars with `pending` or `processing` status immediately; the AI Avatar run waits for processing to finish. Avatars with `failed` status cannot be used.

## Request

```bash theme={null}
curl "https://api.mosaic.so/avatar-profiles" \
  -H "Authorization: Bearer mk_your_api_key"
```

## Response

Returns an object with `avatar_profiles`, an array of avatar profile objects:

| Field                                 | Type                                               | Description                                                                                                                                                                                     |
| ------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avatar_profiles`                     | array                                              | List of avatar profiles available to your organization.                                                                                                                                         |
| `avatar_profiles[].id`                | string UUID                                        | Avatar profile ID. Pass this as `avatar_profile_id` in an AI Avatar tile.                                                                                                                       |
| `avatar_profiles[].video_preview_url` | string URL \| null                                 | Signed video preview URL. This is `null` until a preview/reference video is available.                                                                                                          |
| `avatar_profiles[].name`              | string                                             | Avatar display name.                                                                                                                                                                            |
| `avatar_profiles[].status`            | `"pending" \| "processing" \| "ready" \| "failed"` | Avatar processing state. `ready` means the avatar is fully prepared. `pending` or `processing` can still be used in an AI Avatar tile; the run waits. `failed` means the avatar cannot be used. |
| `avatar_profiles[].status_message`    | string \| null                                     | Error message when `status` is `failed`; otherwise `null`.                                                                                                                                      |

```json theme={null}
{
  "avatar_profiles": [
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "video_preview_url": "https://...",
      "name": "Founder Avatar",
      "status": "ready",
      "status_message": null
    }
  ]
}
```

Use `id` as `avatar_profile_id` in an AI Avatar node.