Skip to main content
GET
https://sunor.cc
/
api
/
v1
/
task
/
{taskId}
Get Task
curl --request GET \
  --url https://sunor.cc/api/v1/task/{taskId} \
  --header 'x-api-key: <x-api-key>'
{
  "code": 123,
  "data": {
    "task_id": "<string>",
    "model": "<string>",
    "type": "<string>",
    "status": "<string>",
    "credits_cost": 123,
    "input": {},
    "output": {},
    "error": {},
    "created_at": "<string>",
    "completed_at": {}
  }
}

​
Get Task

Retrieve the current status, input, and output of a previously created task. If the task is still in progress, sunor will live-poll the upstream provider and return the latest status.

​
Request

GET /api/v1/task/{taskId}

​
Path parameters

​
taskId
string
required
The task ID returned from the Create Task endpoint.

​
Headers

​
x-api-key
string
required
Your API key.

​
Response

​
code
number
HTTP status code (200 on success).
​
data
object
​
task_id
string
The unique task identifier.
​
model
string
The model used (e.g., "suno").
​
type
string
The task type ("music", "lyrics", "upload", or "concat").
​
status
string
Current task status. One of: "pending", "running", "success", "failure", "timeout".
​
credits_cost
number
Credits charged (or frozen) for this task.
​
input
object
The original input parameters submitted with the task.
​
output
object | null
The task output. null while the task is still processing. Contains model-specific results on completion.
​
error
string | null
Error message if the task failed. null otherwise.
​
created_at
string
ISO 8601 timestamp of task creation.
​
completed_at
string | null
ISO 8601 timestamp of task completion. null if not yet completed.

​
Status values

StatusDescription
pendingTask has been submitted and is waiting to be processed
runningTask is actively being processed by the upstream provider
successTask completed successfully. Output is available
failureTask failed. Check the error field for details. Credits are refunded
timeoutTask timed out. Credits are refunded

​
Example responses

​
Task in progress

200
{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "running",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
      "make_instrumental": false,
      "mv": "chirp-v4"
    },
    "output": null,
    "error": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": null
  }
}

​
Task completed

200
{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "success",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer",
      "make_instrumental": false,
      "mv": "chirp-v4"
    },
    "output": {
      "taskType": "music",
      "taskId": "upstream-task-id",
      "status": "completed",
      "progress": "100%",
      "failReason": null,
      "result": [
        {
          "id": "clip-id-1",
          "audio_url": "https://cdn.example.com/audio1.mp3",
          "image_url": "https://cdn.example.com/image1.png",
          "title": "Summer Days",
          "duration": 120
        }
      ]
    },
    "error": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": "2025-01-15T10:32:15.000Z"
  }
}

​
Task failed

200
{
  "code": 200,
  "data": {
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "model": "suno",
    "type": "music",
    "status": "failure",
    "credits_cost": 10,
    "input": {
      "gpt_description_prompt": "A cheerful acoustic guitar song about summer"
    },
    "output": null,
    "error": "Upstream provider returned an error",
    "created_at": "2025-01-15T10:30:00.000Z",
    "completed_at": "2025-01-15T10:30:45.000Z"
  }
}

​
Polling strategy

Tasks typically take 30 seconds to 5 minutes to complete, depending on the task type and upstream provider load.
Poll the Get Task endpoint every 5-10 seconds until the status is "success", "failure", or "timeout". Avoid polling more frequently than once per second.

​
Polling example

import time
import requests

API_KEY = "YOUR_API_KEY"
TASK_ID = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

while True:
    response = requests.get(
        f"https://sunor.cc/api/v1/task/{TASK_ID}",
        headers={"x-api-key": API_KEY},
    )
    data = response.json()["data"]
    status = data["status"]
    print(f"Status: {status}")

    if status in ("success", "failure", "timeout"):
        print("Result:", data["output"])
        break

    time.sleep(5)

​
Errors

StatusDescription
401Missing or invalid API key
404Task not found (invalid ID or task belongs to another user)
500Internal server error