# audioAnalyze > Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json. `POST https://api.map.audio/v1/audio/analyze` Measure audio loudness and peaks (BS.1770). Measure audio this account holds, such as a render's master: loudness (BS.1770), true peak, spectrum, stereo image, tempo, key, sections and defects. Send file ids from a job's `result.outputs`; the measurements come back in `result.command`, under `files` when you send more than one. Run it on a render before you keep or deliver it, or to compare seeds. Free: it counts in GET /v1/usage, never in render-minutes. Answers 200 with the finished job when it ends within `Prefer: wait=N` (30 s unless sent, at most 60), else 202 with the job to poll. Auth: `Authorization: Bearer` with an API key or a map.audio access token. Send `Prefer: wait=N` (0 to 60) to receive the finished job when it ends within N seconds; otherwise the answer is `202` with the job. Send `Idempotency-Key` to retry safely: the same key and body return the same result for 24 hours. MCP tool: `audio_analyze`. ## Body | Field | Type | Required | Description | | --- | --- | --- | --- | | `files` | array of string | yes | Ids (file_…) of WAV or FLAC audio this account holds, at most 16. 1 to 16 items. | | `peaks` | boolean | no | Include the existing 48-bin RMS envelope. | | `pitch` | boolean | no | Estimate mono pitch and confidence. | | `class` | boolean | no | Classify the mono sample and report measured features. | | `spectrum` | boolean | no | Long-term third-octave spectrum of mid and side, and each band's energy share (sub, low, lowMid, mid, highMid, air), relative to the file's total energy from 20 Hz to 20 kHz. | | `stereo` | boolean | no | Side minus mid and L/R correlation per band, and the mono fold-down's loudness difference. | | `hpss` | boolean | no | Harmonic, percussive and residual energy shares from the Transient card's spectral split (HpssCore, FIRM). | | `sections` | boolean | no | Section boundaries from Foote novelty over third-octave features, with each section's loudness and true peak. | | `transients` | boolean | no | Transient times from the sampler's transient detector. | | `beats` | boolean | no | Tempo in BPM, its confidence and the first downbeat, from the DJ view's beat tracker; a tempo in the file name ("loop 92 BPM.wav") fixes the octave. | | `musicalKey` | boolean | no | Musical key ("A minor") with its Camelot code and confidence, from the DJ view's key estimate. | | `levels` | boolean | no | Level statistics: RMS, PLR (true peak minus integrated), PSR (3 s true peak minus short-term loudness, median and lowest), the loudest momentary and short-term loudness, block crest and level swing. | | `validity` | boolean | no | File defects: non-finite samples with the first frame and channel, subnormals, DC offset, clipped samples, where sound starts and ends, and the level of the last 100 ms. | | `timbre` | boolean | no | Timbre: spectral centroid, spread, skewness, kurtosis and 95% rolloff in Hz, flatness and crest in dB (median and 90th percentile over the frames within 60 dB of the loudest) across 20 Hz-20 kHz and per broad band, MFCCs 1-13 (mean and standard deviation) and each pitch class's share of the power (chroma, C first). | | `compare` | string | no | Compare with a reference file at the same rate, such as a render's input, lined up by `latency`: the null raw, after one best gain and after the best linear filter, the largest and RMS sample difference, the residual per broad band, gain and coherence per third octave, the envelope change per band, and MFCC and chroma distances. The id (file_…) of WAV or FLAC audio this account holds: a render output, or an upload once uploads open. Matches `^file_[0-9A-HJKMNP-TV-Z]{26}$`. | | `latency` | integer | no | Frames the file lags the `compare` reference by, such as a render's latencySamples. From -8388608 to 8388608. Default `0`. | | `thd` | number | no | A steady tone's distortion at this frequency in Hz, over the whole file: harmonics in dBc, THD, THD+N, the even harmonics' share and the worst spur. From 1 to 192000. | | `imd` | string | no | A steady twin tone's intermodulation, its two frequencies in Hz as 19000,20000: the difference tone and all products against the pair. | | `window` | number | no | Adds a per-window series of `spectrum`, `stereo` and `hpss` values, this many seconds a window, at most 256 windows. From 0.5 to 3600. | | `metadata` | map of string | no | Up to 20 string pairs stored with the job. At most 20 entries. | ## Example ```sh curl -sS "https://api.map.audio/v1/audio/analyze" \ -H "Authorization: Bearer $MAP_API_KEY" \ -H "Map-Version: 2026-11-01" \ -H "Prefer: wait=30" \ -H "Content-Type: application/json" \ -d '{"files":["file_01M6BPRK0M34NBP2XKJ1RMX1TQ"],"levels":true,"validity":true}' ``` ### Request: Check a render's loudness and look for defects ```json { "files": [ "file_01M6BPRK0M34NBP2XKJ1RMX1TQ" ], "levels": true, "validity": true } ``` ### 200: Finished ```json { "object": "job", "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1", "operation": "audioAnalyze", "status": "succeeded", "livemode": false, "sequence": 3, "progress": 1, "queuePosition": null, "createdAt": "2026-11-01T14:03:31.512Z", "startedAt": "2026-11-01T14:03:33.104Z", "finishedAt": "2026-11-01T14:03:41.877Z", "estimate": { "audioSeconds": 0, "renderMinutes": 0 }, "result": { "outputs": [], "seed": null, "command": { "ok": true, "path": "file_01M6BPRK0M34NBP2XKJ1RMX1TQ", "format": "wav", "sampleRate": 48000, "channels": 2, "durationSeconds": 16, "integratedLufs": -9.6, "loudnessRange": 3.8, "truePeakDb": -0.7, "samplePeakDb": -1.1, "levels": { "rmsDbfs": -11.4, "plrDb": 8.9, "psrDb": 7.6, "minPsrDb": 5.2, "maxMomentaryLufs": -6.9, "maxShortTermLufs": -8.3, "crestDb": 10.3, "swingDb": 6.1 }, "validity": { "nonFinite": { "count": 0, "firstFrame": null, "firstChannel": null, "firstSeconds": null }, "subnormals": 0, "dc": [ 0.0001, -0.0001 ], "dcDbfs": -80, "clipping": { "threshold": 0.99997, "samples": 0, "firstSeconds": null }, "firstAudibleSeconds": 0, "lastAudibleSeconds": 15.98, "tailRmsDbfs": -31.2 } }, "provenance": null }, "error": null, "usage": { "renderMinutes": 0, "audioSeconds": 0, "computeMs": 184 }, "metadata": {}, "urls": { "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1", "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events", "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel" } } ``` ### 202: Still running ```json { "object": "job", "id": "job_01M6BPRFPCH9EBPY7B6JKM7CE1", "operation": "audioAnalyze", "status": "running", "livemode": false, "sequence": 2, "progress": 0, "queuePosition": null, "createdAt": "2026-11-01T14:03:31.512Z", "startedAt": "2026-11-01T14:03:33.104Z", "finishedAt": null, "estimate": { "audioSeconds": 0, "renderMinutes": 0 }, "result": null, "error": null, "usage": null, "metadata": {}, "urls": { "self": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1", "events": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/events", "cancel": "https://api.map.audio/v1/jobs/job_01M6BPRFPCH9EBPY7B6JKM7CE1/cancel" } } ``` ### 404: Not found ```json { "error": { "type": "not_found", "code": "not_found", "message": "No file with that id; GET /v1/files lists this account's files.", "param": "files[0]", "retryable": false, "jobId": null, "docUrl": "https://map.audio/developers/music-api/errors#not_found", "requestId": "9a3f7c2e5b1d8f40-LHR" } } ``` ## Responses - `200`: The finished job: `result.outputs` link each file it wrote and `result.command` is the engine's own result. - `202`: The job, still running when `Prefer: wait` ran out; poll `urls.self`. - `404`: Not found - `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue. ## Errors - [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request) - [`unsupported_media_type`](https://map.audio/developers/music-api/errors#unsupported_media_type) - [`payload_too_large`](https://map.audio/developers/music-api/errors#payload_too_large) - [`terms_required`](https://map.audio/developers/music-api/errors#terms_required) - [`concurrency_limit`](https://map.audio/developers/music-api/errors#concurrency_limit) - [`idempotency_key_reused`](https://map.audio/developers/music-api/errors#idempotency_key_reused) - [`idempotency_in_flight`](https://map.audio/developers/music-api/errors#idempotency_in_flight) - [`queue_unavailable`](https://map.audio/developers/music-api/errors#queue_unavailable) - [`not_found`](https://map.audio/developers/music-api/errors#not_found) - [`file_not_ready`](https://map.audio/developers/music-api/errors#file_not_ready) - [`file_expired`](https://map.audio/developers/music-api/errors#file_expired) - [`uploads_disabled`](https://map.audio/developers/music-api/errors#uploads_disabled)