faces

List face detections

Changed on

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.

get/api/faces

Request

  • Base URL: https://api.gumnut.ai
  • URL: https://api.gumnut.ai/api/faces
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Query parameters

asset_idstring nullable

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

person_idstring nullable

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

idsstring[] nullable

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).

limitinteger

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

starting_after_idstring nullable

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_idstring nullable

Library to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

includestring[] nullable

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

has_moreboolean 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.

Changes

  • 815e0302a988Revision changes
    • breaking

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

    • info

      the response property became required for the status

  • c3e15c78f2daRevision changes
    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status