Get Task

Retrieve the status and output of a task

GET https://sunor.cc/api/v1/task/{taskId}

Get Task

cURL

curl --request GET \
  --url https://sunor.cc/api/v1/task/{taskId} \
  --header 'x-api-key: <x-api-key>'

200

{
  "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

Status	Description
pending	Task has been submitted and is waiting to be processed
running	Task is actively being processed by the upstream provider
success	Task completed successfully. Output is available
failure	Task failed. Check the error field for details. Credits are refunded
timeout	Task 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

Python

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

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