---
title: "List albums in a library"
method: GET
path: "/api/albums"
tags: ["albums"]
---

# List albums in a library

`GET /api/albums`

Returns a paginated list of albums ordered by creation time (newest first), optionally filtered by asset membership or ID. Use this to enumerate a user's albums or to find which albums contain a specific asset (via `asset_id`).

`list_albums` returns album metadata only — to list the assets inside a particular album, use `list_album_assets` or `list_assets` with `album_id`.

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

## Query parameters

- `library_id` string, nullable — Library to list albums from. Optional if the user has a single live (non-trashed) library; required when they have multiple.
- `asset_id` string, nullable — Return only albums that contain this asset. Useful for answering 'which albums is this photo in?' without calling `list_album_assets`.
- `ids` string[], nullable — Look up specific albums by ID (max 200; each ID has the `album_` prefix). Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=album_1,album_2`).
- `limit` integer — Maximum number of albums to return per page (1–200). Defaults to 20.
- `starting_after_id` string, nullable — Cursor for pagination. Pass the `id` of the last album in the previous response's `data` to fetch the next page. Omit for the first page.

## Response `200`

Successful Response

- PaginatedAlbumsResponse
  - `data` AlbumResponse[], required — List of albums
    - `id` string, required — Unique album identifier with 'album_' prefix
    - `name` string, required — Display name of the album
    - `description` string, nullable — Optional description text for the album
    - `asset_count` integer, required — Total number of assets in this album
    - `album_cover_asset_id` string, nullable — ID of the asset displayed as the album cover. May be a server-selected default when the album has no explicit cover set, or null when the album has no live assets.
    - `asset_urls` object, nullable — Asset variants for the album cover: 'thumbnail'
    - `start_date` string, date-time, nullable — The oldest asset date (local_datetime) in the album, or null if empty
    - `end_date` string, date-time, nullable — The newest asset date (local_datetime) in the album, or null if empty
    - `created_at` string, date-time, required — When this album was created
    - `updated_at` string, date-time, required — When this album was last updated
  - `has_more` boolean, required — True if there are more albums after this page. Pass the last album'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)