# List the candidates and versions of a v2 avatar

URL: https://www.atmee.ai/docs/v2/api/reference/avatars/listAvatarCandidates

`GET /v1/avatars/{avatarId}/candidates`

v2 (`engine: v2`) avatars only. A candidate (a take) is one capture: a
sink latent that decides lip sync and motion for this image and voice
pair, plus a ~3 s talking preview of the avatar saying the preview
message. Candidates are identified by `candidateId`; the `seed` is
informational (the same seed does not reproduce a capture). Promote one
with `PUT /selected_candidate`; with `seedSelection: auto` the first
completed candidate of the current version is promoted for you.

A version is one set of capture inputs: the portrait, the voice
sample and the preview message. Replacing any of them starts a new
version; the takes of older versions are kept. `versions` always
lists every version (oldest first) with what going back to it brings
back. `items` lists the takes of the current version, plus the
serving take if it is older; pass `versions=all` for the takes of
every version.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | path | yes |  |
| `versions` | query | no | Which takes `items` lists. `current` (the default) is the current version's takes and the serving one; `all` adds every older version's. |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | The candidates, oldest first, with presigned preview URLs. | `CandidateListResponse` |
| `401` | Missing or invalid credentials -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `403` | insufficient_scope \| avatar_not_allowed \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| v2_access_required (engine v2 is invite-only and this account has not been let in yet) | none |
| `404` | avatar_not_found | none |
| `409` | not_v2_avatar \| account_ambiguous (a user token of several accounts without X-Account-Id) | none |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of `Candidate` | yes |  |
| `versions` | array of `CandidateVersion` | no | Every version, oldest first. |
| `servingCandidateId` | string | no |  |
| `selectedCandidateId` | string | no | The picked candidate. The avatar serves it once its config is built, a few seconds after the pick. |
| `generation` | integer | yes | The generation of the current version's takes (informational). |
| `seedSelection` | string (`auto`, `manual`) | yes |  |
| `selectionRequired` | boolean | yes | Manual mode and a completed candidate of the current version is waiting to be promoted. |
| `rebuilding` | boolean | yes | A candidate serves while a newer version is still being built. |
| `warning` | string | no | Set when many candidates have been tried for one image and voice pair; usually the pair itself does not work. |