# Analysis results: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/analysis-results
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 2.

## GET /v1/audio/{audioId}/analyses

Operation id: `list_file_analyses`

**List the finished analyses of a file**

Returns the analyses that are finished for one of your files: for each, its `category` and the stored `summary`. Analyses that are still running or failed are not listed (the library list shows them as pending or failed). A file with no finished analysis answers an empty list. A file that is not yours, does not exist or is in the trash is 404 `not_found`. If the database is briefly unavailable the route answers 503 `db_unavailable`; retry after a short wait. Success is `{ data }` without `meta`.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or the file id of one of your files. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `audio_id` | string | Registry identifier of the file. |
| `analyses` | array<object> | The finished analyses. |
| `analyses[].category` | string | The kind of analysis, for example `rhythm` or `spectral`. |
| `analyses[].summary` | any | The stored result of that analysis. Its keys depend on the category. Left out when `include_summaries=false`. |

### Responses

200: The finished analyses of the file.

```json
{
  "data": {
    "audio_id": "audio_3f9c1a7d2b60",
    "analyses": [
      {
        "category": "rhythm",
        "summary": {
          "tempo": {
            "bpm": 119.8
          }
        }
      }
    ]
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

404: The file does not exist, is in the trash, or is not yours.

```json
{
  "error": {
    "code": "not_found",
    "message": "File not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/analyses" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## GET /v1/audio/{audioId}/midi

Operation id: `download_file_midi`

**Download the MIDI file of a melody analysis**

Returns the melody that the melody analysis found in one of your files as a standard MIDI file. The response body is the file itself (`Content-Type: audio/midi`) with a `Content-Disposition: attachment` header. Send `name` to choose the file name it is saved under; without it the name is the file id with `.mid`. A file with no melody analysis, an analysis without MIDI, or a file that is not yours is 404 `midi_not_found`. If the database is briefly unavailable the route answers 503 `db_unavailable`; retry after a short wait.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or the file id of one of your files. |
| `name` | query | string | no | File name to save the download under. The `.mid` extension is added when missing. |

### Responses

200: The MIDI file. The body is binary, not JSON.

```text
Binary file
Content-Type: audio/midi
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

404: The file has no melody analysis with a MIDI export, or it is not yours.

```json
{
  "error": {
    "code": "midi_not_found",
    "message": "MIDI file not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#midi_not_found"
  }
}
```

429: Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`midi_not_found`](https://www.scarleta.ai/docs/errors#midi_not_found), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/midi" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  --fail \
  -o output.mid
```