# List All Avatar Groups

Retrieves a list of all available avatar groups. 

<Callout icon="📘" theme="info">
  **Note:**

  * Scroll down to the **Response** section below and expand the status code(s) to view the detailed response schema.
  * Refer to the **RESPONSE** section on the right and choose an example to see how the API response appears for each status code.
</Callout>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "heygen-api",
    "version": "4.0.8"
  },
  "servers": [
    {
      "url": "https://api.heygen.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "x-default": "<your-api-key>"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/avatar_group.list": {
      "get": {
        "summary": "List All Avatar Groups",
        "description": "List all avatar groups",
        "operationId": "list-all-avatar-groups",
        "parameters": [
          {
            "name": "include_public",
            "in": "query",
            "description": "Whether to include all public avatar groups.",
            "schema": {
              "type": "boolean",
              "default": "false"
            },
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": {
                      "error": null,
                      "data": {
                        "total_count": 253,
                        "avatar_group_list": [
                          {
                            "id": "1348c67013e0469c89b303fbd25f4aaa",
                            "name": "Jared",
                            "created_at": 1748548203,
                            "num_looks": 18,
                            "preview_image": "https://files2.heygen.ai/image/a38814d3e10a421e876a77ccd098b1eb/original?Expires=1759512314&Signature=mk-o6kHzrl3C-y~hbuTZoI4OVO~-fW1j5ab1xE8ggHWMaXlvJwLJyVO3KVYgmmK2V3V4saq3Xsr9cQEUuXXEQU4ObiJU8keRlST4FrRNF1Px9z2PPPWeACS5eQHjABjsHRkNXHQEGDRLmJWewO0PUpzrNMvPV9~L1dxd7TOtOTaKLe6sIfbShiKvGE06LGhbuvXRJzl7igL1KTN1WL4rPYibn75uibACaK~cYMk5tMNpI4B~y~6ni5Isw9NgXNydP7JGockFRSiuZ1WkL5I49~y6m2jTa1gYBfK476deuUyvvX8kEIN-~mXh00Tto-gIgCN~PLvuqzOFUAdfHdSKrQ__&Key-Pair-Id=K38HBHX5LX3X2H",
                            "group_type": "PUBLIC_PHOTO",
                            "train_status": "empty",
                            "default_voice_id": null
                          },
                          {
                            "id": "332fca061e49407a9a7e3358253f1185",
                            "name": "Callahan",
                            "created_at": 1750457245,
                            "num_looks": 1,
                            "preview_image": "https://resource2.heygen.ai/image/08287b03dc4044e4968119e9cd8b882f/original",
                            "group_type": "PUBLIC",
                            "train_status": null,
                            "default_voice_id": "3ea8b0a942c44f23bc70653495718682"
                          }
                        ]
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Displays error message when the request fails; null if the request is successful."
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_count": {
                          "type": "integer",
                          "description": "Total number of avatar groups."
                        },
                        "avatar_group_list": {
                          "type": "array",
                          "description": "List of avatar group objects. ",
                          "items": {
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Unique identifier of the avatar group."
                              },
                              "name": {
                                "type": "string",
                                "description": "Name of the avatar group. "
                              },
                              "created_at": {
                                "type": "number",
                                "description": "Unix timestamp when the avatar group was created.",
                                "format": "float"
                              },
                              "num_looks": {
                                "type": "integer",
                                "description": "Number of looks in the avatar group."
                              },
                              "preview_image": {
                                "type": "string",
                                "description": "URL of the avatar group’s preview image."
                              },
                              "group_type": {
                                "type": "string",
                                "description": "Type of the avatar group (e.g., \"PUBLIC_PHOTO\", \"COMMUNITY_PHOTO\").  "
                              },
                              "train_status": {
                                "type": "string",
                                "description": "Training status of the avatar group. "
                              },
                              "default_voice_id": {
                                "type": "string",
                                "description": "Default voice ID assigned to the avatar."
                              }
                            },
                            "type": "object"
                          }
                        }
                      },
                      "description": "Contains the list of avatar groups. "
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```