---
title: "List trusted reference faces"
method: GET
path: "/v1/face-assets"
tags: ["Face assets"]
---

# List trusted reference faces

`GET /v1/face-assets`

## Request

- Base URL: `https://api.hotapi.ai`
- URL: `https://api.hotapi.ai/v1/face-assets`
- Auth: HTTP bearer

List the organization's trusted reference faces — images and videos automatically registered with the video provider so they can be used as reference faces. Pages oldest-used first and reports `used`/`limit` so a client can see how close the library is to its quota. `unused_since` filters to prune candidates.

## Query parameters

- `limit` string
- `cursor` string
- `unused_since` string

## Response `200`

Successful response.

- object
  - `data` object[], required
    - `id` string, required
    - `source_url` string, required
    - `created_at` string, required
    - `last_used_at` string, required
  - `next_cursor` string, nullable, required
  - `used` number, required
  - `limit` number, required

## Other responses

- `400`: Standard error envelope returned by every error response (OpenAI-style).
- `401`: Standard error envelope returned by every error response (OpenAI-style).
- `404`: Standard error envelope returned by every error response (OpenAI-style).
- `429`: Standard error envelope returned by every error response (OpenAI-style).

---

[API](https://skmtc.dev/hotapi/apis/hotapi-gateway.md) · [All operations](https://skmtc.dev/hotapi/apis/hotapi-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/hotapi/apis/hotapi-gateway/revisions/9b6578b0c389?raw)