API reference

Analysis

4 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

POST/v1/analyze

Submit an analysis

Free and paid accountsUses tokens

API key required
Free and paid accounts
Uses tokens

Starts a full analysis of one audio file and returns 202 at once with a job_id. Poll GET /v1/analyze/{job_id} until status is final; the analysis itself normally takes seconds to a minute.

audio_url must be a public http or https URL, or the URL of a file in your own library. Files longer than 60 minutes are refused with 400 audio_too_long. Unreadable or unsupported files are refused with 400 unsupported_format or audio_processing_failed; a file that cannot be downloaded from the URL is refused with 404 audio_not_found. Your balance is checked before the job starts; if it cannot cover the file the call returns 402 insufficient_balance and nothing is charged. Supply features to name the measurements you care about; leave it out to get the standard set.

Cost. Charged when the analysis finishes: tokens per second of audio, at the rate for a full analysis. The submit response reports the amount in `expected_tokens`. A file longer than the maximum, or a balance too low to cover the file, is refused before anything starts.

curl -X POST "https://api.scarleta.ai/v1/analyze" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/track-1.wav"
  }'

Request body

Name	Type	Required	Description
audio_urlbody	string	Required	Where to fetch the audio, at most 4096 characters. Must be public `http` or `https`, or a file in your own library. Allowed: 1 to 4096 characters.
featuresbody	array<string>	Optional	Dotted feature ids to request, for example `spectral.centroid`. Ids that are not recognised are ignored and the standard set is used.

Response fields

Field	Type	Description
job_id	string	Identifier to poll, cancel and read logs with.
status	"IN_QUEUE" \| "IN_PROGRESS" \| "COMPLETED" \| "FAILED" \| "CANCELLED" \| "TIMEOUT"	`IN_QUEUE` when accepted.
message	string
tenant_id	string \| null	Your account identifier. Absent for free accounts.
audio_url	string	The file being analyzed, with any credentials stripped from the URL.
workflow	"direct-api"
created_at	string	ISO 8601 timestamp.
response_time_ms	integer	How long accepting the job took, in milliseconds. Allowed: -9007199254740991 to 9007199254740991.
expected_duration	number	Length of the audio in seconds.
expected_tokens	integer	Tokens this analysis will cost when it finishes. Allowed: -9007199254740991 to 9007199254740991.
cache_hit	boolean	True when the file had been read before and was reused.

Errors

Status	Code	Description
400	missing_audio_url	Invalid JSON, a missing `audio_url`, an unacceptable URL, or a file that cannot be read as audio (`error.details.supported_formats` lists the accepted formats).
401	invalid_key	Missing, malformed, unknown or revoked API key.
402	insufficient_balance	The balance cannot cover this file. `error.details.required_tokens` says how much is needed.
403	media_not_owned	`audio_url` points at a library file owned by another account.
404	audio_not_found	The file at `audio_url` could not be downloaded.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
500	analysis_service_error	The analysis could not be started. Nothing was charged; retry.
503	persistence_failed	The job could not be recorded. Nothing was charged; retry.

Example responses

{
  "data": {
    "job_id": "analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44",
    "status": "IN_QUEUE",
    "message": "Analysis job submitted. Use GET /v1/analyze/{job_id} to retrieve results.",
    "tenant_id": "8c1d0b52-3f6a-4e0d-9d7b-2a41c5e90f13",
    "audio_url": "https://example.com/track-1.wav",
    "workflow": "direct-api",
    "created_at": "2026-10-21T03:41:37.272Z",
    "response_time_ms": 610,
    "expected_duration": 5.2,
    "expected_tokens": 26,
    "cache_hit": false
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

202 Accepted. The job is queued. Carries an `X-Job-ID` header with the same `job_id`,.
400 Invalid JSON, a missing `audio_url`, an unacceptable URL, or a file that cannot be read as audio (`error.details.supported_formats` lists the accepted formats).
401 Missing, malformed, unknown or revoked API key.
402 The balance cannot cover this file. `error.details.required_tokens` says how much is needed.
403 `audio_url` points at a library file owned by another account.
404 The file at `audio_url` could not be downloaded.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
500 The analysis could not be started. Nothing was charged; retry.
503 The job could not be recorded. Nothing was charged; retry.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: analysis_failed, audio_processing_failed, audio_too_long, auth_unavailable, configuration_error, invalid_audio_duration, invalid_audio_url, invalid_auth_format, invalid_json, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, service_unavailable, unauthorized, unsupported_format.

GET/v1/analyze/{job_id}

Get an analysis

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the state of one analysis job and, once status is COMPLETED, its results. Poll this route every few seconds until status is FAILED, CANCELLED or TIMEOUT, or COMPLETED with results present. You can only read your own jobs; any other job id returns 404 job_not_found. For a few seconds after status first reads COMPLETED, results can still be null: keep polling until it is an object. results is a JSON object whose keys depend on the analysis and can grow over time: read the keys you need and ignore the rest.

Cost. Free of charge.

JOB_ID="YOUR_JOB_ID"
curl "https://api.scarleta.ai/v1/analyze/$JOB_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
job_idpath	string	Required	The `job_id` returned when the analysis was submitted, for example `analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44`. Allowed: at least 1 character.

Response fields

Field	Type	Description
job_id	string
status	"IN_QUEUE" \| "IN_PROGRESS" \| "COMPLETED" \| "FAILED" \| "CANCELLED" \| "TIMEOUT"
workflow	string	How the job was started; `direct-api` for jobs created by `POST /v1/analyze`.
audio_url	string	The analyzed file. A library file comes back as a short-lived signed link.
features	array<string>	The feature ids you asked for; empty when you took the standard set.
results	object \| null	The measurements, or null until the job completes.
error	any	Why the job failed, or null.
created_at	string	ISO 8601 timestamp.
completed_at	string \| null	ISO 8601 timestamp, or null while the job runs.

Errors

Status	Code	Description
400	invalid_job_id	`job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	job_not_found	No job with this id exists for your account.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
500	retrieval_failed	The job could not be read. Retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "job_id": "analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44",
    "status": "COMPLETED",
    "workflow": "direct-api",
    "audio_url": "https://example.com/track-1.wav",
    "features": [],
    "results": {
      "success": true,
      "summary": {
        "duration_seconds": 5,
        "dominant_key": "A",
        "rms_energy": 0.856
      }
    },
    "error": null,
    "created_at": "2026-10-21T03:41:37.272Z",
    "completed_at": "2026-10-21T03:41:56.630Z"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 The job exists. `results` is null until `status` is `COMPLETED`.
400 `job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401 Missing, malformed, unknown or revoked API key.
404 No job with this id exists for your account.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
500 The job could not be read. Retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, missing_job_id, rate_limit_unavailable, unauthorized.

POST/v1/analyze/{job_id}/cancel

Cancel an analysis

Free and paid accounts

API key required
Free and paid accounts
No token cost

Stops an analysis that has not finished and marks it CANCELLED. The call is idempotent: a job that is already final is left alone and its current status is returned, so a second cancel is not an error. A job cancelled before it finishes is not charged.

Cost. Free of charge. A cancelled job is not charged.

JOB_ID="YOUR_JOB_ID"
curl -X POST "https://api.scarleta.ai/v1/analyze/$JOB_ID/cancel" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
job_idpath	string	Required	The `job_id` returned when the analysis was submitted, for example `analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44`. Allowed: at least 1 character.

Response fields

Field	Type	Description
job_id	string
status	"IN_QUEUE" \| "IN_PROGRESS" \| "COMPLETED" \| "FAILED" \| "CANCELLED" \| "TIMEOUT"	`CANCELLED` when this call stopped the job; otherwise the final state the job was already in.

Errors

Status	Code	Description
400	invalid_job_id	`job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	job_not_found	No job with this id exists for your account.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "job_id": "analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44",
    "status": "CANCELLED"
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401 Missing, malformed, unknown or revoked API key.
404 No job with this id exists for your account.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, missing_job_id, rate_limit_unavailable, unauthorized.

GET/v1/analyze/{job_id}/logs

Get the logs of an analysis

Free and paid accounts

API key required
Free and paid accounts
No token cost

Returns the execution log entries recorded for one of your jobs, oldest first, at most 200 entries. A job that has not started a step, or an analysis submitted with POST /v1/analyze, can have no entries: logs is then an empty array. Use the logs to diagnose a failed job.

Cost. Free of charge.

JOB_ID="YOUR_JOB_ID"
curl "https://api.scarleta.ai/v1/analyze/$JOB_ID/logs" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Parameters

Name	Type	Required	Description
job_idpath	string	Required	The `job_id` returned when the analysis was submitted, for example `analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44`. Allowed: at least 1 character.

Response fields

Field	Type	Description
job_id	string
status	"IN_QUEUE" \| "IN_PROGRESS" \| "COMPLETED" \| "FAILED" \| "CANCELLED" \| "TIMEOUT"
log_count	integer	Entries in `logs`. Allowed: -9007199254740991 to 9007199254740991.
logs	array<object>
logs[].job_id	string
logs[].tool_name	string \| null	Name of the step that produced the entry.
logs[].worker_id	string \| null	Opaque identifier of the machine that ran the step.
logs[].success	boolean \| null	Whether the step succeeded.
logs[].total_time_ms	number \| null	How long the step took, in milliseconds.
logs[].error_message	string \| null	Why the step failed, when it did.
logs[].stdout_tail	string \| null	The last lines the step printed.
logs[].created_at	string \| number \| null	When the entry was recorded.

Errors

Status	Code	Description
400	invalid_job_id	`job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	job_not_found	No job with this id exists for your account.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "job_id": "analysis_8f3c2a41-6d57-4b1e-9a02-5c7e1d0b9a44",
    "status": "COMPLETED",
    "log_count": 0,
    "logs": []
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}

200 Success
400 `job_id` has characters outside letters, digits and `_ . : -`, or is too long.
401 Missing, malformed, unknown or revoked API key.
404 No job with this id exists for your account.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, missing_job_id, rate_limit_unavailable, unauthorized.