---
title: "List face match jobs"
method: GET
path: "/face-match"
tags: ["Face Match"]
---

# List face match jobs

`GET /face-match`

## Request

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

List all face match jobs

## Query parameters

- `limit` integer
- `offset` integer
- `created_before` string, date
- `created_after` string, date
- `status` 'pending' | 'processing' | 'completed' | 'failed'

## Response `200`

Face match jobs retrieved successfully

- FaceMatchListResponse
  - `object` 'list', required: Object type, always 'list'
  - `total` integer, required: The total number of items
  - `limit` integer, required: The number of items per page
  - `offset` integer, required: The offset of the items
  - `data` object[]
    - `job_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)
    - `match_count` integer: Number of matches found

## Changes

- **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
- **2026-01-02** `9d805815496c`: 3 info
  - added the new optional `query` request parameter `created_after`
  - added the new optional `query` request parameter `created_before`
  - added the new optional `query` request parameter `status`
- **2025-12-22** `fd6b2376db4d`: 1 info
  - endpoint added

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