Skip to main content
GET
/
v2
/
faces
List Faces
curl --request GET \
  --url https://tavusapi.com/v2/faces \
  --header 'x-api-key: <api-key>'
{
  "data": [
    {
      "face_id": "r90bbd427f71",
      "face_name": "My Face",
      "thumbnail_video_url": "<string>",
      "training_progress": "100/100",
      "status": "completed",
      "created_at": "<string>",
      "face_type": "user'",
      "model_name": "phoenix-3"
    }
  ],
  "total_count": 42
}
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
limit
integer

The number of faces to return per page.

​
page
integer

The page number to return

​
verbose
boolean

If set to true, the response will include additional face data such as the face type.

​
face_type
enum<string>

If set to user, the response will only include user faces. If set to system, the response will only include stock faces.

Available options:
user,
system
​
face_ids
string

A comma separated list of face ids to filter the response by. Example: face_ids=r90bbd427f71

​
model_name
string

Filter the list to faces trained on a specific Phoenix model (e.g. phoenix-3, phoenix-4).

Response

​
data
object[]

Faces for the current page; use total_count for the full count under the applied filters.

​
total_count
integer

The total number of faces given the filters provided.

Example:

42