Skip to main content
GET
Get a face detection

Authorizations

Authorization
string
header
required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Path Parameters

face_id
string
required

Face ID (with face_ prefix) to fetch. Carried by the entries of an asset's faces field (returned with include=faces).

Query Parameters

library_id
string | null

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

include
string[] | null

Opt-in expansion fields. See list_faces for supported values. Accepts multiple include= query params or a single comma-delimited value.

Response

Successful Response

Represents a detected face in an asset with facial recognition data.

id
string
required

Unique face identifier with 'face_' prefix

asset_id
string
required

ID of the asset containing this face

bounding_box
Bounding Box · object
required

Face location as {x, y, w, h} coordinates in pixels

source
enum<string>
required

How this face was added: 'automatic' for detector-found faces, 'manual' for user-drawn face boxes.

Available options:
automatic,
manual
created_at
string<date-time>
required

When this face was detected and recorded

updated_at
string<date-time>
required

When this face record was last updated

person_id
string | null

ID of the person this face belongs to (if identified)

assignment_source
enum<string> | null

How the current person assignment was set: 'assigned' at ingest, 'clustered' by clustering, 'auto_merged' by automatic person merge, or 'manual' by an explicit client assignment, confirmation, or manual person merge. Manual does not imply individual human review. Null when unassigned or when provenance is unknown. Separate from source, which describes how the face box was created.

Available options:
assigned,
clustered,
auto_merged,
manual
confidence
number | null

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.

timestamp_ms
integer | null

For video files, timestamp in milliseconds when face appears

asset_urls
Asset Urls · object | null

Asset variants for this face: 'thumbnail' with face crop

cluster_assignment
ClusterAssignmentResponse · object | null

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.