---
title: "List your music generations"
method: GET
path: "/api/v1/music-generations"
tags: ["Music"]
---

# List your music generations

`GET /api/v1/music-generations`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/music-generations`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Your jobs, newest first, optionally filtered by `state` and `source`. Cursor-paginated (see the pagination convention): pass `next_cursor` back as `cursor` until it is `null`.

## Query parameters

- `limit` integer
- `cursor` string
- `state` 'pending' | 'running' | 'storing' | 'succeeded' | 'failed' | 'blocked' | 'cancelled'
- `source` 'api' | 'studio' | 'agent'

## Response `200`

A page of jobs.

- ListMusicGenerationsResponse200
  - `data` object[], required
    - `id` string, required
    - `object` 'music_generation', required
    - `state` 'pending' | 'running' | 'storing' | 'succeeded' | 'failed' | 'blocked' | 'cancelled', required
    - `model` string, required
    - `prompt` string, required
    - `lyrics` string, nullable, required: The lyrics you sent, or null.
    - `instrumental` boolean, required
    - `duration_seconds` number, required: The length requested (the model default when omitted).
    - `source` 'api' | 'studio' | 'agent', required
    - `error` object, nullable, required
      - `code` 'content_blocked' | 'provider_timeout' | 'provider_error' | 'region_unavailable' | 'output_too_large' | 'cancelled', required
      - `message` string, required
    - `output` object, nullable, required
      - `availability` 'ready' | 'pending_scan' | 'unavailable', required: `ready`: url is set. `pending_scan`: the saved file is still being scanned; re-fetch the job until it changes (self-hosted installs can stay here for up to ~30 minutes). `unavailable`: the file was blocked by the scan or deleted and url will never be set; stop polling.
      - `url` string, nullable, required: Signed download URL, valid until expires_at; re-fetch the job for a fresh one. Set only when availability is `ready`, otherwise null.
      - `expires_at` string, nullable, required: ISO 8601. When url stops working; null whenever url is.
      - `content_type` string, required
      - `duration_seconds` number, required: The length of the song produced, which can differ from the request.
      - `lyrics` string, nullable, required: What the model sang, as plain lines; null for instrumental output or when the provider does not report it.
      - `file_id` string, nullable, required: The Files entry, or null when the song was stored outside Files.
    - `credits` object, required
      - `reserved` number, nullable, required
      - `settled` number, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid credentials.
- `403`: The API key lacks the `ai:generate` scope.
- `405`: The path does not serve this HTTP method.
- `422`: A malformed `cursor`, `limit`, `state` or `source`.
- `429`: Per-user rate limit exceeded.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/d437aaac22ac?raw)