Skip to main content

Understanding Analysis Results

Learn how to interpret the JSON output from a completed analysis job, including successful results and error states.

The Result Object​

When you check the status of an analysis job, the API returns a result object. This object contains the current status of the job and, if completed, the output from the algorithms you requested.

Anatomy of the Response​

The response body is a JSON object with the following key fields:

  • job_id: The unique identifier for the analysis job.
  • status: The current state of the job. Can be CREATED, PENDING, SUCCESS, or ERROR.
  • results: A nested object containing the output of each requested model. This field is only present when the status is SUCCESS.
  • error: A string containing an error message. This field is only present when the status is ERROR.

Successful Response​

When your job is finished, the status will change to SUCCESS, and the results field will be populated.

Example Successful Response
{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "SUCCESS",
  "results": {
    "bpm_essentia": {
      "bpm": 128.20115661621094
    },
    "key_essentia": {
      "key": "C",
      "scale": "major",
      "strength": 0.85
    }
  },
  "error": null
}

Pending or Failed Response​

If the job is still running, the status will be PENDING. If something went wrong (e.g., the audio URL was invalid), the status will be ERROR and the error field will contain a descriptive message.

Example Error Response
{
  "job_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "status": "ERROR",
  "results": null,
  "error": "Failed to download or decode audio from the provided URL."
}

Inside the results Field​

The results object contains a key for each model you requested in your original analysis job. The value for each key is another object containing the specific output of that model.

Dynamic Output

The structure of the output within each model's object is unique to that model. Refer to the Algorithms Reference for details on what to expect from each one.

For example, key_essentia returns an object with key, scale, and strength, while loudness_ebur128 returns an object with loudness measurements.