Skip to main content
GET
Get a face detection

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

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.