Skip to main content
GET
List face detections

Query Parameters

asset_id
string | null

Return only faces detected in this asset. Useful for 'show me all the faces in this photo'.

person_id
string | null

Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster.

ids
string[] | null

Look up specific faces by ID (max 200). IDs use the face_ prefix. Accepts multiple ids= query params or a single comma-delimited value (e.g., ids=face_1,face_2).

limit
integer
default:20

Maximum number of faces per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200
starting_after_id
string | null

Cursor for pagination. Pass the id of the last face in the previous response's data to fetch the next page. Omit for the first page.

library_id
string | null

Library to list from. Optional if the user has a single library; required when they have multiple.

include
string[] | null

Opt-in expansion fields. Supported values: cluster_assignment (adds the nested cluster_assignment object — distance_to_person and a top-K candidates list of nearby Persons). Accepts multiple include= query params or a single comma-delimited value (e.g., include=cluster_assignment).

Response

Successful Response

data
FaceResponse · object[]
required

List of faces

has_more
boolean
required

True if there are more faces after this page. Pass the last face's id as starting_after_id to fetch the next page.