Skip to main content
GET
get task status
Only async endpoints return a taskId. Poll this API until a terminal status (success, failed, or timeout). Sync endpoints (/wav, /m4a, /timing, /downbeats, /upsampleTags, /lyricsInfill, /persona, /getVoxStem, playlist create/add, session prepare) return the result in the same response — do not poll /status for them.
See Suno overview — Async vs Sync. To see whether the account that ran a task is still available, call Check Account Offline (GET, sync). The status body always includes taskId. When the request that created the task stored a gateway x-trace-id, the body also includes traceId. Tasks with no stored trace id omit traceId. Other fields stay the same.

Task Status Values

Polling Best Practices

Use exponential backoff when polling: start with 2-3 second intervals, then gradually increase. Music generation tasks typically take 30-120 seconds depending on the task type.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

taskId
string
required

Task ID

Example:

"1212"

Response

200 - application/json

The task status information

taskId
string
required

Task id.

Example:

"task_1731a9b2f4"

status
enum<string>
required

task status

Available options:
queued,
ready,
running,
stream,
awaiting,
success,
failed,
timeout
createdAt
string<date-time>
required

Task created time (UTC).

Example:

"2025-08-18T02:30:00.000Z"

traceId
string

Trace id of the request that created this task (gateway x-trace-id). Omitted when that task has no stored trace id. Other fields stay the same.

Example:

"82b093e1-b45d-462d-906e-df066fdd084a"

failReason
string

Failure reason when status=FAILED.

Example:

"Audio source not found."

failCode
number

Failure code when status=FAILED.

Example:

4001

data
object

Data associated with the task.

finishAt
string<date-time>

Task finished time (UTC).

Example:

"2025-08-18T02:35:00.000Z"