AudioAtlas API
REST API for natural-language music search across the AudioAtlas index — 28 catalogues of production, commercial and independent repertoire. Send a brief in plain English ("uplifting indie folk for a road-trip montage") and get back ranked tracks with rich metadata: BPM, key, mood, genre, vocal info, ISRC, ISWC, similarity score, and direct preview URLs.
AudioAtlas is a public and free music search engine. We do not sell anything.
Overview
Base URL
https://audioatlas.com/v1
Content type — all requests and responses use application/json (UTF-8).
HTTPS only — plaintext requests are refused.
Access & pricing
API access is arranged directly with our team: tell us about your use case, the endpoints you need and your expected monthly volume, and we come back with credentials and a proposal — from evaluation keys to high-volume production access with dedicated support. Contact us or use the contact form on audioatlas.com.
Authentication
Every request must include your API key in the X-API-Key header.
Keys look like aa_ followed by 32 hex characters
(e.g. aa_8f1c…). The full secret is shown to you only once at
creation time — store it in a secret manager.
X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7
Bearer tokens also work as a fallback for clients that only support that
scheme: Authorization: Bearer aa_….
Generating a key
Keys are issued by your account administrator from the AudioAtlas admin console. When a key is created, the secret and a copy of this documentation are emailed to the owner address you provide.
Quotas & rate limits
Each key has an optional monthly request quota and an optional expiry date. The quota window resets on the first day of each calendar month at 00:00 UTC.
Every successful response includes the following headers so you can self-throttle:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your monthly quota (omitted if unlimited). |
X-RateLimit-Used | Requests counted in the current month, including this one. |
X-RateLimit-Remaining | Quota left until reset. |
X-RateLimit-Reset | ISO-8601 UTC timestamp of the next quota reset. |
When the quota is exhausted the server replies with HTTP 429 Too Many Requests
and a JSON body containing limit, used, and
resets_at so your client can wait or notify a human.
Errors
Errors return a JSON body of the form { "error": "code", "message": "human description" }
with one of the codes below.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | bad_request | Missing or invalid parameter (e.g. empty query, query > 512 chars). |
| 401 | missing_api_key | No X-API-Key header on the request. |
| 401 | invalid_api_key | The key doesn't exist. |
| 403 | key_disabled | The key has been revoked. |
| 403 | key_expired | The expiry date has passed. |
| 429 | quota_exceeded | Monthly quota exhausted. |
| 500 | internal_error | Unexpected server error — retry with exponential backoff. |
Use with Claude (MCP)
AudioAtlas is also an MCP server, so Claude Code, Claude Desktop and any other Model Context Protocol client can search the catalogue directly in a conversation with your API key. There is nothing to install.
Claude Code: run once in a terminal:
claude mcp add --transport http audioatlas https://audioatlas.com/mcp \
--header "Authorization: Bearer aa_your_key_here"
Add -s user to make it available in every project. Then ask Claude
things like "find instrumental tracks for a tense chase scene around 140 BPM",
"which song has the lyric ‘that’s that me espresso’?" or
"find 1980s synth-pop tracks with a female vocal".
Other clients (Claude Desktop, IDEs): add a remote / HTTP MCP server with
URL https://audioatlas.com/mcp and the header
Authorization: Bearer <your key>.
| Tool | Does | Same as |
|---|---|---|
search_music | Free-text brief or "artist + title" search | POST /v1/search |
lookup_tracks | Exact lookup by ISRC, ISWC, artist, title, composer | GET /v1/search/lookup |
get_track | One track by id, with fresh preview link | GET /v1/tracks/{id} |
find_similar_tracks | Tracks that sound like a track | GET /v1/tracks/{id}/similar |
similar_to_url | Tracks that sound like the audio at a URL | POST /v1/search/similar-by-url |
search_lyrics | Find a song from a lyric phrase | GET /v1/lyrics/search |
beat_grid | Beats, downbeats and BPM for video sync | GET /v1/tracks/{id}/beats |
identify_audio / get_identification | Identify a recording from an audio URL | /v1/identify |
catalog_stats | Catalogue size, daily additions, AI share | GET /v1/stats |
api_usage | Your key's usage and monthly limit | GET /v1/usage |
Each tool call counts as one request against your quota, exactly like
calling the endpoint yourself; connecting and listing tools are free. Your key's service
restrictions apply to the matching tools. An unknown, disabled or expired key is
rejected when the client connects (HTTP 401).
Health check
Lightweight liveness probe. No authentication required.
$ curl https://audioatlas.com/v1/health
{ "status": "ok" }
Usage
Returns the current month's usage and limit for the calling key.
Response
{
"name": "Acme Studio production",
"usage_total": 12480,
"usage_month": 2104,
"monthly_limit": 10000,
"expires_at": "2027-01-01T00:00:00+00:00",
"month_resets_at": "2026-05-01T00:00:00Z"
}
curl https://audioatlas.com/v1/usage \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/usage",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
timeout=10,
)
r.raise_for_status()
print(r.json())const r = await fetch("https://audioatlas.com/v1/usage", {
headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" }
});
console.log(await r.json());Fresh content
Curated “fresh content” — recently-notable tracks for a slice (e.g. new soundtracks), served from the catalogue. Pre-built and cached (rebuilt daily), so it is a cheap call. Service scope: metadata.
Query parameters
slice — content slice; currently soundtracks (default). An unknown slice returns an empty list.
Response
{
"slice": "soundtracks",
"items": [
{
"id": 126806646,
"song_id": "1440906939",
"catalog": "apple",
"title": "Can't Catch Me Now",
"artist": "Olivia Rodrigo",
"artwork_url": "https://.../300x300bb.jpg",
"preview_url": "https://.../preview.m4a",
"release_date": "2023-11-05",
"apple_music_url": "https://music.apple.com/..."
}
]
}
curl "https://audioatlas.com/v1/fresh?slice=soundtracks" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/fresh",
params={"slice": "soundtracks"},
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
timeout=10,
)
r.raise_for_status()
print(r.json()["items"])const r = await fetch("https://audioatlas.com/v1/fresh?slice=soundtracks", {
headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" }
});
console.log((await r.json()).items);Catalogue metrics
Daily metrics on the AudioAtlas index: total tracks, tracks added per day, and the share of AI-generated music flagged by the MatchTune AI Detector (per day and catalogue-wide). Computed once a day, early morning UTC; the latest entry is the last complete UTC day. Service scope: metadata.
Query parameters
days — length of the daily series, 1–90 (default 30).
Response
{
"computed_at": "2026-10-07T04:10:12+00:00",
"date": "2026-10-06",
"tracks": { "total": 155701494, "added": 86946 },
"ai": {
"detector": "MatchTune AI Detector",
"added": 27571,
"scanned": 79542,
"share_pct": 34.66,
"catalog": {
"ai": 6813827,
"scanned": 55820952,
"share_pct": 12.21,
"scope": "Apple Music releases dated 2023 or later"
},
"note": "Shares are computed over scanned tracks ..."
},
"daily": {
"timezone": "UTC",
"days": [
{ "date": "2026-10-05", "added": 45741, "ai": 18914, "ai_scanned": 44169, "ai_share_pct": 42.82 },
{ "date": "2026-10-06", "added": 86946, "ai": 27571, "ai_scanned": 79542, "ai_share_pct": 34.66 }
]
}
}
| Field | Description |
|---|---|
date | The latest complete UTC day in the series; tracks.added and the ai day figures refer to it. |
tracks.total | Tracks in the index, all catalogues, at computed_at. |
tracks.added | Tracks added to the index on date. |
ai.added / ai.scanned / ai.share_pct | Of that day’s additions: tracks flagged as AI-generated, tracks scanned (releases dated 2023 or later), and the AI share in percent. |
ai.catalog | Catalogue-wide AI count and share over every scanned track in scope. |
daily.days[] | Per UTC day, oldest first: added (all catalogues), ai, ai_scanned, ai_share_pct. |
AI figures are a lower bound: the detector recognises known generators only. AI fields are null for a day whose tracks had not all been analysed yet; they fill in on a later run.
curl "https://audioatlas.com/v1/stats?days=7" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/stats",
params={"days": 7},
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
timeout=10,
)
r.raise_for_status()
s = r.json()
print(s["date"], s["tracks"]["added"], s["ai"]["share_pct"])const r = await fetch("https://audioatlas.com/v1/stats?days=7", {
headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" }
});
const s = await r.json();
console.log(s.date, s.tracks.added, s.ai.share_pct);Search
The flagship endpoint. Send a free-text brief and get ranked tracks back.
Request body
| Field | Type | Description |
|---|---|---|
query * | string | Free-text brief, up to 512 chars. The model parses tempo, mood, genre, vocal type, and other constraints from natural English. May also include keyword operators (see Query syntax). |
limit | integer | Number of results, default 10, max 50. |
provider | string | "musical" (default, audio-similarity flavor — best for "sounds like" queries) or "semantic" (text-meaning flavor — best for descriptive briefs like "sad cinematic piano"). |
filters | object | Hard filters that override the parser's guesses — see below. |
catalog_ids | integer[] | Restrict the search to specific catalogs. Omit for all available catalogs. |
intent | object | Optional override of the model's intent inference — used to skip the disambiguation popup. Shape: {type, …} where type is one of soundtrack, song_title, artist, composer, sonic, any. See examples below. |
lang | string | Two-letter locale ("en", "fr", "es", "it", "de") — controls the language of the disambiguation popup labels. Defaults to "en". Other response fields are locale-independent. |
Query syntax
The query field accepts three input styles. You can mix and match.
1. Natural language
Describe the sound — mood, instruments, energy, tempo, genre, use case. The model parses structured filters out of the brief and runs a semantic match against the catalog.
"epic cinematic orchestral 120 BPM"
"melancholic piano with female vocals under 90 BPM"
"uplifting indie folk for a road-trip montage"
2. Named entities
If the brief references a specific artist, composer, song title, ISRC, or ISWC, the search runs a direct metadata lookup before falling back to semantic match.
"songs by Hans Zimmer" // artist
"music composed by John Williams" // composer
"Bohemian Rhapsody" // song title
"USRC17607839" // ISRC
3. Keyword operators (power-user)
Prefix a field name with field:value to force a strict structured match. Combine multiple operators with whitespace (they are AND'd). A value runs from after the colon to the next operator, so multi-word values need no quotes (quotes are still accepted).
| Operator | Behavior |
|---|---|
title: | Substring ILIKE on the track title. |
artist: | Substring ILIKE on artist credit. |
composer: | Substring ILIKE on composer (Apple/BMG real column; falls back to artist on catalogs that don't carry composer metadata). |
album: | Substring ILIKE on album. Useful for soundtracks where the film name lives in the album field. |
isrc: | Exact ISRC match. Index-aware. |
iswc: | Exact ISWC match. |
ipi: | Every work of a writer, by IPI number (all name variants of that IPI). |
publisher: | Works published or administered by a music publisher (name or IPI). |
label: | Record label, exact match (case-insensitive). |
genre: | Genre tag, exact match (primary or secondary tag). |
mood: | Mood tag, exact match (primary or secondary tag). |
bpm: | Tempo: a value (bpm:120) or a range (bpm:120-130, bpm:>140). |
year: | Release year or range (year:1990-1999). |
film: | The actual soundtrack of a film, show or game, or of a whole franchise (film:Interstellar, film:James Bond). |
country: | Artists from a country: ISO code or name (country:FR, country:Japan). |
lyrics: | A line of the lyrics, at least 2 words in order (lyrics:hello from the other side); tolerates small typos. |
covers: | Covers of a track: covers:<catalog_id>/<track_id>. |
Examples:
composer:Zimmer album:Gladiator // Hans Zimmer's Gladiator score
artist:bocelli // any Bocelli track
title:"Pearl Harbor" // titles literally matching Pearl Harbor
composer:"John Williams" album:Star // Star Wars / Star Trek scores by Williams
genre:cinematic mood:tense bpm:80-100 // tense cinematic cues, 80-100 BPM
artist:eddy gronfier title:afro electro // one exact song, no quotes needed
Without operators. A short query that is a song title plus its artist, in either order ("afro electro eddy gronfier"), is resolved as that exact song even when the artist is obscure; the response then carries "provider": "title_lookup". In metadata matches, a term with no word of at least 3 letters or digits (43, t3) is matched exactly rather than as a substring.
When keyword operators are present, the response carries "provider": "keyword_lookup" and parsed.keywords echoes back the parsed operators. The model parser and disambiguation popup are skipped entirely.
Disambiguation popup
API behaviour: when one of the options is a song-title lookup (e.g. "lizzo good as hell"), POST /v1/search resolves it automatically instead of asking: the response carries the results plus resolved_intent (the option applied) and alternatives (the other readings). Pass intent yourself to force another reading. Record labels for the top results are resolved inline when available (same-recording rows, then Spotify); the rest arrive within seconds and are flagged in processing.
Short, ambiguous queries — typically a single proper noun like "pearl harbor", "inception", "moonlight" — can mean several things (find the soundtrack, find a literal title, run a sonic vibe search). When the model can't pick a winner, the response returns needs_clarification: true with 2–3 options instead of results:
{
"needs_clarification": true,
"query": "pearl harbor",
"message": "What are you looking for?",
"options": [
{
"id": "soundtrack",
"label": "Find tracks from the Pearl Harbor film soundtrack.",
"intent": {"type": "soundtrack", "film_title": "Pearl Harbor", "composer": "Hans Zimmer"}
},
{
"id": "song-title",
"label": "Find a song with the exact title 'Pearl Harbor'.",
"intent": {"type": "song_title", "song_title": "Pearl Harbor"}
},
{
"id": "sonic",
"label": "Find epic cinematic war-film music.",
"intent": {"type": "sonic", "description": "epic orchestral war film cinematic with dramatic brass"}
}
]
}
To resolve: re-send the same query with the chosen option's intent object in the request body. The backend then runs the targeted search:
curl -X POST https://audioatlas.com/v1/search \
-H "X-API-Key: aa_..." -H "Content-Type: application/json" \
-d '{
"query": "pearl harbor",
"intent": {"type": "soundtrack", "film_title": "Pearl Harbor", "composer": "Hans Zimmer"}
}'
A fourth synthetic option, intent.type = "any", tells the backend to run the full default pipeline without re-asking. Use it to bypass the popup programmatically.
Intent types accepted in intent.type:
| Type | Honored fields | Search strategy |
|---|---|---|
soundtrack | film_title, composer | OR-match the film name against title + album, optionally narrowed by composer. Real soundtrack albums rank above covers. |
song_title | song_title | ILIKE on track title. |
composer | composer | ILIKE on composer (artist fallback on non-Apple catalogs). |
artist | artist_name | ILIKE on artist. |
sonic | description | Semantic match against the supplied description; skips literal-title fallback. |
any | — | Skip the popup; run the full default pipeline. |
Available filters
bpm_min / bpm_max | integer | Tempo window in BPM. |
vocal_types | string[] | Instrumental, Male Vocals, Female Vocals, Mixed Vocals, Choir, Vocal Samples, Spoken Word. |
energy_levels | string[] | Very Low, Low, Medium, High, Very High. |
genres / moods | string[] | Free strings — see the discovery page for the full vocabulary. |
year_min / year_max | integer | Release year range. |
min_duration / max_duration | integer | Track length in seconds. |
licensable_only | boolean | Restrict to catalogs marked licensable in your account. |
ai | string | "hide" removes AI music: tracks identified as AI by the MatchTune AI Detector plus the AI-generated catalogues (Suno, Udio); tracks not yet analysed are kept. "only" returns AI music exclusively and implies include_ai. Omit for no restriction. Each returned track then carries ai_generated (boolean). The filter is applied after ranking, so a page may hold fewer than limit results. |
Examples
curl -X POST https://audioatlas.com/v1/search \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{
"query": "uplifting indie folk for a road-trip montage, no lead vocals",
"limit": 10,
"filters": { "vocal_types": ["Instrumental"] }
}'import requests
r = requests.post(
"https://audioatlas.com/v1/search",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={
"query": "uplifting indie folk for a road-trip montage, no lead vocals",
"limit": 10,
"filters": {"vocal_types": ["Instrumental"]},
},
timeout=20,
)
r.raise_for_status()
for track in r.json()["results"]:
print(f"{track['search_score']:>3} {track['artist']} — {track['title']}")const r = await fetch("https://audioatlas.com/v1/search", {
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "uplifting indie folk for a road-trip montage, no lead vocals",
limit: 10,
filters: { vocal_types: ["Instrumental"] },
}),
});
const { results } = await r.json();
results.forEach(t => console.log(`${t.search_score} ${t.artist} — ${t.title}`));Response
The provider field echoes which strategy actually answered the call:
"semantic"/"musical"— the corresponding similarity search ran."metadata_lookup"— the brief named an artist / composer / song / ISRC, or anintentoverride was supplied."title_lookup"— short proper-noun query fell back to literal title match."keyword_lookup"— keyword operators (title:,composer:, …) were detected.
{
"total": 10,
"query": "uplifting indie folk for a road-trip montage, no lead vocals",
"provider": "semantic",
"parsed": {
"description": "uplifting indie folk, acoustic guitar driven, no lead vocals",
"filters": { "vocal_types": ["Instrumental"] }
},
"relaxed_filters": false,
"timings_ms": { "parse_ms": 0, "embed_ms": 33, "search_ms": 87 },
"results": [
{
"id": 1234567890,
"title": "Wonders",
"artist": "Atlas Trail",
"album": "Open Road",
"duration_seconds": 187.3,
"bpm": 128,
"music_key": "G major",
"ai_genre": "Indie Folk",
"ai_genre_secondary": "Folk Rock",
"ai_mood": "Uplifting",
"ai_mood_secondary": "Hopeful",
"ai_energy_level": "Medium",
"ai_energy_score": 0.62,
"ai_tempo_feel": "Steady Mid-tempo",
"ai_tags": ["acoustic guitar", "soft drums", "warm"],
"ai_use_cases": ["Travel Vlog", "Lifestyle Brand"],
"ai_description": "Mid-tempo indie folk with warm acoustic textures and a hopeful tone.",
"ai_similar_artists": ["Mumford & Sons", "The Lumineers", "Of Monsters and Men"],
"ai_mix_tips": "Tighten low-mids around 200 Hz to keep the vocal upfront against the acoustic guitar.",
"has_vocals": true,
"vocal_gender": null,
"artwork_url": "https://...",
"preview_url": "https://...",
"isrc": "USXY12345678",
"iswc": "T-345.246.800-1",
"record_label": "Atlas Records",
"record_labels": ["Atlas Records", "Atlas Compilations"],
"parent_label": "Apple Music",
"apple_music_url": "https://music.apple.com/...",
"spotify_url": "https://open.spotify.com/...",
"artist_popularity": {
"artist_name": "Adele",
"listeners": 5686879,
"playcount": 322763309,
"lastfm_url": "https://www.last.fm/music/Adele",
"fetched_at": "2026-06-23T10:14:22+00:00"
},
"mri_status": "completed",
"search_score": 84,
"catalog_id": 6
}
]
}
Track object
Selected fields you'll find in each results[] entry. Field set is stable but additive — new metadata fields may appear over time, so be tolerant of unknown keys.
id | integer | AudioAtlas internal ID. Stable per catalog. |
catalog_id | integer | Which catalog this track came from. |
title / artist / album | string | Display metadata. |
isrc / iswc / composer | string | Industry identifiers, when known. |
preview_url | string (URL) | ~30 s audio preview. |
duration_seconds | number | Full track length. |
bpm / music_key | number / string | Tempo and detected key (Camelot or scientific). |
ai_genre / ai_genre_secondary | string | Primary and secondary AI-tagged genre. |
ai_mood / ai_mood_secondary | string | Primary and secondary mood descriptor. |
ai_energy_level / ai_energy_score | string / number | Energy bucket ("Low" / "Medium" / "High") plus a 0–1 score. |
ai_tempo_feel | string | Subjective tempo descriptor (e.g. "Steady Mid-tempo"). |
ai_tags | string[] | Free-form audio tags (e.g. instruments, textures, production cues). |
ai_use_cases | string[] | Suggested sync / placement contexts (e.g. "Coffee Commercial"). |
ai_description | string | Short natural-language summary. |
ai_similar_artists | string[] | 3–5 reference artists with a similar sonic profile (LLM-generated, lazy on first read). |
ai_mix_tips | string | One-line production / mix note (LLM-generated, lazy on first read). |
vocal_gender | string | "male" / "female" / null for instrumental. |
has_vocals | boolean | Whether the track contains a vocal performance. |
artwork_url | string (URL) | Album / track artwork thumbnail when available. |
record_label | string | Track-level label (rights holder). When missing on the row it is resolved from other releases of the same recording in our catalogue, then Spotify, then Deezer (needs an ISRC). For the top results of a request this happens inline (up to ~2.5 s), so the label is usually present in the first response; for the rest it arrives within seconds and processing lists "record_label" until it does. Provider answers are sanity-checked: when Spotify or Deezer return a track for the ISRC whose artist and title share nothing with ours (mistyped or reused ISRCs happen), that label is discarded rather than attached to the wrong recording. |
record_labels | string[] | Every label under which this recording (same ISRC) appears in our catalogue: ["Warner Music Group - X5 Music Group", "Atlantic"]. record_labels[0] always equals record_label; the others follow by number of releases. A recording re-released on a compilation or by a catalogue owner legitimately carries several labels — use the list for rights research, record_label for one answer. Same field and shape as in POST /v1/lookup/isrc. Absent when no sibling release carries a label. Scope: the list covers releases sharing this row's ISRC only. Other rows in the same response may be different recordings of the work (re-recordings, compilations with their own ISRC) and can disagree with it, so a single-element list is not a consensus across the whole result set, and two same-company variants ("Warner Records" / "Warner Bros. Records") are not a disagreement. Result order does not indicate the original issue. |
beat_grid | object | Beat grid for audio↔video sync, on production-catalogue tracks that have been beat-analysed: { bpm, beat_offset_ms, downbeat_offset_ms, beats_per_bar, confidence, analysed_seconds, reference }. Offsets are milliseconds from the start of the delivered file (reference: "track_start"); the next beats follow at 60000 / bpm ms, the next bars at beats_per_bar beats. confidence (0–1) is the beat-interval regularity — low values mean rubato or tempo changes, use the full grid then. Absent on tracks without a grid yet. Apple tracks: grids are measured on the preview clip (reference: "preview_start") — Apple previews do not start on a beat — and are stored as tracks get analysed; GET /v1/tracks/{id}/beats computes one on demand when missing. Add ?beat_grid=full to GET /v1/fprint/lookup to also get beats_ms[] and downbeats_ms[], the complete grids for the analysed window. |
ai_verdict | string | On every search / lookup result: "ai" when the MatchTune AI Detector identified the track as AI-generated (or its catalogue is AI-generated), "human" when it was analysed and judged human-made or when the track was released before January 2023 (predates generative music at scale), null when not analysed yet. Present regardless of the ai filter. |
ai_verdict_score | number / null | On every search / lookup result: the MatchTune AI Detector's score behind ai_verdict: probability (0–1, 4 decimals) that the track is AI-generated. Low values back a "human" verdict, high values an "ai" one. Apple-catalogue tracks only; null when the track has not been analysed (including tracks judged "human" from their pre-2023 release date alone) and on other catalogues. |
publishers | object[] / null | Music publishers of the track's work (by ISWC): [{ "name", "ipi", "role" }], up to 8, sorted by name. role is "E" (original publisher) or, when the work has none on record, "AM" (administrator). [] = the work is known but no publisher is on record (often an unpublished work); null = no ISWC known for this track, so the work is unknown. Returned by /v1/search/lookup. |
vocal_type | string / null | "Instrumental", "female" / "male" (vocal performance with a known singer gender, same as vocal_gender), "Vocals" (vocals, gender unknown), or null when not analysed. |
isrcs | string[] | Every ISRC known for this recording; isrcs[0] equals isrc. |
song_id | string | Apple Music song id (Apple-catalogue tracks). |
similarity | string / number | Raw match score behind search_score (0–1). Prefer search_score for display. |
parent_label | string | Catalog publisher / parent label (e.g. "Apple Music", "Musicbed"). |
licensable / license_price_cents | boolean / integer | Direct-licensing status, when applicable to your account. |
apple_music_url / spotify_url / amazon_music_url / deezer_url / tidal_url / napster_url / pandora_url / yandex_url | string (URL) | Streaming-platform deep links. Resolved lazily via Odesli on first read for Apple-catalog tracks. |
artist_popularity | object | Last.fm popularity for the track's artist, when known: { artist_name, listeners, playcount, lastfm_url, fetched_at }. Omitted when the artist has no Last.fm presence. Cached per artist for the calendar month and refreshed on the 1st. Returned by GET /v1/tracks/{id}. |
mri_status | string | Audio-analysis state: "completed" means features (BPM / key / fingerprint / AI tags) are ready. "pending" / "failed" means a backfill is in flight or unavailable. |
search_score | integer (0–100) | Similarity score for this query. Higher is closer. (Search results only.) |
processing | string[] | Present only when a background backfill is in flight for this track. Lists the field names being filled (e.g. ["mri","iswc","record_label","ai_similar_artists","ai_mix_tips"]). Re-poll /v1/search/lookup or GET /v1/tracks/{id} a few seconds later to pick up the filled values. |
resolved_from_title / title_resolution | string / string | Present when your artist + title had no match of its own and the result is the original work: unofficial remixes, edits, extended mixes, remasters and other versions, bracketed or not (e.g. "Pop Style (Jack Daily Remix)" or "Voulez-Vous Extended Mix" → the original) carry no ISRC or label of their own, and the rights holders are those of the original. resolved_from_title echoes the title you sent; title_resolution is "original_work". Absent on direct matches. |
Lazy enrichment. The first read of a track that lacks audio features
or LLM-generated fields silently kicks off a background backfill (MRI, ISRC/ISWC
lookup, Spotify record_label, LLM ai_similar_artists +
ai_mix_tips, streaming links). This applies to GET /v1/tracks/{id}
and to /v1/search/lookup — both endpoints inspect each result and
trigger any missing backfills. The list of fields currently being filled is returned
in a per-track processing[] field; the response also carries a top-level
"processing": true|false so a UI can decide whether to schedule a re-poll.
Re-poll a few seconds later and the new fields will be present. Treat any field as
nullable on first encounter — never block UI rendering on a single missing field.
Track by id
Re-resolve a single Apple track by its AudioAtlas track_id — a
fresh preview_url plus artwork_url,
apple_music_url, bpm, key,
energy, duration_seconds and isrc.
Handy for durable "saved track" lists: a track_id is an
AudioAtlas internal id, so this is how you refresh a stored track's
preview link. 404 if the id is unknown.
curl https://audioatlas.com/v1/tracks/97212939 \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"
Lookup by metadata
Beat grid
Beat grid of an Apple track's preview clip, for cutting video on the beat. Returns { "track_id", "beat_grid": { bpm, beat_offset_ms, downbeat_offset_ms, beats_per_bar, confidence, analysed_seconds, reference, beats_ms[], downbeats_ms[] } }, or "beat_grid": null when no preview is available. Offsets are milliseconds from the start of the preview clip, which is what an app playing that preview needs; Apple previews are cut at arbitrary points, not on a beat. By default a missing grid is computed on demand from the preview (about one to two seconds); pass compute=0 to only read a stored grid. Production-catalogue tracks carry their grid in beat_grid on every result instead (see the field table), with offsets from the start of the delivered file.
Direct metadata match — useful when you have a known artist, title, ISRC, ISWC, or composer and want the canonical AudioAtlas record (or the best string match). Skips the LLM brief-parser and the vector pipeline entirely.
For each result, any missing metadata (audio features, ISRC/ISWC, record_label,
LLM fields, streaming links) is silently scheduled for backfill. A per-track
processing[] field lists which fields are being filled, and the response
carries a top-level boolean processing so the client knows to re-poll.
Exception: record_label for the first three results is resolved before
the response is returned (same-recording rows, then Spotify), so it is normally present immediately.
Query parameters (provide at least one of artist / title / isrc / iswc / composer / publisher):
artist | string | Artist name (case-insensitive substring). |
title | string | Track title. |
isrc | string | Exact ISRC. |
iswc | string | Exact ISWC. |
composer | string | Composer credit. |
publisher | string | Publisher name or IPI: returns tracks of the works that publisher holds. |
catalog_ids | string | Comma-separated catalog IDs to filter (e.g. 6,4). |
limit | integer | Number of results, default 20, max 50. |
Response. Every result carries the same set of keys; a value that is unknown or does not apply is null (never a missing key). Field meanings are in the Track object table.
{
"results": [
{
"id": 163792898,
"catalog_id": 6,
"song_id": "6806333350",
"title": "OMANH'O",
"artist": "Nash",
"album": "OMANH'O - Single",
"composer": "NATACHA FLORA SONLOUE",
"isrc": "QT6HV2669681",
"isrcs": ["QT6HV2669681"],
"iswc": "T3369066188",
"publishers": [],
"record_label": "Nash Noushi Production (2N Prod)",
"duration_seconds": 176.6,
"bpm": 143.55,
"music_key": "F# minor",
"has_vocals": true,
"vocal_gender": "female",
"vocal_type": "female",
"ai_genre": "afrobeats",
"ai_genre_secondary": "hip hop",
"ai_mood": "energetic",
"ai_mood_secondary": "sad",
"ai_energy_level": "High",
"ai_energy_score": 0.7,
"ai_tempo_feel": "Uptempo Dance",
"ai_tags": ["brass section", "accordion", "808 drums", "minimal", "punchy", "polished"],
"ai_use_cases": ["Party", "Wedding", "Workout", "Action Scene"],
"ai_description": "Minimal afrobeats track with an energetic mood, uptempo dance feel, and high energy.",
"ai_verdict": "human",
"ai_verdict_score": 0.0158,
"artwork_url": "https://is1-ssl.mzstatic.com/...",
"preview_url": "https://audio-ssl.itunes.apple.com/...",
"licensable": false,
"license_price_cents": null,
"mri_status": "completed",
"similarity": "1.0",
"search_score": 100
}
],
"total": 1,
"query": "Nash — OMANH'O",
"lookup": { "artist": "Nash", "title": "OMANH'O", "isrc": null, "iswc": null, "composer": null, "publisher": null },
"provider": "metadata_lookup",
"processing": false,
"timings_ms": { "search_ms": 281 }
}
When nothing in the catalogue matches an isrc query, the track is looked up on Spotify and returned with "catalog_id": null, "source": "spotify" and "provider": "spotify"; that fallback row carries Spotify's metadata only.
curl "https://audioatlas.com/v1/search/lookup?artist=Coldplay&limit=5" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/search/lookup",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
params={"isrc": "GBAYE0601498"},
timeout=15,
)
print(r.json()["results"][0])const r = await fetch(
"https://audioatlas.com/v1/search/lookup?title=Yesterday&artist=Beatles",
{ headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" } },
);
console.log((await r.json()).results);Search by lyrics
Find a song from a line of its lyrics. The phrase is matched with its words in order, ignoring case, accents and hyphens. Results are ordered by popularity, one row per song (title + artist). The lyric text itself is never returned.
Query parameters
q * | string | A phrase from the song: at least 2 words, at most 300 characters. |
limit | integer | Default 20, max 50. |
Response
{
"query": "that's that me espresso",
"count": 1,
"tracks": [
{ "track_id": 182736455, "title": "Espresso", "artist": "Sabrina Carpenter",
"album": "Espresso - Single", "isrc": "USUM72401991", "isrcs": ["USUM72401991"],
"preview_url": "https://…", "artwork_url": "https://…",
"apple_music_url": "https://music.apple.com/…", "duration_seconds": 175.0 }
]
}
Errors. 400 when q has fewer than 2 words or is too long;
422 when the phrase is so common it cannot be resolved in time (add more words).
The site search accepts the same thing as a keyword operator: lyrics:that's that me espresso.
curl -G "https://audioatlas.com/v1/lyrics/search" \
--data-urlencode "q=hello from the other side" -d limit=5 \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/lyrics/search",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
params={"q": "hello from the other side", "limit": 5},
timeout=20,
)
for t in r.json()["tracks"]:
print(t["artist"], "-", t["title"])const q = encodeURIComponent("hello from the other side");
const r = await fetch(`https://audioatlas.com/v1/lyrics/search?q=${q}&limit=5`,
{ headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" } });
const { tracks } = await r.json();Fprint match lookup
Resolve an Fprint acoustic-fingerprint match to its catalog metadata. An Fprint query returns the AudioAtlas track id of the matched fingerprint. Because each catalog has its own Fprint database — and track ids are not unique across catalogs — you must pass the catalog the match came from so the correct record is returned.
Any missing metadata is scheduled for backfill the same way
/v1/search/lookup does (see processing[]).
A thin Apple/DistroKid row (Apple id but no title yet) is filled from iTunes
on the fly, so a match never resolves to an empty record.
Query parameters (both required):
catalog | string | Catalog id (e.g. 22) or source slug (e.g. audionetwork) — i.e. which Fprint database produced the match. |
id | integer | The Fprint match index = AudioAtlas track id. Alias: match_id. |
Returns { found, catalog, catalog_id, match_id, track, processing }.
404 if no track with that id exists in the given catalog;
403 if your key isn't authorised for that catalog.
curl "https://audioatlas.com/v1/fprint/lookup?catalog=audionetwork&id=38288" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/fprint/lookup",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
params={"catalog": 22, "id": 38288},
timeout=15,
)
print(r.json()["track"])const r = await fetch(
"https://audioatlas.com/v1/fprint/lookup?catalog=22&id=38288",
{ headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" } },
);
console.log((await r.json()).track);Identify audio — Shazam + all Fprint (async)
Identify an audio recording — like Shazam, but across both Apple's commercial catalog and every AudioAtlas catalog. We fingerprint the input against Apple ShazamKit (commercial recordings) and all per-catalog Fprint databases (our licensable catalogs), then return the matches.
Asynchronous: this returns a job_id; poll
GET /v1/identify/{job_id} for the result. A full
run can take ~10–60 s, since ShazamKit samples several windows of the audio.
Provide exactly one of:
audio | file | multipart/form-data file field (alias file) — the audio to identify. Any common format, ≤ 60 MB. |
url | string | Public http(s):// URL to an audio file (form field, query param, or JSON body). Fetched server-side with an SSRF guard — private/reserved addresses are rejected. |
recognizers | string | Optional. Comma list, default shazam,fprint. Use fprint for our-catalogs-only or shazam for commercial-only. |
Returns 202 with { job_id, status:"queued", poll, recognizers }.
# identify a local file
curl -X POST "https://audioatlas.com/v1/identify" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-F "[email protected]"
# identify by URL
curl -X POST "https://audioatlas.com/v1/identify" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/clip.mp3"}'Identify status
Poll an identify job. status is
queued → running → done /
error. When done, the matches arrive under
result:
best | object | The single most likely match. A confident Fprint catalog hit wins (ours/licensable); otherwise a Shazam commercial match. source is "fprint" or "shazam". |
fprint_matches[] | array | Every catalog whose fingerprint DB matched above threshold, ranked by match_count (confidence). Each has catalog, catalog_id, track_id, confidence (high|medium|low), matched time spans, and resolved track metadata. |
shazam | object | Apple ShazamKit result. Empty {} when the recording isn't in Apple's catalog (e.g. AI-generated or unreleased). |
curl "https://audioatlas.com/v1/identify/55703ba5786a4ca29cd9252954ceca10" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"
# => { "status": "done", "result": {
# "best": { "source": "fprint", "catalog": "audionetwork", "catalog_id": 22,
# "track_id": 38288, "confidence": "high", "match_count": 110,
# "track": { "title": "...", "artist": "...", "preview_url": "..." } },
# "fprint_matches": [ ... ], "shazam": { ... } } }Bulk ISRC lookup (async + callback)
Submit up to 10 000 ISRCs in one request. The server fans
the batch across every AudioAtlas catalog, optionally enriches misses via
the Deezer metadata API, and POSTs the full result list to a callback URL
you control when processing finishes. The HTTP response returns
immediately with a job_id — typical end-to-end completion is
seconds for local-only lookups, minutes for large batches that include
Deezer enrichment.
Body (JSON):
isrcs | string[] | Required. Up to 10 000 entries. Case-insensitive; duplicates removed server-side. |
callback_url | string | Required. http(s):// URL we POST the results to when the batch completes. |
client_id | string | Free-form correlation id returned unchanged in the callback body. |
enrich_missing | boolean | Default true. When true, ISRCs not found in any local catalog are looked up against Deezer. Set false to skip Deezer. |
include | string[] | List of field groups (see below). Default ["basic"]. The basic group is always implied — extra groups are additive. |
Field groups — choose only what you need; smaller payloads = faster callbacks. A track's payload only contains fields the matched catalog actually has (e.g. Shutterstock tracks have no apple_music_url even if links is requested).
About labels
One ISRC identifies a recording, and a recording is released many times — as a single, on an album, on a deluxe edition, on compilations, per storefront. Each of those is a separate row here, and the source metadata only attaches a label to some of them, sometimes with different wording.
record_label— a single best value. If the matched row carries its own label, that one is used; otherwise it is filled from the labels held for the same ISRC elsewhere in our catalogues. Preference order: a real imprint ("Interscope Records") > a licensing string ("… under exclusive license to Interscope Records") > a distributor placeholder ("7058901 Records DK2"); ties break toward the label the most releases agree on.record_labels[]— every distinct label we hold for that recording, across all catalogues, in that same preference order.record_labels[0]always equalsrecord_label. Use this when you need every attribution (rights research, auditing) rather than one answer.record_label_source— present and set to"isrc_label"when the value did not come from the matched row itself but from a sibling release.record_label_category— what kind of label this is. Returned alongside every non-emptyrecord_label:imprint— an actual label; who released the recording ("Interscope Records","Aftermath"). ~93% of what we hold.placeholder— means UNKNOWN. A distributor artefact such as"7058901 Records DK2"or"1121961 Records DK"(DistroKid, TuneCore, CD Baby, ONErpm, or a bare serial number). It is not a company and must never be shown as a rights holder — display "unknown" instead. ~7% of what we hold, so roughly 3 million ISRCs.library_brand— where the track is licensable, not who released it ("MUSICBED","ARTLIST","JAMENDO LICENSING","AUDIO NETWORK"). Useful for clearing rights, but a different claim from ownership.
Both are omitted when we hold no label at all for the recording — we never guess one.
Note that a distributor placeholder is not an imprint: strings like
"1121961 Records DK" are DistroKid artefacts, so treat a numeric
"… Records DK" value as "unknown label" rather than a rights holder.
Artist popularity. Request the popularity group to get
how well known the artist is. These are artist-level values, so every track
by the same artist carries the same numbers — they say nothing about how popular an
individual track is.
artist_deezer_fans— the raw Deezer fan count. Use this if you want to bucket artists yourself.artist_deezer_score— that fan count mapped onto a 0–100 scale. Fan counts are extremely long-tailed (a linear scale puts almost every real artist near zero), so the mapping is logarithmic above 75,000 fans and calibrated so that75,000 → 40,750,000 → 70and25,000,000 → 100. Below 75,000 fans it is a straight ramp to 40. The score is what you want for ranking and for showing a meter in a UI.artist_deezer_tier/artist_deezer_tier_label— the score cut into five bands. The number sorts and filters; the label is what to show a human.Tier Label Score ≈ fans 1 Mega Artists ≥ 85 ≥ 3,920,512 2 Mainstream Artists ≥ 70 ≥ 750,000 3 Established Artists ≥ 50 ≥ 127,568 4 Moderate Reach Artists ≥ 21 ≥ 39,375 5 Long-Tail Artists < 21 < 39,375
Absent means unknown, not unpopular. When we hold no fan count for
an artist, all three fields are omitted rather than returned as 0 — a
zero would rank a never-measured artist below one genuinely measured as small. Sort
with unknowns last, and don't read a missing score as a low score.
One caveat worth knowing: fan counts reflect Deezer adoption. Artists who broke out very recently, or on other platforms, can carry a lower tier here than their overall profile suggests, because their Deezer following has not caught up yet. The effect is strongest for recent viral releases.
| Group | Fields |
|---|---|
basic (always included) | id, song_id, title, artist, album, record_label, record_labels[], duration_seconds, preview_url, source_url, isrc, mri_status |
audio_features | bpm, music_key, key_confidence, beat_count, beat_regularity, danceability, valence, sample_rate_hz, plus all spectral / RMS librosa features. Populated only on tracks with mri_status = "completed". |
ai | ai_genre, ai_genre_secondary, ai_genre_confidence, ai_mood, ai_mood_secondary, ai_energy_level, ai_energy_score, ai_tempo_feel, ai_use_cases[], ai_similar_artists[], ai_description, ai_tags[], ai_mix_tips, has_vocals, vocal_gender |
identifiers | iswc, composer, upc, year, release_date, content_rating, track_number, disc_number, artist_id, album_id |
links | apple_music_url, spotify_url, amazon_music_url, deezer_url, napster_url, pandora_url, tidal_url, yandex_url, artwork_url |
lyrics | has_lyrics |
apple_specific | apple_genre[], is_apple_digital_master, licensable, license_price_cents, deezer_popularity, trendy_at |
popularity | artist_deezer_fans, deezer_artist_id, artist_deezer_score, artist_deezer_tier, artist_deezer_tier_label. Artist-level, not track-level — see Artist popularity. |
all | Every field listed above. |
Response (202 Accepted)
{
"job_id": 1234,
"status": "queued",
"count": 7421,
"status_url": "/v1/lookup/isrc/1234"
}
Callback body (POSTed to callback_url when the job finishes — results are in input order, after dedup):
{
"job_id": 1234,
"client_id": "your-correlation-id",
"status": "completed",
"completed_at": "2026-05-18T14:30:00Z",
"count": 7421,
"found_count": 6890,
"local_count": 6800,
"enriched_count": 90,
"results": [
{
"isrc": "USRC17600555",
"found": true,
"source": "local",
"track": {
"catalog": "apple",
"id": 12345,
"title": "…", "artist": "…", "album": "…",
"record_label": "Interscope Records",
"record_label_category": "imprint",
"record_labels": ["Interscope Records",
"SMG Music LLC & Friends Keep Secrets under exclusive license to Interscope Records"],
"isrc": ["USRC17600555"],
"duration_seconds": 187.3,
"preview_url": "https://…",
"source_url": "https://…",
"mri_status": "completed"
}
},
{
"isrc": "GBLV62307332",
"found": true,
"source": "deezer",
"enriched": true,
"track": {
"catalog": "deezer",
"title": "…", "artist": "…", "album": "…",
"record_label": "…", "upc": "…",
"duration_seconds": 201.0,
"preview_url": "https://…",
"artwork_url": "https://…",
"deezer_url": "https://…",
"release_date": "2023-09-15"
}
},
{ "isrc": "ZZZZZ9999999", "found": false }
]
}
source is "local" for catalog matches or
"deezer" for Deezer-enriched rows. The
enriched: true flag marks rows that came from Deezer
or locally-matched rows that we just backfilled (see below).
Callback delivery is retried twice on 5xx / network errors (1 s + 2 s
backoff); 4xx responses are treated as final. If the callback can't be
delivered, fall back to the polling endpoint below.
Local backfill
When enrich_missing is true (default) and a
locally-matched track has empty Deezer-fillable columns, we fetch the
track from Deezer once, UPDATE the row in place, and merge the fresh
values into the response. The UPDATE is permanent: subsequent lookups
(and /v1/search, /v1/search/lookup) return
the fuller row natively without re-paying Deezer. Backfillable columns:
record_label, upc, deezer_url, deezer_popularity,
release_date, artwork_url, preview_url
Backfill runs through the rotating proxy pool (≤ 64 parallel workers)
and is independent of your include selection — gaps are
filled opportunistically since the data is valuable across all future
callers. Rows that already have preview_url keep theirs
(Apple's preview is preserved); only NULL columns are
written. The response summary reports local_backfilled_count
so you can see how many rows the call enriched in place.
Errors: 400 invalid body (no isrcs, malformed callback URL, batch > 10 000); 401 missing or invalid X-API-Key.
curl -X POST "https://audioatlas.com/v1/lookup/isrc" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{
"isrcs": ["USRC17600555", "GBAYE0601498", "QZWFL2380089"],
"callback_url": "https://yourapp.example.com/hooks/audioatlas",
"client_id": "batch-2026-05-18-001",
"enrich_missing": true,
"include": ["audio_features", "ai", "links"]
}'import requests
r = requests.post(
"https://audioatlas.com/v1/lookup/isrc",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={
"isrcs": ["USRC17600555", "GBAYE0601498", "QZWFL2380089"],
"callback_url": "https://yourapp.example.com/hooks/audioatlas",
"client_id": "batch-2026-05-18-001",
"include": ["audio_features", "ai", "links"],
},
timeout=15,
)
print(r.status_code, r.json()) # 202, {"job_id": ..., "status_url": ...}const r = await fetch("https://audioatlas.com/v1/lookup/isrc", {
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({
isrcs: ["USRC17600555", "GBAYE0601498", "QZWFL2380089"],
callback_url: "https://yourapp.example.com/hooks/audioatlas",
client_id: "batch-2026-05-18-001",
include: ["audio_features", "ai", "links"],
}),
});
console.log(await r.json()); // { job_id, status_url, count }Bulk ISRC lookup status
Polling endpoint for the bulk job. Use it when you'd rather poll than
receive the callback, or to diagnose a callback that didn't arrive
(the response carries callback_delivered and the last
HTTP status the callback attempt returned).
Response
{
"job_id": 1234,
"status": "running", // queued | running | completed | failed | cancelled
"phase": "scanning", // queued | scanning | assembling response | posting callback | completed | failed
"total": 7421,
"processed": 4200,
"created_at": "2026-05-18T14:25:11Z",
"completed_at": null,
"callback_delivered": null, // null until callback attempted; true | false after
"callback_status": null, // e.g. "HTTP 200" or "ConnectTimeout: …"
"summary": {}, // populated when status=completed
"client_id": "your-correlation-id",
"error": null
}
Recommended polling cadence: 2–5 seconds. Job rows are kept indefinitely.
curl "https://audioatlas.com/v1/lookup/isrc/1234" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests, time
job_id = 1234
while True:
r = requests.get(
f"https://audioatlas.com/v1/lookup/isrc/{job_id}",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
timeout=10,
).json()
if r["status"] in ("completed", "failed", "cancelled"):
print(r["summary"], "delivered:", r["callback_delivered"])
break
time.sleep(3)Ensure an Apple Music track exists
Idempotent: returns the AudioAtlas Apple-catalog row for an Apple Music
track, inserting it on first call. When the track is missing, it is
fetched from iTunes, inserted, and the full enrichment chain runs
synchronously (audio fingerprinting, MusicBrainz ISRC, SACEM ISWC,
Spotify record_label, Odesli streaming links, LLM
ai_*) before the response is returned. Expect
20–60 s on first insertion; cached rows return in <50 ms.
Body (JSON — provide at least one identifier):
isrc | string | Preferred. Direct ISRC match in catalog, then fallback to iTunes Lookup ?isrc=. |
apple_music_id | string | Apple's track id (also accepts integer). |
title | string | Free-text fallback (best paired with artist). |
artist | string | Disambiguates the title search. |
Response
track | object | Full Apple-catalog row. |
source | string | "catalog" (already had it), "itunes_isrc", "itunes_id", or "itunes_search". |
created | boolean | true only when this call performed the insert. |
Errors: 400 if no identifier, 404 if iTunes has no record of the track, 500 on insert/MRI failure.
curl -X POST "https://audioatlas.com/v1/tracks/apple/ensure" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{"isrc": "USRC17600555"}'import requests
r = requests.post(
"https://audioatlas.com/v1/tracks/apple/ensure",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={"isrc": "USRC17600555"},
timeout=120, # full MRI may take up to a minute on first insert
)
data = r.json()
print(data["created"], data["source"], data["track"]["id"])const r = await fetch(
"https://audioatlas.com/v1/tracks/apple/ensure",
{
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({ title: "Yesterday", artist: "The Beatles" }),
},
);
const { track, source, created } = await r.json();Similar to a known track
Audio-to-audio similarity for a track that's already in AudioAtlas. Uses the source track's audio fingerprint to find the closest tracks across all (or filtered) catalogs. Returns 404 if the source has not been indexed yet.
Query / body parameters (all optional):
limit | integer | Default 20, max 50. |
catalog_ids | integer[] or csv | Restrict the result pool. |
exclude_same_artist | boolean | Skip other tracks by the same artist — useful for stylistic variety. |
curl "https://audioatlas.com/v1/tracks/93993520/similar?limit=10&exclude_same_artist=true" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"import requests
r = requests.get(
"https://audioatlas.com/v1/tracks/93993520/similar",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
params={"limit": 10, "exclude_same_artist": "true"},
timeout=20,
)
print(r.json()["source"], "→", len(r.json()["results"]), "matches")const r = await fetch(
"https://audioatlas.com/v1/tracks/93993520/similar?limit=10",
{ headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" } },
);
const { source, results } = await r.json();Similar to a URL
Find tracks similar to the audio at a URL. Two execution paths chosen automatically:
- Catalog hit — if the URL is already a known catalog source/preview link, the stored audio fingerprint is reused (~50 ms).
- External download — for YouTube, SoundCloud, Spotify previews, Bandcamp, or direct audio links, AudioAtlas downloads, fingerprints, and matches in one call. Results are cached by SHA-256 of the audio bytes, so re-posting the same URL is instant.
Body
url * | string | Media URL (YouTube, SoundCloud, Spotify, Bandcamp, Vimeo, or direct audio). |
limit | integer | Default 5, max 50. |
catalog_ids | integer[] | Restrict to specific catalogs. |
bypass_cache | boolean | Skip the cached result for this audio and force a fresh analysis (the fresh result is still cached for next time). Aliases: no_cache, force. |
curl -X POST https://audioatlas.com/v1/search/similar-by-url \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"limit": 10
}'import requests
r = requests.post(
"https://audioatlas.com/v1/search/similar-by-url",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={"url": "https://soundcloud.com/.../track", "limit": 10},
timeout=120, # external download can take a few seconds
)
print(r.json())const r = await fetch("https://audioatlas.com/v1/search/similar-by-url", {
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://...", limit: 10 }),
});
console.log(await r.json());/v1/search/similar-by-file hits the cache.
Similar to an uploaded audio file
Upload an audio file and get the closest matches in the catalog. Accepts standard
formats (mp3, wav, m4a, flac, ogg). Multipart file field is required.
Form fields
file * | file | The audio to match against. |
limit | integer | Default 5, max 50. |
catalog_ids | JSON string | JSON-encoded array of catalog ids, e.g. [6,4]. |
bypass_cache | boolean | Skip the cached result for this file (keyed by SHA-256) and force a fresh analysis; the fresh result is still written to the cache. Aliases: no_cache, force. |
curl -X POST https://audioatlas.com/v1/search/similar-by-file \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-F "file=@./reference.mp3" \
-F "limit=10"import requests
with open("reference.mp3", "rb") as f:
r = requests.post(
"https://audioatlas.com/v1/search/similar-by-file",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
files={"file": f},
data={"limit": 10},
timeout=120,
)
print(r.json())const fd = new FormData();
fd.append("file", fileBlob);
fd.append("limit", "10");
const r = await fetch("https://audioatlas.com/v1/search/similar-by-file", {
method: "POST",
headers: { "X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" },
body: fd,
});
console.log(await r.json());Artist metrics
Batch-fetch popularity metrics (Last.fm listeners & playcount) for up to
100 artist names in one call. Results are cached server-side and refreshed
roughly every 30 days; names that can't be resolved come back with
not_found: true and null metrics rather than failing the batch.
Body
artists * | string[] | Artist names, max 100 (extras are ignored). An empty list returns {"artists": {}}. |
Response — an artists object keyed by the lower-cased artist name, each value:
artist_name | string | Canonical name as resolved on Last.fm. |
listeners | integer | Last.fm listener count (null if unknown). |
playcount | integer | Last.fm total play count (null if unknown). |
lastfm_url | string | Artist page URL on Last.fm. |
fetched_at | string | ISO-8601 timestamp of when these metrics were last refreshed. |
not_found | boolean | true when the name couldn't be matched; the other fields are null. |
curl -X POST https://audioatlas.com/v1/artists/metrics \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{
"artists": ["Olivia Rodrigo", "Hans Zimmer"]
}'import requests
r = requests.post(
"https://audioatlas.com/v1/artists/metrics",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={"artists": ["Olivia Rodrigo", "Hans Zimmer"]},
timeout=30,
)
print(r.json()["artists"])const r = await fetch("https://audioatlas.com/v1/artists/metrics", {
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({ artists: ["Olivia Rodrigo", "Hans Zimmer"] }),
});
console.log((await r.json()).artists);Score one track against an audio URL
One-to-one similarity score between an arbitrary audio URL and a single catalog track's stored audio fingerprint. Use this when you already know which track you're comparing against (sync validation, A/B reference checks) — it's a direct score rather than a search.
Accepts the URL via either: JSON body {"audio": "https://…"} (also accepts "url") or query string ?audio=https://….
Response (200)
track_id | integer | The id you queried. |
similarity | float | 0.0–1.0 similarity score. |
score | integer | round(similarity * 100). Use this for UI display. |
track | object | {id, title, artist} of the matched track. |
audio_url | string | The URL you passed in (echoed back). |
HTTP codes: 200 OK · 400 missing or invalid URL · 404 track not found · 409 track has not been indexed yet (enrichment pending) · 500 download or fingerprint failure.
curl -X POST "https://audioatlas.com/v1/tracks/12968462/score" \
-H "X-API-Key: aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7" \
-H "Content-Type: application/json" \
-d '{"audio": "https://example.com/reference.mp3"}'import requests
r = requests.post(
"https://audioatlas.com/v1/tracks/12968462/score",
headers={"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7"},
json={"audio": "https://example.com/reference.mp3"},
timeout=60,
)
data = r.json()
print(f"{data['score']}/100 — similarity {data['similarity']:.4f}")const r = await fetch("https://audioatlas.com/v1/tracks/12968462/score", {
method: "POST",
headers: {
"X-API-Key": "aa_8f1c2d3e4b5a6978c0d1e2f3a4b5c6d7",
"Content-Type": "application/json",
},
body: JSON.stringify({ audio: "https://example.com/reference.mp3" }),
});
const { score, similarity } = await r.json();Response headers
Every response (including errors that authenticated successfully) carries the rate-limit headers documented under Quotas. Use them to display remaining-quota meters in dashboards.