---
title: "List album-asset link records"
method: GET
path: "/api/album-assets"
tags: ["album-assets"]
---

# List album-asset link records

`GET /api/album-assets`

Returns paginated *link* records (lightweight join rows between albums and assets) describing which assets are in which albums — each row contains `album_id` + `asset_id` + link timestamps, not the full asset or album metadata. Use this when you specifically need the junction records (for sync or change tracking).

**For most use cases you want a different tool:** use `list_assets` with `album_id` to get the full asset metadata for a specific album; use `list_albums` with `asset_id` to find which albums contain an asset.

**Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last album-asset in `data` as `starting_after_id` to fetch the next page.

## Query parameters

- `album_id` string, nullable — Return only link records for this album ID. Equivalent to 'list the assets in this album' — in most cases prefer `list_assets` with `album_id` to get the asset metadata directly instead of the lightweight link records.
- `asset_id` string, nullable — Return only link records for this asset ID. Equivalent to 'which albums contain this asset' — in most cases prefer `list_albums` with `asset_id` to get the album metadata directly.
- `ids` string[], nullable — Look up specific album-asset link records by ID (max 200). The ID has the `album_asset_` prefix. Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=album_asset_1,album_asset_2`).
- `limit` integer — Maximum number of link records per page (1–200). Defaults to 20.
- `starting_after_id` string, nullable — Cursor for pagination. Pass the `id` of the last album-asset in the previous response's `data` to fetch the next page. Omit for the first page.
- `library_id` string, nullable — Library to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

## Response `200`

Successful Response

- PaginatedAlbumAssetsResponse
  - `data` AlbumAssetResponse[], required — List of album-asset links
    - `id` string, required — Unique album_asset identifier with 'album_asset_' prefix
    - `album_id` string, required — ID of the album
    - `asset_id` string, required — ID of the asset
    - `created_at` string, date-time, required — When this link was created
    - `updated_at` string, date-time, required — When this link was last updated
  - `has_more` boolean, required — True if there are more album-asset links after this page. Pass the last album-asset's `id` as `starting_after_id` to fetch the next page.

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)