API REFERENCE

List Music Generations

On this page

GET/api/music

The calling account's music generations, newest first. Scope follows the standard account override: with no account_id you get your own personal and organization generations; pass account_id to read another account you can access.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/music' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

account_idquery · string

statusquery · string

limitquery · integer

offsetquery · integer

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/music'

Parameters

Query parameters

account_idstring

Optional. Read another account you can access. Defaults to the calling account.

statusstring · enum

Optional. Return only generations in this state.

Values: "pending", "processing", "completed", "failed"

limitinteger

Optional. Maximum generations to return, newest first.

Default: 20

offsetinteger

Optional. Number of generations to skip, for paging.

Default: 0

Responses

200Generations in the requested context, newest first.

application/json

statusstring · enum

Status of the request

Values: "success"

generationsarray<MusicGeneration>

Generations, newest first. Empty when the context has none.

Item properties

idstring

The generation's id. Poll Get Music Generation with this.

format: uuid

statusstring · enum

Lifecycle phase. pending until the workflow picks it up, processing while fal is rendering, then completed or failed.

Values: "pending", "processing", "completed", "failed"

promptstring

The music description the song was generated from.

lyricsstring

The lyrics the song was generated from.

modelstring

The generating model.

duration_secondsnumber | null

Actual length of the generated audio. Null until completed; may be shorter than requested.

audio_urlstring | null

Playable audio URL. Null until the generation completes.

error_messagestring | null

Why the generation failed. Null unless status is failed.

created_atstring

When the generation was created.

format: date-time

updated_atstring

When the generation last changed.

format: date-time

400Invalid query parameter.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

401Unauthorized.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

403Access denied to the specified account_id.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

500Internal server error.

application/json

statusstring · enumrequired

Always error

Values: "error"

missing_fieldsarray<one of>

JSON path segments to the first field that failed validation, e.g. ["lyrics"]

Item properties

oneOf · string 1

string

oneOf · integer 2

integer

errorstringrequired

Human-readable error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "summary": "List music generations",
  "description": "The calling account's music generations, newest first. Scope follows the standard account override: with no `account_id` you get your own personal and organization generations; pass `account_id` to read another account you can access.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "account_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Optional. Read another account you can access. Defaults to the calling account."
    },
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "pending",
          "processing",
          "completed",
          "failed"
        ]
      },
      "description": "Optional. Return only generations in this state."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 50,
        "default": 20
      },
      "description": "Optional. Maximum generations to return, newest first."
    },
    {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      },
      "description": "Optional. Number of generations to skip, for paging."
    }
  ],
  "responses": {
    "200": {
      "description": "Generations in the requested context, newest first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationListResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid query parameter.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the specified `account_id`.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MusicGenerationErrorResponse"
          }
        }
      }
    }
  }
}