---
title: "Retrieve face detections for a specific file in a collection"
method: GET
path: "/collections/{collection_id}/videos/{file_id}/face-detections"
tags: ["Collections"]
---

# Retrieve face detections for a specific file in a collection

`GET /collections/{collection_id}/videos/{file_id}/face-detections`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/collections/{collection_id}/videos/{file_id}/face-detections`
- Auth: HTTP bearer

Retrieve face detections for a specific file in a collection. Results are paginated with a default limit of 50 faces per request (maximum 100). Use limit and offset parameters to paginate through all results. This API is only available when the collection is created with collection_type 'face-analysis'

## Path parameters

- `collection_id` string, required
- `file_id` string, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

File face detections

- FileFaceDetections
  - `collection_id` string, required: ID of the collection
  - `file_id` string, required: ID of the file
  - `faces` object[], required: Array of detected faces
    - `id` string, uuid, required: Unique identifier for the detected face
    - `face_bounding_box` object, 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)
  - `total` integer, required: Total number of faces detected
  - `limit` integer, required: Maximum number of faces returned per request
  - `offset` integer, required: Number of faces skipped

## Other responses

- `400`: Collection type is not 'face-analysis'
- `404`: Collection, file, or face detection job not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 3 info
  - added the optional property `code` to the response with the `400` status
  - 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-11-07** `3ab05be3c99d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/collections/:collection_id/videos/:file_id/face-detections/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)