> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/faces openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/faces: get: tags: - faces summary: List face detections description: >- 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. operationId: list_faces parameters: - name: asset_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only faces detected in this asset. Useful for 'show me all the faces in this photo'. title: Asset Id description: >- Return only faces detected in this asset. Useful for 'show me all the faces in this photo'. - name: person_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster. title: Person Id description: >- Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster. - name: ids in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- 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`). title: Ids description: >- 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`). - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Maximum number of faces per page (1–200). Defaults to 20. default: 20 title: Limit description: Maximum number of faces per page (1–200). Defaults to 20. - name: starting_after_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- 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. title: Starting After Id description: >- 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. - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Library to list from. Optional if the user has a single library; required when they have multiple. title: Library Id description: >- Library to list from. Optional if the user has a single library; required when they have multiple. - name: include in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- 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`). title: Include description: >- 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`). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedFacesResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PaginatedFacesResponse: properties: data: items: $ref: '#/components/schemas/FaceResponse' type: array title: Data description: List of faces has_more: type: boolean title: Has More description: >- True if there are more faces after this page. Pass the last face's `id` as `starting_after_id` to fetch the next page. type: object required: - data - has_more title: PaginatedFacesResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FaceResponse: properties: id: type: string title: Id description: Unique face identifier with 'face_' prefix asset_id: type: string title: Asset Id description: ID of the asset containing this face person_id: anyOf: - type: string - type: 'null' title: Person Id description: ID of the person this face belongs to (if identified) bounding_box: additionalProperties: type: integer type: object title: Bounding Box description: Face location as {x, y, w, h} coordinates in pixels confidence: anyOf: - type: number - type: 'null' title: Confidence description: >- Detector confidence on a 0-1 scale; higher is more confident among faces detected under the same configuration (values are not comparable across detector generations). Null on legacy faces without a stored score and on manually added faces. source: type: string enum: - automatic - manual title: Source description: >- How this face was added: 'automatic' for detector-found faces, 'manual' for user-drawn face boxes. timestamp_ms: anyOf: - type: integer - type: 'null' title: Timestamp Ms description: For video files, timestamp in milliseconds when face appears asset_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Asset Urls description: 'Asset variants for this face: ''thumbnail'' with face crop' created_at: type: string format: date-time title: Created At description: When this face was detected and recorded updated_at: type: string format: date-time title: Updated At description: When this face record was last updated cluster_assignment: anyOf: - $ref: '#/components/schemas/ClusterAssignmentResponse' - type: 'null' description: >- Cluster-assignment diagnostics for this face. Populated only when `include=cluster_assignment` is requested on the faces endpoint; null otherwise. See `ClusterAssignmentResponse` for the shape. type: object required: - id - asset_id - bounding_box - source - created_at - updated_at title: FaceResponse description: Represents a detected face in an asset with facial recognition data. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AssetVariant: properties: url: type: string title: Url description: URL to fetch this image variant mimetype: type: string title: Mimetype description: MIME type of the served image width: anyOf: - type: integer - type: 'null' title: Width description: Target width in pixels (null if unknown) type: object required: - url - mimetype title: AssetVariant description: A single image variant with its URL, MIME type, and target width. ClusterAssignmentResponse: properties: distance_to_person: anyOf: - type: number - type: 'null' title: Distance To Person description: >- Cosine distance from the face's embedding to its currently-assigned Person's centroid. Lower = better fit. Null when the face is unassigned or when the assigned Person has no centroid. candidates: items: $ref: '#/components/schemas/FaceCandidatePersonResponse' type: array title: Candidates description: >- Persons in the same library that pass the same gate shape as production face assignment, surfaced with deliberately relaxed thresholds so the list is a superset of what the automated path would admit. Sorted ascending by distance. Excludes the face's currently-assigned Person (its distance is in `distance_to_person`). Empty when no eligible Persons pass the gate. type: object title: ClusterAssignmentResponse description: |- Per-face cluster-assignment diagnostics: how well the face fits its currently-assigned Person, and which other Persons are nearby in embedding space. Surfaced via ``include=cluster_assignment`` on the faces endpoints — used by the operator-facing face cleanup dashboard to triage mis-clustered faces. FaceCandidatePersonResponse: properties: person_id: type: string title: Person Id description: Person ID (with 'person_' prefix) of the candidate. name: anyOf: - type: string - type: 'null' title: Name description: >- Display name of the candidate Person, or null for unnamed clusters. Candidates surface the same Persons production assignment considers, which includes unnamed clusters. distance: type: number title: Distance description: >- Cosine distance from the face's embedding to this Person's centroid (lower = closer). type: object required: - person_id - distance title: FaceCandidatePersonResponse description: |- A Person whose centroid is close enough to a given face's embedding that it would be considered for assignment — surfaced under ``ClusterAssignmentResponse.candidates``. ````