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

# list avatars

> Returns a list of all avatars



## OpenAPI

````yaml https://api.anam.ai/swagger.json get /v1/avatars
openapi: 3.1.0
info:
  title: Anam AI API
  version: '1.0'
servers:
  - url: https://api.anam.ai
    description: Anam API
security:
  - BearerAuth: []
tags:
  - name: Sessions
  - name: Personas
  - name: Avatars
  - name: Voices
  - name: LLMs
  - name: Knowledge
  - name: Tools
  - name: Share Links
paths:
  /v1/avatars:
    get:
      tags:
        - Avatars
      summary: list avatars
      description: Returns a list of all avatars
      operationId: listAvatars
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - in: query
          name: perPage
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of avatars per page (max 100)
        - in: query
          name: search
          schema:
            type: string
          description: Search term to filter avatars by display name
        - in: query
          name: onlyOneShot
          schema:
            type: boolean
            default: false
          description: Only return one-shot avatars
      responses:
        '200':
          description: Successfully retrieved avatars
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Avatar'
                  meta:
                    $ref: '#/components/schemas/Pagination'
              examples:
                default:
                  $ref: '#/components/examples/AvatarListResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Not Found - No avatars found
        '500':
          description: Server error
components:
  schemas:
    Avatar:
      type: object
      description: A face preset that a persona can use as its visual representation.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the avatar.
        displayName:
          type: string
          description: Human-readable name shown in the Lab and share links.
        variantName:
          type: string
          description: >-
            Name of the specific variant (e.g. lighting or pose) within the
            avatar family.
        imageUrl:
          type: string
          format: uri
          description: URL of the still image used as a preview of the avatar.
        videoUrl:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Signed URL for a muted idling MP4 preview of the avatar, if one
            exists. The URL expires after 1 hour; re-fetch the avatar to get a
            fresh URL. `null` when the preview is unavailable or still
            generating.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the avatar was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the avatar was last updated.
        createdByOrganizationId:
          type:
            - string
            - 'null'
          description: >-
            ID of the organization that created the avatar, or `null` for stock
            avatars. IDs may be either UUIDs or nanoid-style strings depending
            on when the organization was created.
        availableVersions:
          type: array
          items:
            type: string
          description: >-
            Internal avatar version identifiers this avatar has generated assets
            for. Current public model mappings are `v1` = `cara-2`, `v2` =
            `cara-3`, and `cara-4-*` = `cara-4-latest`. Use the public
            `avatarModel` request field when selecting a model.
        activeVersion:
          type: string
          description: >-
            Internal avatar version used by default when no explicit
            `avatarModel` is requested. Current public model mappings are `v1` =
            `cara-2`, `v2` = `cara-3`, and `cara-4-*` = `cara-4-latest`.
    Pagination:
      type: object
      description: >-
        Pagination metadata returned alongside the `data` array of every list
        endpoint.
      properties:
        total:
          type: integer
          description: Total number of items across all pages.
        lastPage:
          type: integer
          description: Number of the last page.
        currentPage:
          type: integer
          description: Number of the current page.
        perPage:
          type: integer
          description: Number of items per page.
        prev:
          type:
            - integer
            - 'null'
          description: Number of the previous page, or null if on the first page.
        next:
          type:
            - integer
            - 'null'
          description: Number of the next page, or null if on the last page.
  examples:
    AvatarListResponse:
      summary: A paginated list of avatars
      value:
        data:
          - id: 071b0286-4cce-4808-bee2-e642f1062de3
            displayName: Liv
            variantName: home
            imageUrl: https://lab.anam.ai/persona_thumbnails/liv_home.png
            videoUrl: >-
              https://anam-prod.r2.cloudflarestorage.com/avatars/v2/stock/liv_home/idling_video.mp4?X-Amz-Signature=...
            createdAt: '2026-04-20T10:00:00.000Z'
            updatedAt: '2026-04-20T10:00:00.000Z'
            createdByOrganizationId: null
            availableVersions:
              - v1
              - v2
              - cara-4-3
            activeVersion: v2
        meta:
          total: 1
          lastPage: 1
          currentPage: 1
          perPage: 10
          prev: null
          next: null
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````