---
title: "List asset entities"
method: GET
path: "/assets/entities"
tags: ["Assets"]
---

# List asset entities

`GET /assets/entities`

## Request

- Base URL: `https://api.fal.ai/v1`
- URL: `https://api.fal.ai/v1/assets/entities`
- Auth: API key in header `Authorization`

List saved characters, props, environments, styles, and scenes in the authenticated account. Returns their @mention handles and defining reference images. Uses limit and offset pagination; omit types to include every entity type.

**Required permissions:** `assets:read`. Key presets that include them: `API`, `SERVERLESS`, `READONLY`, `FULL`. See [key permissions](https://fal.ai/docs/documentation/model-apis/authentication/key-based#permissions).

## Query parameters

- `limit` integer: Maximum number of entities to return
- `offset` integer, nullable: Number of entities to skip
- `types` string[], nullable: Entity types to include, comma-separated. Omit to list all types.

## Response `200`

Entities

- object
  - `entities` object[], required: Saved smart entities
    - `id` string, required: Smart entity ID
    - `type` 'character' | 'prop' | 'environment' | 'style' | 'scene', required: Smart entity type
    - `name` string, required: Entity display name
    - `handle` string, required: Resolved @mention handle, without the leading @
    - `description` string, nullable, required: Entity visual description
    - `cover_image_url` string, nullable, required: Entity cover image URL
    - `reference_images` string[], required: Defining reference image URLs
    - `is_favorited` boolean, required: Whether the entity is favorited
    - `created_at` string, date-time, required: Creation time in UTC
    - `updated_at` string, date-time, required: Last update time in UTC

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `403`: Access denied
- `404`: Resource not found
- `409`: Invalid request parameters
- `422`: Invalid request parameters
- `429`: Rate limit exceeded
- `500`: Internal server error
- `502`: Upstream asset service error

## Changes

- **2026-10-10** `479db2f9dcd6`: 2 info
  - the endpoint scheme security `readonlyApiKey` was added to the API
  - the endpoint scheme security `apiKey` was removed from the API
- **2026-09-13** `51d8e07444e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fal/apis/platform-apis/changes/assets/entities/get.md)

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) - [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/fal/apis/platform-apis/revisions/3b3b61bedf06?raw)