> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whisul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Lifecycle

> Reference for all Whisul job status values (running, completed, failed), when each occurs, and every field available in the completed result object.

Every music generation job moves through a defined set of status values. Understanding the lifecycle lets you write polling logic that reacts correctly to each state and extracts the right fields when a job finishes. This page describes each status, specifies which fields are available at each stage, and provides a complete reference for the `result` object returned when generation completes.

## Status lifecycle

<Tabs>
  <Tab title="running">
    The job has been accepted and generation is in progress. The Whisul backend is actively processing your prompt.

    **What to expect:**

    * `status` is `"running"`
    * `result` is `null`
    * `error` is `null`
    * `finished_at` is not present
    * `started_at` is populated

    **What to do:** Continue polling `GET /jobs/{job_id}` at a reasonable interval until `status` changes. See the [polling guide](/guides/polling-jobs) for recommended intervals.

    ```json theme={null}
    {
      "status": "running",
      "prompt": "a trap song",
      "result": null,
      "error": null,
      "started_at": "2026-02-17 15:39:34"
    }
    ```
  </Tab>

  <Tab title="completed">
    Generation succeeded. The song, cover art, and metadata are ready.

    **What to expect:**

    * `status` is `"completed"`
    * `result` is a populated object containing the song URL, cover art URL, BPM, duration, title, and tags
    * `error` is `null`
    * Both `started_at` and `finished_at` are present

    **What to do:** Read the fields from the `result` object. Use `song_url` to access the audio file and `image_url` to access the cover artwork.

    ```json theme={null}
    {
      "status": "completed",
      "prompt": "a trap song",
      "result": {
        "title": "Midnight Grid",
        "bpm": 140,
        "duration": "2:47",
        "song_url": "https://cdn.whisul.com/audio/81fa5ff7.mp3",
        "image_url": "https://cdn.whisul.com/covers/81fa5ff7.jpg",
        "tags": "trap, dark, 808s, synth, bass"
      },
      "error": null,
      "started_at": "2026-02-17 15:39:34",
      "finished_at": "2026-02-17 15:41:58"
    }
    ```
  </Tab>

  <Tab title="failed">
    Generation did not complete successfully. The job terminated with an error.

    **What to expect:**

    * `status` is `"failed"`
    * `result` is `null`
    * `error` may contain a message describing what went wrong
    * Both `started_at` and `finished_at` are present

    **What to do:** Check the `error` field for details. You can submit a new job with `POST /compose`. If failures persist for the same prompt, try rephrasing it or contact [Whisul support](https://whisul.com).
  </Tab>
</Tabs>

## Timestamp fields

Both endpoints return timing information for the job.

| Field         | Type   | When present                 | Description                                                             |
| ------------- | ------ | ---------------------------- | ----------------------------------------------------------------------- |
| `started_at`  | string | Always                       | The time the job began processing. Format: `YYYY-MM-DD HH:MM:SS` (UTC). |
| `finished_at` | string | `completed` or `failed` only | The time the job finished. Not present while the job is `running`.      |

## Result object fields

The `result` object is only present when `status` is `"completed"`. For all other statuses, `result` is `null`.

| Field       | Type   | Description                                                                                                                                                |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`     | string | The AI-generated title for the song.                                                                                                                       |
| `bpm`       | number | The tempo of the generated track in beats per minute.                                                                                                      |
| `duration`  | string | The length of the song in `m:ss` format — for example, `"2:47"`.                                                                                           |
| `song_url`  | string | A URL to the generated audio file.                                                                                                                         |
| `image_url` | string | A URL to the AI-generated cover artwork for the song.                                                                                                      |
| `tags`      | string | A comma-separated string of descriptive tags characterizing the song's style, genre, and instrumentation — for example, `"trap, dark, 808s, synth, bass"`. |

<Note>
  `result` fields are only guaranteed to be populated when `status` is `"completed"`. Do not attempt to read `result` fields before confirming the status value.
</Note>