---
title: "Generate a playlist result set (song, index, or id)"
method: GET
path: "/songs/playlist-generate"
tags: ["Playlists"]
---

# Generate a playlist result set (song, index, or id)

`GET /songs/playlist-generate`

Get a list of song JSON, indexes or id's based on some simple search criteria 'recent' will search for tracks played after 'Popular Threshold' days 'forgotten' will search for tracks played before 'Popular Threshold' days 'unplayed' added in 400002 for searching unplayed tracks

## Query parameters

- `mode` 'recent' | 'forgotten' | 'unplayed' | 'random'
- `filter` string
- `album` string
- `artist` string
- `flag` 0 | 1
- `format` 'song' | 'index' | 'id'
- `offset` integer
- `limit` integer

## Response `200`

Generated list

- union — Depends on the `format` parameter: `song` (default) and `index` return the song list envelope, `id` returns a bare array of song ids.
  - SongsResponse
    - `total_count` integer, required
    - `md5` string, required
    - `song` SongObject[], required
      - `id` string, required
      - `title` string, nullable, required
      - `name` string, nullable, required
      - `artist` NamedReference, required
        - `id` string, required
        - `name` string, nullable, required
        - `prefix` string, nullable, required
        - `basename` string, nullable, required
      - `artists` NamedReference[], required
        - `id` string, required
        - `name` string, nullable, required
        - `prefix` string, nullable, required
        - `basename` string, nullable, required
      - `album` NamedReference, required
        - `id` string, required
        - `name` string, nullable, required
        - `prefix` string, nullable, required
        - `basename` string, nullable, required
      - `albumartist` NamedReference
        - `id` string, required
        - `name` string, nullable, required
        - `prefix` string, nullable, required
        - `basename` string, nullable, required
      - `disk` integer, required
      - `disksubtitle` string, nullable, required
      - `bpm` number, nullable, required
      - `track` integer, required
      - `filename` string, nullable, required
      - `genre` GenreReference[], required
        - `id` string, required
        - `name` string, required
      - `mood` object[], required
        - `id` string, required
        - `name` string, required
      - `playlisttrack` integer, required
      - `time` integer, required
      - `year` integer, required
      - `format` string, nullable, required
      - `stream_format` string, nullable, required
      - `bitrate` integer, nullable, required
      - `stream_bitrate` integer, nullable, required
      - `rate` integer, required
      - `mode` string, nullable, required
      - `mime` string, nullable, required
      - `stream_mime` string, nullable, required
      - `url` string, required
      - `size` integer, required
      - `mbid` string, nullable, required
      - `art` string, nullable, required
      - `has_art` boolean, required
      - `flag` boolean, required
      - `rating` integer, nullable, required
      - `averagerating` number, nullable, required
      - `playcount` integer, required
      - `last_played` string, nullable, required
      - `catalog` string, required
      - `composer` string, nullable, required
      - `channels` integer, nullable, required
      - `comment` string, nullable, required
      - `license` string, nullable, required
      - `publisher` string, nullable, required
      - `language` string, nullable, required
      - `lyrics` string, nullable, required
      - `replaygain_album_gain` number, nullable, required
      - `replaygain_album_peak` number, nullable, required
      - `replaygain_track_gain` number, nullable, required
      - `replaygain_track_peak` number, nullable, required
      - `r128_album_gain` number, nullable, required
      - `r128_track_gain` number, nullable, required
      - `metadata` object
  - string[] — Returned by `format=id`: song ids only, with no envelope.

## Other responses

- `400` — HTTP 400 Bad Request (errors 4705, 4710).
- `401` — HTTP 401 Unauthorized (error 4701).
- `403` — HTTP 403 Forbidden (errors 4700, 4703, 4742).
- `404` — HTTP 404 Not Found (error 4704).
- `500` — HTTP 500 Internal Server Error (error 4702).

## Changes

- **2026-08-09** `535feee32afb` — 1 info
  - added the required property `oneOf[#/components/schemas/SongsResponse]/song/items/mood` to the response with the `200` status
- **2026-08-07** `b152883a37a3` — 1 info
  - added the required property `oneOf[#/components/schemas/SongsResponse]/song/items/bpm` to the response with the `200` status
- **2026-07-28** `48f80d018de4` — 1 info
  - added the required property `oneOf[#/components/schemas/SongsResponse]/song/items/last_played` to the response with the `200` status
- **2026-07-22** `e8e6b266ea29` — 5 info
  - api operation id `playlistGenerateSongs` was added
  - 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 `404`
  - …1 more
- **2026-07-21** `2ff18e50dcc1` — 1 breaking, 1 info
  - added `#/components/schemas/SongsResponse, subschema #2` to the response body `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the response body `oneOf` list for the response status `200`

[Full history](https://skmtc.dev/ampache/apis/ampache-rest-api/changes/songs/playlist-generate/get.md)

---

[API](https://skmtc.dev/ampache/apis/ampache-rest-api.md) · [All operations](https://skmtc.dev/ampache/apis/ampache-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ampache/ampache-rest-api/revisions/42d304fb6867/schema)