# List All Avatars in One Avatar Group
Retrieves all avatars that belong to a specific avatar group.
**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.
# 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": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/v2/avatar_group/{group_id}/avatars": {
"get": {
"summary": "List All Avatars in one avatar group",
"description": "List all avatars in one avatar group",
"operationId": "list-all-avatars-in-one-avatar-group",
"parameters": [
{
"name": "group_id",
"in": "path",
"description": "Unique identifier of the avatar group. Can be retrieved from List All Avatar Groups endpoint.",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {
"200": {
"description": "Avatars retrieved successfully - Expand to view the detailed response schema.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": {
"error": null,
"data": {
"avatar_list": [
{
"id": "0a315279757841e9ad2af34a5f7232ec",
"image_url": "https://files2.heygen.ai/image/be610f15a53640e3a2805438687d124f/original?Expires=1759511270&Signature=KfR9jYaTPpc~zmziovsJNclt9QQCfH8pegLkTrk0KDUQ1fEnmpBubcauiGdK6COvLh60wFVyNuKZQNa-jzed-ykhLaA2vTEJC6bg~GUZXYy6mhuXhloulMYvuG9X1ryjywCZ4~7I1crBVCQS1fsqOi9YuqrUoHYdNDZFooELqiJCCXzyVXGMBrxSOwmXZRXKGZN1niumQsYjXynsVWN93PeJXXGW28RIhWGQM7J87QgY~TsBG8q8-jlIT2OMnkeyaQSMa9ENNVnxAWwvnvY0DZ99CXxUaXu2Ni7mMGLpCGLFxXjNNryJ8nZveNgtUMDgcWhzC8Jp8jI0U9UcdtQsaw__&Key-Pair-Id=K38HBHX5LX3X2H",
"created_at": 1730251663,
"name": "Outside 3",
"status": "completed",
"group_id": "1348c67013e0469c89b303fbd25f4aaa",
"is_motion": false,
"motion_preview_url": null,
"business_type": null,
"upscale_availability": {
"available": false,
"reason": "Preset photo avatar look not supported for upscale"
},
"upscaled": false,
"background_sound_effect": null,
"default_voice_id": null,
"moderation_msg": null
},
{
"id": "e64fa6ebd10947efb58675c3ea273a6a",
"image_url": "https://files2.heygen.ai/image/4b288efaf3fe46058465febb296ae78a/original?Expires=1759511270&Signature=Nzqpkcuq02H3wpn1cEq1YCApZsOpksggVLD0o2Ma0Ug04CBY30YbGYJxR1F7tlLSz8DD67IYZTveDKOuKWIvmTEl8F7L3zK~23WDvkNNs67OHNhWyXy3POM8RvnflSaTpq3jOzIs~LTg7p1CXbjEBkhg-5ZSm2a42ztfEvY4u9cOGwEz1cWUQlzb5hsXUuHxSfVCiRy084JqAA8g1vgxO-x5kVRXsXfb2k8YWJyXXkllfYWwc-civQAiscAnbxi0QjN5B8RacJ7fX4xcksyOqbtxF9bJPfq5tqQvV~IASZsaIH6tRxbyjnDcJ4YwhIzIk2Jh8S7YZlPYDHux4BFmtA__&Key-Pair-Id=K38HBHX5LX3X2H",
"created_at": 1730251663,
"name": "Smoothie",
"status": "completed",
"group_id": "1348c67013e0469c89b303fbd25f4aaa",
"is_motion": false,
"motion_preview_url": null,
"business_type": null,
"upscale_availability": {
"available": false,
"reason": "Preset photo avatar look not supported for upscale"
},
"upscaled": false,
"background_sound_effect": null,
"default_voice_id": null,
"moderation_msg": null
}
]
}
}
}
},
"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": {
"avatar_list": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the avatar."
},
"image_url": {
"type": "string",
"description": "URL of the avatar's image. "
},
"created_at": {
"type": "number",
"description": "Unix timestamp when the avatar was created.",
"format": "float"
},
"name": {
"type": "string",
"description": "Name of the avatar look. "
},
"status": {
"type": "string",
"description": "Processing status of the avatar (e.g., \"completed\"). "
},
"group_id": {
"type": "string",
"description": "Identifier of the group the avatar belongs to."
},
"is_motion": {
"type": "boolean",
"description": "Whether the avatar is a motion (animated) avatar. "
},
"motion_preview_url": {
"type": "string",
"description": "URL of the motion avatar's preview. Returns null if not available. "
},
"business_type": {
"type": "string",
"description": "Indicates the origin of the avatar (e.g., \"generated\" or \"uploaded\")."
},
"upscale_availability": {
"type": "object",
"description": "Information about the avatar's upscaling availability. ",
"properties": {
"available": {
"type": "boolean",
"description": "Whether the avatar can be upscaled. "
},
"reason": {
"type": "string",
"description": "Reason why the avatar cannot be upscaled (if applicable). "
}
}
},
"upscaled": {
"type": "boolean",
"description": "Whether the avatar has already been upscaled. "
},
"background_sound_effect": {
"type": "string",
"description": "Background sound effect applied to the avatar. Returns null if none. "
},
"default_voice_id": {
"type": "string",
"description": "Default voice ID assigned to the avatar. "
},
"moderation_msg": {
"type": "string",
"description": "Message describing the result of content moderation for the avatar. Provides the reason if the avatar is rejected, suspended, or pending review. Returns null if no moderation issues exist."
}
},
"type": "object"
},
"description": "A collection of available avatar objects in the specified group."
}
},
"description": "Contains the list of avatars. "
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```