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

# List Assets

`GET /assets/`

List assets with pagination and optional filtering.

This endpoint returns a paginated list of assets belonging to your organization.
You can optionally filter by a specific list of asset IDs, by the agent that
produced them, and/or by the specific run that produced them.

**Primary Use Cases:**
- Browse all your assets with pagination
- Retrieve specific assets using their IDs
- Fetch every asset produced by a given agent across all its runs
- Fetch every asset produced by a specific run
- Verify the provenance of a known asset list (combine `asset_ids` with
  `agent_id` or `run_id`)

**Pagination Parameters:**
- `limit`: Maximum number of items to return (default: 20, max: 100)
- `cursor`: Cursor for pagination (optional)

**Filtering Parameters:**
- `asset_ids`: Optional list of UUIDs to filter specific assets.
- `agent_id`: Optional agent UUID. Returns all assets produced by that agent
  across every run.
- `run_id`: Optional run UUID. Returns all assets produced by that single run.
- All three filters compose as an AND. For example,
  `?asset_ids=<id>&agent_id=<agent>` returns the asset only if it was
  produced by that agent; otherwise the response is empty.
- `agent_id` and `run_id` only match assets that were produced by an agent
  run, so uploaded assets are excluded when either filter is set.

**Response:**
Returns a `CursorPaginatedResponse` object containing:
- `data`: List of `AssetSummary` objects. Each asset includes `agent_id` and
  `run_id` so you can correlate it back to the agent / run that produced it.
- `has_more`: Indicates if there are more results available
- `next_cursor`: Cursor for the next page

**Access Control:**
- Only assets belonging to your organization are returned
- Assets not found or not accessible are silently excluded

## Query parameters

- `asset_ids` string[], nullable — Restrict the result to this list of asset IDs. Combines with `agent_id` / `run_id` as an AND — an asset is only returned if it is in this list and matches every other filter.
- `agent_id` string, uuid, nullable — Return only assets produced by this agent (across all its runs). Uploaded assets are never returned by this filter.
- `run_id` string, uuid, nullable — Return only assets produced by this specific run. Uploaded assets are never returned by this filter.
- `external_id` string, nullable — Return the asset you uploaded with this reference id. Use after a 409 on upload to fetch the existing asset.
- `limit` integer — Maximum number of items to return
- `cursor` string, nullable — Cursor for pagination (from next_cursor)

## Headers

- `X-Organization-Id` string, nullable — Active organization ID for multi-org support

## Response `200`

Successful Response

- CursorPaginatedResponseAssetSummary
  - `data` AssetSummary[], required
    - `id` string, uuid, required — Unique asset identifier
    - `external_id` string, nullable — Client-supplied reference id provided at upload, if any
    - `asset_type` 'reference' | 'intermediate' | 'output', required — Classification of assets by their role in workflows.
    - `media_type` 'image' | 'video' | 'audio' | 'file', required — Primary media categories for assets.
    - `media_extension` 'png' | 'jpg' | 'jpeg' | 'svg' | 'heic' | 'heif' | 'avif' | 'webp' | 'mp4' | 'wav' | 'mp3' | 'mov' | 'webm' | 'pdf' | 'docx' | 'csv' | 'txt' | 'json' | 'md' | 'ttf' | 'otf' | 'woff' | 'woff2', required
    - `visibility` 'public' | 'shared' | 'private', required
    - `bookmarked` boolean — Whether the asset is bookmarked
    - `archived` boolean — Whether the asset is archived
    - `downloaded` boolean — Whether the asset has been downloaded before
    - `created_at` string, date-time, required — When the asset was created
    - `updated_at` string, date-time, required — When the asset was last modified
    - `url` string, required — CDN URL for the asset (thumbnail/preview size)
    - `large_url` string, nullable — CDN URL for the full-resolution version
    - `agent_id` string, uuid, nullable — ID of the agent that produced this asset. Null for uploaded assets.
    - `run_id` string, uuid, nullable — ID of the run that produced this asset. Null for uploaded assets.
  - `has_more` boolean, required
  - `next_cursor` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/pletor/apis/pletor-public-api.md) · [All operations](https://skmtc.dev/pletor/apis/pletor-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pletor/pletor-public-api/revisions/e5c350c02ffb/schema)