---
title: "Get face match results"
method: GET
path: "/face-match/{face_match_id}"
tags: ["Face Match"]
---

# Get face match results

`GET /face-match/{face_match_id}`

## Request

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

Retrieve face match results including detected faces and similarity scores

## Path parameters

- `face_match_id` string, uuid, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

Face match results retrieved successfully

- FaceMatch
  - `face_match_id` string, uuid, required: Unique identifier for the face match job
  - `face_detection_id` string, uuid: ID of the face detection analysis used
  - `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 match job
  - `created_at` number, required: Unix timestamp in milliseconds when the job was created
  - `source_face_bounding_box` FaceBoundingBox
    - `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)
  - `data` object: Face match results (only present when status is completed)
    - `object` 'list': Object type, always 'list'
    - `total` integer: Total number of face matches found
    - `limit` integer: Number of face matches returned per page
    - `offset` integer: Offset from the start of the face matches list
    - `faces_matches` FaceMatchResult[]: Array of face matches found
      - `id` string, uuid, required: Unique identifier for the face match result
      - `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)
      - `similarity` number, required: Similarity score between source face and detected face (0-100)
      - `frame_id` string, uuid, required: ID of the frame where the match was found
      - `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 match 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-11-01** `07a25f72b264`: 1 breaking, 2 info
  - the response property `source_face_bounding_box` became nullable for the status `200`
  - added `#/components/schemas/FaceBoundingBox` to the `source_face_bounding_box` response property `allOf` list for the response status `200`
  - removed `#/components/schemas/FaceBoundingBox, subschema #2` from the `source_face_bounding_box` response property `oneOf` list for the response status `200`
- **2025-10-16** `e2dce1715ffc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/face-match/:face_match_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)