Skip to main content

​
GET /api/get

Returns an array of AudioInfo objects from Suno’s /api/feed/v2 endpoint. Pass a list of IDs to look up specific songs, or omit ids to return your entire song library. This is the primary endpoint for polling generation status after calling /api/generate.

​
Request

​
Query Parameters

​
ids
string
Comma-separated list of song IDs to retrieve. If omitted, returns all songs in your library.Example: id1,id2,id3
​
page
string
Page number for paginating through results. Applies to both filtered and unfiltered requests.Example: 2

​
Response

An array of AudioInfo objects.
​
id
string
required
Unique identifier for the audio clip.
​
title
string
Title of the song.
​
image_url
string
URL of the cover image associated with the song.
​
lyric
string
Processed lyrics text. Empty lines are stripped from the original prompt.
​
audio_url
string
URL of the generated audio file.
​
video_url
string
URL of the generated video file.
​
created_at
string
ISO 8601 timestamp of when the clip was created.
​
model_name
string
required
Name of the Suno model used to generate the clip (e.g., chirp-v3-5).
​
status
string
required
Current generation status. Possible values:
ValueMeaning
submittedRequest received, not yet queued
queuedWaiting in the generation queue
streamingAudio is being generated and is partially available
completeGeneration finished successfully
errorGeneration failed — check error_message
​
gpt_description_prompt
string
The natural-language description prompt passed to GPT for non-custom generations.
​
prompt
string
The raw prompt / lyrics text used during generation.
​
type
string
Internal clip type from Suno’s metadata.
​
tags
string
Genre and style tags applied to the song.
​
duration
string
Duration of the audio clip.
​
error_message
string
Human-readable error description when status is error, otherwise absent.

​
Error responses

StatusMeaning
500Internal server error

​
Polling for generation status

After calling /api/generate or /api/custom_generate, poll this endpoint every 3–5 seconds until status is "streaming" or "complete". This is the same logic the SDK uses internally when wait_audio is true.
A generation is considered done when all returned clips satisfy: 
status === "streaming" || status === "complete"
If all clips reach status === "error", the generation has failed.

​
Examples

​
Fetch specific songs by ID

curl "http://localhost:3000/api/get?ids=abc123,def456"

​
Fetch all songs (no filter)

curl "http://localhost:3000/api/get"

​
Paginate through your library

curl "http://localhost:3000/api/get?page=2"

​
Example response

[
  {
    "id": "abc123",
    "title": "Midnight Drive",
    "image_url": "https://cdn1.suno.ai/image_abc123.png",
    "lyric": "Neon lights blur past\nThe city never sleeps",
    "audio_url": "https://cdn1.suno.ai/abc123.mp3",
    "video_url": "https://cdn1.suno.ai/abc123.mp4",
    "created_at": "2024-03-15T22:10:00.000Z",
    "model_name": "chirp-v3-5",
    "status": "complete",
    "gpt_description_prompt": "a moody synthwave track about driving at night",
    "prompt": "Neon lights blur past\nThe city never sleeps",
    "type": "gen",
    "tags": "synthwave, moody, electronic",
    "duration": "180",
    "error_message": null
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us