GET /v1/playlists/:id

Retrieve a single playlist including every track in it. Works on your own playlists (public or private) and on other users' public playlists.

Use this to drive "move everything from A to B" workflows: fetch the source playlist, collect the track IDs, then pass them to move.

Request

GET https://pub.finetuning.ai/v1/playlists/:id

Path parameters

Parameter	Type	Description
`id`	string	The playlist ID (see GET /v1/playlists)

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Example

curl https://pub.finetuning.ai/v1/playlists/9b2f51e2-4c1a-4b8e-9d3e-2f7a8c641b05 \
  -H "X-API-Key: ft_live_your_key_here"

Response

200 OK

{
  "data": {
    "id": "9b2f51e2-4c1a-4b8e-9d3e-2f7a8c641b05",
    "name": "Focus Beats",
    "description": "Deep work background loops",
    "trackCount": 2,
    "totalDuration": 240,
    "isPublic": false,
    "isOwner": true,
    "createdAt": "2025-01-10 09:00:00",
    "updatedAt": "2025-01-15 10:30:00",
    "tracks": [
      {
        "id": "a4f6c1e9-2d3b-4c8a-9e5f-7b1d0c2a8e64",
        "title": "lofi chill piano night",
        "prompt": "lofi chill piano night",
        "status": "completed",
        "audioUrl": "https://media.finetuning.ai/audio/a4f6c1e9-2d3b-4c8a-9e5f-7b1d0c2a8e64.mp3",
        "duration": 120,
        "isPublic": false,
        "createdAt": "2025-01-15 10:30:00"
      },
      {
        "id": "c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72",
        "title": "modern country instrumental",
        "prompt": "modern country instrumental, acoustic guitar strumming",
        "status": "completed",
        "audioUrl": "https://media.finetuning.ai/audio/c7d2e8a1-5f4b-4e9c-8a6d-3b9f1e0c5a72.mp3",
        "duration": 120,
        "isPublic": true,
        "createdAt": "2025-01-14 14:20:00"
      }
    ]
  }
}

Response fields

Field	Type	Description
`data.id`	string	Unique playlist ID (UUID)
`data.name`	string	Playlist name
`data.description`	string \| null	Playlist description
`data.trackCount`	number	Number of tracks in the playlist
`data.totalDuration`	number	Combined track length in seconds
`data.isPublic`	boolean	Whether the playlist is publicly visible
`data.isOwner`	boolean	Whether the playlist belongs to you
`data.createdAt`	string	Creation timestamp
`data.updatedAt`	string	Last update timestamp
`data.tracks`	array	The tracks, in playlist order
`data.tracks[].id`	string	Track ID — use with the bulk endpoints
`data.tracks[].title`	string	Track title
`data.tracks[].prompt`	string	The tags/prompt used
`data.tracks[].status`	string	`pending`, `processing`, `completed`, `failed`
`data.tracks[].audioUrl`	string \| null	Audio URL (available when `completed`)
`data.tracks[].duration`	number	Track duration in seconds
`data.tracks[].isPublic`	boolean	Whether the track is publicly visible
`data.tracks[].createdAt`	string	Creation timestamp

Errors

Code	Status	Description
`NOT_FOUND`	404	Playlist doesn't exist, was deleted, or is another user's private playlist
`MISSING_API_KEY`	401	X-API-Key header was not provided
`INVALID_API_KEY`	401	API key is malformed, revoked, or does not exist
`INTERNAL_ERROR`	500	Unexpected server error