---
title: "Get face detection results"
method: GET
path: "/face-detect/{face_detection_id}"
tags: ["Face Detection"]
---

# Get face detection results

`GET /face-detect/{face_detection_id}`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/face-detect/{face_detection_id}`
- Auth: HTTP bearer

Retrieve face detection results including all detected faces

## Path parameters

- `face_detection_id` string, uuid, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Face detection results retrieved successfully

- FaceDetection
  - `face_detection_id` string, uuid, required: Unique identifier for the face detection job
  - `frame_extraction_id` string, uuid: ID of the frame extraction used
  - `file_id` string, uuid: ID of the target file
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Status of the face detection job
  - `created_at` number, required: Unix timestamp in milliseconds when the job was created
  - `data` object: Face detection results (only present when status is completed)
    - `object` 'list': Object type, always 'list'
    - `total` integer: Total number of faces detected
    - `limit` integer: Number of faces returned per page
    - `offset` integer: Offset from the start of the faces list
    - `faces` DetectedFace[]: Array of detected faces
      - `id` string, uuid, required: Unique identifier for the detected face
      - `face_bounding_box` FaceBoundingBox, required
        - `height` number, required: Height of the bounding box (normalized 0-1)
        - `width` number, required: Width of the bounding box (normalized 0-1)
        - `top` number, required: Top position of the bounding box (normalized 0-1)
        - `left` number, required: Left position of the bounding box (normalized 0-1)
      - `frame_id` string, uuid, required: ID of the frame where the face was detected
      - `timestamp` number, required: Timestamp of the frame in seconds
      - `thumbnail_url` string: URL of the frame thumbnail (if frame extraction enabled thumbnails)

## Other responses

- `404`: Face detection job not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 2 info
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `500` status
- **2026-03-11** `1d5d6115c0d0`: 2 breaking
  - for the `query` request parameter `limit`, default value `50` was removed
  - for the `query` request parameter `offset`, default value `0` was removed
- **2025-10-16** `e2dce1715ffc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/face-detect/:face_detection_id/get.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)