List face detections
Returns a paginated list of individual face detections (with bounding boxes), ordered by creation time (newest first), optionally filtered by asset, person, or ID. Each row is a single face in a single asset — a person with many photos will have many face rows.
Use list_people instead when the user wants the grouped identities ('list everyone in my library') rather than individual face detections. This tool is useful for curating clustering results, finding unassigned faces, or picking a thumbnail face for a person via update_person.thumbnail_face_id.
Pagination is cursor-based: when has_more is true, pass the id of the last face in data as starting_after_id to fetch the next page.
Query parameters
Return only faces detected in this asset. Useful for 'show me all the faces in this photo'.
Return only faces detected in this asset. Useful for 'show me all the faces in this photo'.
Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster.
Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster.
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).
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).
Maximum number of faces per page (1–200). Defaults to 20.
Maximum number of faces per page (1–200). Defaults to 20.
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.
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 to list from. Optional if the user has a single library; required when they have multiple.
Library to list from. Optional if the user has a single library; required when they have multiple.
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).
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