> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Songs

> List songs in your workspace with optional filtering and search

Retrieve a paginated list of songs in your workspace, sorted by creation date (newest first by default).

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer" default="20">
  1–50. Items per page.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  0-based offset for pagination.
</ParamField>

<ParamField query="q" type="string">
  Search over title, prompt, and tags.
</ParamField>

<ParamField query="status" type="string">
  Filter: `generating`, `ready`, or `failed`.
</ParamField>

<ParamField query="type" type="string">
  Filter: `vocal` or `instrumental`.
</ParamField>

<ParamField query="liked" type="string">
  Filter: `true` to show only liked songs.
</ParamField>

<ParamField query="sort" type="string" default="newest">
  Sort order: `newest` or `oldest`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  True on success
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="songs" type="array">
      Array of Song objects (list format — omits lyrics)
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total count matching filters
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Requested limit
    </ResponseField>

    <ResponseField name="offset" type="integer">
      Requested offset
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether more results exist beyond this page
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.60db.ai/songs?limit=20&offset=0&sort=newest \
    -H "Authorization: Bearer your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const list = await client.music.list({ limit: 20, offset: 0 });
  console.log('Songs:', list.data.songs);
  console.log('Has more:', list.data.has_more);
  ```

  ```python Python theme={null}
  list_result = client.music.list(limit=20, offset=0)
  print('Songs:', list_result['data']['songs'])
  print('Has more:', list_result['data']['has_more'])
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "songs": [
        {
          "id": "song-550e8400",
          "batch_id": "batch-001",
          "variant_index": 0,
          "status": "succeeded",
          "progress": null,
          "mode": "simple",
          "title": "Jazzy Lo-Fi Beat",
          "prompt": "upbeat lo-fi hip hop with jazzy chords",
          "tags": null,
          "instrumental": false,
          "vocal_gender": null,
          "voice_id": null,
          "duration_seconds": 185,
          "audio_url": "https://cdn.60db.ai/songs/song-550e8400.mp3?expires=...",
          "liked": true,
          "played": false,
          "error_message": null,
          "created_at": "2026-09-24T10:30:00Z",
          "completed_at": "2026-09-24T10:32:15Z"
        }
      ],
      "total": 42,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
  ```
</ResponseExample>