> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Video Face Detections

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

For details on how to create a face-analysis collection, see [Create Collection](/api-reference/endpoint/collections/post)


## OpenAPI

````yaml GET /collections/{collection_id}/videos/{file_id}/face-detections
openapi: 3.0.0
info:
  title: Cloudglue API
  description: API for Cloudglue
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 0.7.13
servers:
  - url: https://api.cloudglue.dev/v1
security:
  - bearerAuth: []
paths:
  /collections/{collection_id}/videos/{file_id}/face-detections:
    get:
      tags:
        - Collections
      summary: Retrieve face detections for a specific file in a collection
      description: >-
        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'
      operationId: getFaceDetections
      parameters:
        - name: collection_id
          in: path
          required: true
          description: The ID of the collection
          schema:
            type: string
        - name: file_id
          in: path
          required: true
          description: The ID of the file
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of faces to return
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
        - name: offset
          in: query
          description: Number of faces to skip
          required: false
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: File face detections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileFaceDetections'
        '400':
          description: Collection type is not 'face-analysis'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Collection, file, or face detection job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FileFaceDetections:
      type: object
      properties:
        collection_id:
          type: string
          description: ID of the collection
        file_id:
          type: string
          description: ID of the file
        faces:
          type: array
          description: Array of detected faces
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Unique identifier for the detected face
              face_bounding_box:
                type: object
                required:
                  - height
                  - width
                  - top
                  - left
                properties:
                  height:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Height of the bounding box (normalized 0-1)
                  width:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Width of the bounding box (normalized 0-1)
                  top:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Top position of the bounding box (normalized 0-1)
                  left:
                    type: number
                    minimum: 0
                    maximum: 1
                    description: Left position of the bounding box (normalized 0-1)
              frame_id:
                type: string
                format: uuid
                description: ID of the frame where the face was detected
              timestamp:
                type: number
                minimum: 0
                description: Timestamp of the frame in seconds
              thumbnail_url:
                type: string
                description: >-
                  URL of the frame thumbnail (if frame extraction enabled
                  thumbnails)
            required:
              - id
              - face_bounding_box
              - frame_id
              - timestamp
        total:
          type: integer
          description: Total number of faces detected
        limit:
          type: integer
          description: Maximum number of faces returned per request
        offset:
          type: integer
          description: Number of faces skipped
      required:
        - collection_id
        - file_id
        - faces
        - total
        - limit
        - offset
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````