---
title: "Get an album"
method: GET
path: "/api/albums/{album_id}"
tags: ["albums"]
---

# Get an album

`GET /api/albums/{album_id}`

## Request

- Base URL: `https://api.gumnut.ai`
- URL: `https://api.gumnut.ai/api/albums/{album_id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Fetches one album's metadata by ID (name, description, cover, counts). Use when you already have an album ID. The JSON response is metadata only and does not include the album's assets — to get the asset IDs or data, use `list_album_assets` or `list_assets` with `album_id`.

## Path parameters

- `album_id` string, required: Album ID (with `album_` prefix) to fetch.

## Response `200`

Successful Response

- AlbumResponse: Represents a collection of assets organized by the user.
  - `id` string, required: Unique album identifier with 'album_' prefix
  - `name` string, required: Display name of the album. Names supplied as text on create or update are trimmed and must not be blank.
  - `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

## 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
- `409`: Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it.
- `422`: Validation Error
- `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header.
- `503`: Authentication provider temporarily unavailable. Retry sign-in later.

## Changes

- **2026-10-16** `7c2860d9eb88`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `503`
- **2026-08-08** `815e0302a988`: 1 breaking, 1 info
  - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422`
  - the response property `detail` became required for the status `422`
- **2026-08-05** `c3e15c78f2da`: 4 info
  - added the media type `application/json` for the response with the status `404`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/albums/:album_id/get.md)

---

[API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) - [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gumnut-ai/apis/gumnut-api/revisions/285ec2f6cd93?raw)
