Skip to main content
GET
List albums in a library

Authorizations

Authorization
string
header
required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Query Parameters

library_id
string | null

Library to list albums from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

asset_id
string | null

Return only albums that contain this asset. Useful for answering 'which albums is this photo in?' without calling list_album_assets.

ids
string[] | null

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
default:20

Maximum number of albums to return per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200
starting_after_id
string | null

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

Successful Response

data
AlbumResponse · object[]
required

List of albums

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.