> ## 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. # Get a face detection > Fetches one face's details by ID (bounding box, assigned person, timestamps, thumbnail). Use when you already have a `face_id`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/faces/{face_id} 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/{face_id}: get: tags: - faces summary: Get a face detection description: >- Fetches one face's details by ID (bounding box, assigned person, timestamps, thumbnail). Use when you already have a `face_id`. operationId: get_face parameters: - name: face_id in: path required: true schema: type: string description: >- Face ID (with `face_` prefix) to fetch. Carried by the entries of an asset's `faces` field (returned with `include=faces`). title: Face Id description: >- Face ID (with `face_` prefix) to fetch. Carried by the entries of an asset's `faces` field (returned with `include=faces`). - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Library the face belongs to. Optional if the user has a single library; required when they have multiple. title: Library Id description: >- Library the face belongs to. 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. See `list_faces` for supported values. Accepts multiple `include=` query params or a single comma-delimited value. title: Include description: >- Opt-in expansion fields. See `list_faces` for supported values. Accepts multiple `include=` query params or a single comma-delimited value. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FaceResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: 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. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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. 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 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``. ````