Retrieve a job

November 14, 2026 (November 16, 2026)

Table of contents

  1. Request Headers
  2. Responses
  3. Model
  4. Examples
  5. Try It

Fetch a job by its jobid. POST /music and POST /music/stems return one. After an async request, or a sync one that answered 202, poll this endpoint until status is completed or failed.

Songs take 20 seconds to about 2 minutes and a stem split about 1.5 minutes, so polling every 10 seconds is enough. A job still running 30 minutes after it started fails with 504 when it is read. ACE Music may still finish it later, and a later read then shows it completed.

Every read asks ACE Music for the job’s songs, so links are always fresh: each song’s playUrl and the stem track links are read again. playUrl is a direct link to the same MP3 for players, valid until playUrlExpires (about an hour): some browsers (Brave) block the redirect behind audioUrl. Store audioUrl, play playUrl. Stem track links are valid for 24 hours from the read.

After the job ends, nothing of it is kept on our side: the record is rebuilt from the songs ACE Music keeps in the account’s Library. A song deleted since, with DELETE /music/songId or on acemusic.ai, is listed as { songId, taskId, status: "deleted" } with no links, and the job keeps its status from the song still there. A job none of whose songs ACE Music has any more answers 404, and any job answers 410 once it is older than 7 days.

Instead of polling, pass replyUrl (and optionally replyRef) with the POST: when the job completes or fails, the API sends one POST of this same job record, as JSON, to that URL. See Model.

https://api.useapi.net/v1/acemusic/jobs/jobid

  • jobid is URL-encoded in the path (it contains : and @), for example j1114201530412583907m-u1234-email%3Aexample%40example.com-task%3Aso_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot%3Aacemusic.
Request Headers
Authorization: Bearer {API token}
Responses
  • 200 OK

    A song job (the songs are cut short here, see POST /music for full songs):

    {
      "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic",
      "type": "music",
      "status": "completed",
      "email": "example@example.com",
      "created": "2026-11-14T20:15:30.412Z",
      "model": "ace-step-1.5-xl",
      "modelUsed": "ace-step-1.5-xl",
      "songs": [
        {
          "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
          "taskId": "so_3f9c2a7d81e64b05a9d2c4e7",
          "status": "succeeded",
          "title": "Farmers Market Sunshine",
          "model": "ace-step-1.5-xl",
          "duration": 135.02,
          "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…",
          "playUrlExpires": "2026-11-14T21:17:21.000Z",
          "coverUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498",
          "kind": "original",
          "score": false
        },
        {
          "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "taskId": "so_b6e14d0c9a7f4382be51f0a3",
          "status": "succeeded",
          "title": "Farmers Market Sunshine",
          "model": "ace-step-1.5-xl",
          "duration": 135.02,
          "audioUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3",
          "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201723Z&X-Amz-Expires=3599&…",
          "playUrlExpires": "2026-11-14T21:17:22.000Z",
          "coverUrl": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611",
          "kind": "original",
          "score": false
        }
      ],
      "completed": "2026-11-14T20:16:14.205Z",
      "job_state": "completed",
      "outputs": [
        {
          "ok": true,
          "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
          "thumbnail_url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7-cover.jpg?v=1794685678498"
        },
        {
          "ok": true,
          "url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3.mp3",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "thumbnail_url": "https://acemusic.ai/data/so_b6e14d0c9a7f4382be51f0a3-cover.jpg?v=1794685679611"
        }
      ]
    }
    

    The same job after its second song was deleted with DELETE /music/songId, its song cut short the same way:

    {
      "jobid": "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic",
      "type": "music",
      "status": "completed",
      "email": "example@example.com",
      "created": "2026-11-14T20:15:30.412Z",
      "model": "ace-step-1.5-xl",
      "modelUsed": "ace-step-1.5-xl",
      "songs": [
        {
          "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
          "taskId": "so_3f9c2a7d81e64b05a9d2c4e7",
          "status": "succeeded",
          "title": "Farmers Market Sunshine",
          "audioUrl": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "playUrl": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/audio/202611/….mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20261114T201722Z&X-Amz-Expires=3599&…",
          "playUrlExpires": "2026-11-14T21:17:21.000Z"
        },
        {
          "songId": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "taskId": "so_b6e14d0c9a7f4382be51f0a3",
          "status": "deleted"
        }
      ],
      "completed": "2026-11-14T20:16:14.205Z",
      "job_state": "completed",
      "outputs": [
        {
          "ok": true,
          "url": "https://acemusic.ai/data/so_3f9c2a7d81e64b05a9d2c4e7.mp3",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
          "thumbnail_url": null
        },
        {
          "ok": false,
          "url": null,
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": null,
          "ref": "user:1234-example@example.com-song:so_b6e14d0c9a7f4382be51f0a3",
          "thumbnail_url": null
        }
      ]
    }
    

    A stem split, read a few minutes after it finished. Its track links are signed again on every read, so expires and each expires_at are 24 hours after the read:

    {
      "jobid": "j1114203012775104298s-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.0-bot:acemusic",
      "type": "stems",
      "status": "completed",
      "email": "example@example.com",
      "created": "2026-11-14T20:30:12.775Z",
      "stems": {
        "mode": "vocals",
        "songId": "user:1234-example@example.com-song:so_3f9c2a7d81e64b05a9d2c4e7",
        "tracks": [
          {
            "type": "vocal",
            "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
            "duration": 135.02
          },
          {
            "type": "instrumental",
            "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
            "duration": 135.02
          }
        ],
        "expires": "2026-11-15T20:35:59.230Z"
      },
      "completed": "2026-11-14T20:31:39.143Z",
      "job_state": "completed",
      "outputs": [
        {
          "ok": true,
          "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": "2026-11-15T20:35:59.256Z",
          "ref": null
        },
        {
          "ok": true,
          "url": "https://….r2.cloudflarestorage.com/acemusic-data-prod/users/…/stem/202611/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&…",
          "url_auth": "none",
          "mime": "audio/mpeg",
          "expires_at": "2026-11-15T20:35:59.256Z",
          "ref": null
        }
      ]
    }
    

    A job that is still running or that failed answers 200 too: check status, and for a failed job code and error.

  • 400 Bad Request

    {
      "error": "Path parameter jobid (not-a-job) is not a valid ACE Music job id",
      "code": 400
    }
    
  • 401 Unauthorized

    Invalid API token.

    {
      "error": "useapi.net ⁝ Unauthorized",
      "code": 401
    }
    
  • 403 Forbidden

    The job belongs to another useapi.net user.

    {
      "error": "Not your job",
      "code": 403
    }
    
  • 404 Not Found

    ACE Music has none of the job’s songs any more (deleted and then emptied from the trash on acemusic.ai), or the job’s account was removed.

    {
      "error": "Job j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic not found: ACE Music has none of its songs",
      "code": 404
    }
    
    {
      "error": "Account example@example.com is not configured: the job cannot be read",
      "code": 404
    }
    
  • 410 Gone

    The job is older than 7 days. Its songs are still in the account’s Library: read them with GET /music.

    {
      "error": "Job has expired: jobs can be read for 7 days",
      "code": 410
    }
    
Model

The job record. POST /music and POST /music/stems return it too, and it is the body of the replyUrl webhook.

The job record, field by field, and the types it uses (Song, Output, ErrorInfo)
{ // TypeScript, all fields are optional
  jobid: string                  // the job's id, `j…-u<id>-email:<email>-task:…-bot:acemusic`. It names the account and
                                 // the song or songs the job is about. Read the job with GET /jobs/{jobid}
  type: 'music' | 'stems'        // music: POST /music. stems: POST /music/stems
  status: 'processing' | 'completed' | 'failed'   // processing: ACE Music is making the songs or the split (every job
                                 // starts here). completed: done, a song job once at least one of its two songs succeeded.
                                 // failed: done without a result, error says why and code is the HTTP status
  email: string                  // the ACE Music account the job runs on
  created: string                // ISO 8601
  completed?: string             // ISO 8601, when the job completed or failed
  model?: string                 // music: the model you asked for
  modelUsed?: string             // music: the model that made the songs. It differs from model when the request ran on
                                 // another one: a request that must read a song (a mashup, a cover asked on acemusic-v1, a
                                 // prompt with more than one reference on ace-step-1.5-xl) runs on acemusic-v1.1, and ACE
                                 // Music can also switch a request itself
  songs?: (Song | DeletedSong)[] // music: the request's two songs, see Song below. A song deleted since, with
                                 // DELETE /music/{songId} or on acemusic.ai, is a DeletedSong
  stems?: {                      // on a stems job: the split
    mode: 'vocals' | 'all'       // the split you asked for
    songId: string               // the song that was split
    songStatus?: 'deleted'       // the song was deleted, its stems went with it (the job failed with code 404)
    tracks: {                    // one per stem
      type: string               // vocals: vocal, instrumental. all: vocals, `backing_vocals`, drums, bass, guitar,
                                 // keyboard, strings, synth, woodwinds, fx (the stems ACE Music found)
      url: string | null         // signed mp3 link, valid 24 hours
      duration?: number          // seconds
    }[]
    expires?: string             // ISO 8601, when the track links stop working (read the job again for fresh ones)
  }
  error?: string                 // status 'failed': why
  code?: number                  // status failed: the HTTP status of the failure. 400: ACE Music could not read a
                                 // referenced song's melody (read its score with GET /music/score, then run it again). 404:
                                 // the account was removed, or a split's song was deleted. 422: ACE Music could not make
                                 // the songs or the split. 504: not finished within 30 minutes (ACE Music may still finish
                                 // it). 596: the account was signed out
  replyUrl?: string               // the replyUrl you sent: it receives this record when the job ends
  replyRef?: string               // the replyRef you sent, echoed back
  job_state: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' | 'unknown'
                                 // where the job is, in the same words for every useapi.net API
  outputs: Output[]              // one entry per file the job made, see Output below
  error_info?: ErrorInfo         // only on a failed job: why, and whether to retry, see ErrorInfo below
}

Song: each item of songs in the job record above.

{ // TypeScript, all fields are optional
  songId: string                 // user:<id>-<email>-song:so_…, the song's id: use it as a reference, to split, download or delete
  taskId: string                 // ACE Music's own id of the song (so_…)
  status: 'planning' | 'scoring' | 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted'
                                 // ACE Music's progress on the song
  title: string | null           // the song's title (ACE Music writes one for a prompt request)
  model: string | null           // acemusic-v1, acemusic-v1.1 or ace-step-1.5-xl. null for an uploaded file
  style: string | null           // the style the song was made with (ACE Music writes it for a prompt request)
  lyrics: string | null          // [verse] / [chorus] tagged
  instrumental: boolean | null   // true for a song with no vocals
  duration: number | null        // seconds
  audioUrl: string | null        // public mp3 link, https://acemusic.ai/data/<taskId>.mp3, once the song succeeded.
                                 // It never changes: store this one. null for an uploaded file: get its audio with
                                 // GET /music/download
  playUrl?: string | null        // a direct link to the song's audio for players, valid until playUrlExpires: about an
                                 // hour for a made song (the same mp3 as audioUrl), 24 hours for an upload (its own audio,
                                 // in the format it was uploaded in). Some browsers (Brave) block the redirect behind
                                 // audioUrl: store audioUrl, play playUrl. For about a minute after a song is made it is
                                 // audioUrl itself (ACE Music serves the file directly then). In job records,
                                 // GET /music/{songId} and an audio upload's POST /files answer, not in GET /music. null
                                 // while the song is not finished, or when the link could not be read
  playUrlExpires?: string | null // ISO 8601, when playUrl stops working: read the job or the song again for a fresh one
  coverUrl: string | null        // cover art (jpg)
  pageUrl: string | null         // the song's page on acemusic.ai, when ACE Music made one
  created: string | null         // ISO 8601
  finished: string | null        // ISO 8601
  kind: 'original' | 'cover' | 'mashup' | 'edit' | 'upload'   // how the song was made: original (a prompt or mode
                                 // generate), cover (mode cover, and mode remix too), mashup, edit, or upload (a file
                                 // sent with POST /files)
  score: boolean                 // true when ACE Music already has the song's score (GET /music/score)
  error?: {                      // a failed song
    code?: string                // ACE Music's code, e.g. `ref_no_melody`, `song_not_made`
    message?: string             // ACE Music's own words
    reason?: string              // ACE Music's reason, when it gives one
  }
  refunded?: boolean             // ACE Music gave the credits back for a failed song
  stems?: {                      // splits made with POST /music/stems. Their track links are signed (24 hours) on
                                 // GET /music/{songId}, null elsewhere
    vocals?: Split               // mode vocals: vocal and instrumental
    all?: Split                  // mode all: every stem ACE Music found
  }
  upload?: {                     // an uploaded audio file (POST /files)
    seconds?: number             // its length, counted against the account's upload minutes
    bpm?: number                 // the tempo ACE Music read
    transcription?: string       // done once ACE Music has read its lyrics, style and melody
  }
}

Split: each split in stems of a Song above (vocals, all).

{ // TypeScript
  status?: string                // ACE Music's progress on the split
  tracks: {                      // one per stem
    type?: string                // the stem, e.g. vocals, drums, bass
    url: string | null           // signed mp3 link (24 hours) on GET /music/{songId}, null elsewhere
    duration?: number            // seconds
  }[]
}

DeletedSong: an item of songs whose song was deleted since, with DELETE /music/{songId} or on acemusic.ai.

{ // TypeScript
  songId: string                 // the song's id, as it was
  taskId: string                 // ACE Music's own id of the song (so_…)
  status: 'deleted'              // deleted with DELETE /music/{songId} or on acemusic.ai
}

Output: each item of outputs in the job record above.

{ // TypeScript
  ok: boolean                    // true when this file is ready to use
  url: string | null             // the link to the file, always absolute
  url_auth: 'none' | 'bearer'    // none: open the link as it is. bearer: send your API token with it
  mime: string                   // the file type, e.g. audio/mpeg
  expires_at: string | null      // ISO 8601, when the link stops working. null when it does not expire
  ref: string | null             // the id to use for this file in later calls
  thumbnail_url?: string | null  // a cover or preview image
  text?: string                  // the text, when the output is text
}

ErrorInfo: the error_info of a failed job above.

{ // TypeScript
  code: string                   // the kind of failure, in the same words for every useapi.net API, e.g. `timeout`,
                                 // `generation_failed`, `input_rejected`, `not_found`, `account_unhealthy`
  message: string                // what went wrong, in the API's own words
  retry: {                       // whether and when to send it again
    mode: 'never' | 'now' | 'backoff' | 'after' | 'after_reset' | 'other_account'
                                 // never: do not send it again as it is (see action). now: send it again right
                                 // away. backoff: send it again later, waiting longer each time. after: send it again
                                 // once the wait in seconds has passed. after_reset: send it again once the account's credits or
                                 // usage limit reset. other_account: send it on another account
    seconds?: number             // mode after: wait this long (or the Retry-After header)
    max?: number                 // retry at most this many times
    action?: string              // what to change first, e.g. `fix_body`, `replace_input`, `add_credits`, `upgrade_plan`
  }
  vendor_code?: string           // the code the vendor answered with
}
status Meaning
processing ACE Music is making the songs or the split. Every job starts here.
completed Done. A song job is completed when at least one of its two songs succeeded. A song that failed carries its own error, and a song deleted since shows status: "deleted".
failed Done without a result. error says why and code is the HTTP status.
code Meaning
400 ACE Music could not read the melody of a referenced song (ref_no_melody), usually an ACE-Step song with no score yet. Read its score with GET /music/score, then run the request again. The songs show refunded: true: ACE Music gave the credits back.
404 The account was removed with DELETE /accounts/email while the job ran, or a stem split’s song was deleted (its stems went with it, stems.songStatus is deleted).
422 ACE Music could not make the songs or the split, and error has ACE Music’s reason. A failed song shows refunded: true when ACE Music gave its credits back.
504 The job did not finish within 30 minutes. ACE Music may still finish it and has likely charged for it: read the job again later (it shows completed once ACE Music finished it) or look for its songs with GET /music before you run it again.
596 The account was signed out while the job ran: ACE Music refused the stored password. ACE Music may still finish the job. Update the password with POST /accounts, then read the job again.

The replyUrl webhook is one POST with Content-Type: application/json and this record as the body, sent once when the job completes or fails (a 10-second timeout, no retries, redirects are not followed). Use replyRef to match the callback to your own records.

Examples
  • JOBID="j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic"
    curl -H "Authorization: Bearer …" \
         "https://api.useapi.net/v1/acemusic/jobs/$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$JOBID")"
    
  • const token = "API token";
    const jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic";
    const apiUrl = `https://api.useapi.net/v1/acemusic/jobs/${encodeURIComponent(jobid)}`;
    let job;
    do {
      await new Promise(resolve => setTimeout(resolve, 10000));
      const response = await fetch(apiUrl, { headers: { "Authorization": `Bearer ${token}` } });
      job = await response.json();
      console.log(job.status);
    } while (job.status === "processing");
    console.log("job", job);
    
  • import requests, time, urllib.parse
    
    token = "API token"
    jobid = "j1114201530412583907m-u1234-email:example@example.com-task:so_3f9c2a7d81e64b05a9d2c4e7.so_b6e14d0c9a7f4382be51f0a3-bot:acemusic"
    apiUrl = "https://api.useapi.net/v1/acemusic/jobs/" + urllib.parse.quote(jobid, safe="")
    headers = {"Authorization": f"Bearer {token}"}
    while True:
        time.sleep(10)
        job = requests.get(apiUrl, headers=headers).json()
        print(job.get("status"))
        if job.get("status") != "processing":
            break
    print(job)
    
Try It

The songs or stem tracks play above the JSON once the job is completed.