Sign in
albums

List albums in a library

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.

get/api/albums

Query parameters

library_idstring nullable

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

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

asset_idstring nullable

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

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

idsstring[] 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).

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).

limitinteger

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

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

starting_after_idstring 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.

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

has_moreboolean 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.

Changes

Changed in 2 of the 79 revisions of this API.15

  • 815e0302a98811See the full diff
    • ▲

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

      response-property-list-of-types-widened

    • ○

      the response property became required for the status

      response-property-became-required

  • c3e15c78f2da4See the full diff
    • ○

      added the media type application/json for the response with the status

      response-media-type-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added