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:

HeaderMeaning
X-RateLimit-LimitYour monthly quota (omitted if unlimited).
X-RateLimit-UsedRequests counted in the current month, including this one.
X-RateLimit-RemainingQuota left until reset.
X-RateLimit-ResetISO-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.

HTTPCodeMeaning
400bad_requestMissing or invalid parameter (e.g. empty query, query > 512 chars).
401missing_api_keyNo X-API-Key header on the request.
401invalid_api_keyThe key doesn't exist.
403key_disabledThe key has been revoked.
403key_expiredThe expiry date has passed.
429quota_exceededMonthly quota exhausted.
500internal_errorUnexpected 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.

POST/mcp

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>.

ToolDoesSame as
search_musicFree-text brief or "artist + title" searchPOST /v1/search
lookup_tracksExact lookup by ISRC, ISWC, artist, title, composerGET /v1/search/lookup
get_trackOne track by id, with fresh preview linkGET /v1/tracks/{id}
find_similar_tracksTracks that sound like a trackGET /v1/tracks/{id}/similar
similar_to_urlTracks that sound like the audio at a URLPOST /v1/search/similar-by-url
search_lyricsFind a song from a lyric phraseGET /v1/lyrics/search
beat_gridBeats, downbeats and BPM for video syncGET /v1/tracks/{id}/beats
identify_audio / get_identificationIdentify a recording from an audio URL/v1/identify
catalog_statsCatalogue size, daily additions, AI shareGET /v1/stats
api_usageYour key's usage and monthly limitGET /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

GET/v1/health

Lightweight liveness probe. No authentication required.

$ curl https://audioatlas.com/v1/health
{ "status": "ok" }

Usage

GET/v1/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

GET/v1/fresh

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

GET/v1/stats

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 }
    ]
  }
}
FieldDescription
dateThe latest complete UTC day in the series; tracks.added and the ai day figures refer to it.
tracks.totalTracks in the index, all catalogues, at computed_at.
tracks.addedTracks added to the index on date.
ai.added / ai.scanned / ai.share_pctOf that day’s additions: tracks flagged as AI-generated, tracks scanned (releases dated 2023 or later), and the AI share in percent.
ai.catalogCatalogue-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);
POST/v1/search

The flagship endpoint. Send a free-text brief and get ranked tracks back.

Request body

FieldTypeDescription
query *stringFree-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).
limitintegerNumber of results, default 10, max 50.
providerstring"musical" (default, audio-similarity flavor — best for "sounds like" queries) or "semantic" (text-meaning flavor — best for descriptive briefs like "sad cinematic piano").
filtersobjectHard filters that override the parser's guesses — see below.
catalog_idsinteger[]Restrict the search to specific catalogs. Omit for all available catalogs.
intentobjectOptional 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.
langstringTwo-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).

OperatorBehavior
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:

TypeHonored fieldsSearch strategy
soundtrackfilm_title, composerOR-match the film name against title + album, optionally narrowed by composer. Real soundtrack albums rank above covers.
song_titlesong_titleILIKE on track title.
composercomposerILIKE on composer (artist fallback on non-Apple catalogs).
artistartist_nameILIKE on artist.
sonicdescriptionSemantic match against the supplied description; skips literal-title fallback.
any—Skip the popup; run the full default pipeline.

Available filters

bpm_min / bpm_maxintegerTempo window in BPM.
vocal_typesstring[]Instrumental, Male Vocals, Female Vocals, Mixed Vocals, Choir, Vocal Samples, Spoken Word.
energy_levelsstring[]Very Low, Low, Medium, High, Very High.
genres / moodsstring[]Free strings — see the discovery page for the full vocabulary.
year_min / year_maxintegerRelease year range.
min_duration / max_durationintegerTrack length in seconds.
licensable_onlybooleanRestrict to catalogs marked licensable in your account.
aistring"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:

{
  "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.

idintegerAudioAtlas internal ID. Stable per catalog.
catalog_idintegerWhich catalog this track came from.
title / artist / albumstringDisplay metadata.
isrc / iswc / composerstringIndustry identifiers, when known.
preview_urlstring (URL)~30 s audio preview.
duration_secondsnumberFull track length.
bpm / music_keynumber / stringTempo and detected key (Camelot or scientific).
ai_genre / ai_genre_secondarystringPrimary and secondary AI-tagged genre.
ai_mood / ai_mood_secondarystringPrimary and secondary mood descriptor.
ai_energy_level / ai_energy_scorestring / numberEnergy bucket ("Low" / "Medium" / "High") plus a 0–1 score.
ai_tempo_feelstringSubjective tempo descriptor (e.g. "Steady Mid-tempo").
ai_tagsstring[]Free-form audio tags (e.g. instruments, textures, production cues).
ai_use_casesstring[]Suggested sync / placement contexts (e.g. "Coffee Commercial").
ai_descriptionstringShort natural-language summary.
ai_similar_artistsstring[]3–5 reference artists with a similar sonic profile (LLM-generated, lazy on first read).
ai_mix_tipsstringOne-line production / mix note (LLM-generated, lazy on first read).
vocal_genderstring"male" / "female" / null for instrumental.
has_vocalsbooleanWhether the track contains a vocal performance.
artwork_urlstring (URL)Album / track artwork thumbnail when available.
record_labelstringTrack-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_labelsstring[]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_gridobjectBeat 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_verdictstringOn 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_scorenumber / nullOn 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.
publishersobject[] / nullMusic 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_typestring / null"Instrumental", "female" / "male" (vocal performance with a known singer gender, same as vocal_gender), "Vocals" (vocals, gender unknown), or null when not analysed.
isrcsstring[]Every ISRC known for this recording; isrcs[0] equals isrc.
song_idstringApple Music song id (Apple-catalogue tracks).
similaritystring / numberRaw match score behind search_score (0–1). Prefer search_score for display.
parent_labelstringCatalog publisher / parent label (e.g. "Apple Music", "Musicbed").
licensable / license_price_centsboolean / integerDirect-licensing status, when applicable to your account.
apple_music_url / spotify_url / amazon_music_url / deezer_url / tidal_url / napster_url / pandora_url / yandex_urlstring (URL)Streaming-platform deep links. Resolved lazily via Odesli on first read for Apple-catalog tracks.
artist_popularityobjectLast.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_statusstringAudio-analysis state: "completed" means features (BPM / key / fingerprint / AI tags) are ready. "pending" / "failed" means a backfill is in flight or unavailable.
search_scoreinteger (0–100)Similarity score for this query. Higher is closer. (Search results only.)
processingstring[]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_resolutionstring / stringPresent 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

GET/v1/tracks/{track_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

GET/v1/tracks/{track_id}/beats

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.

GET/v1/search/lookup

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):

artiststringArtist name (case-insensitive substring).
titlestringTrack title.
isrcstringExact ISRC.
iswcstringExact ISWC.
composerstringComposer credit.
publisherstringPublisher name or IPI: returns tracks of the works that publisher holds.
catalog_idsstringComma-separated catalog IDs to filter (e.g. 6,4).
limitintegerNumber 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);
GET/v1/lyrics/search

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 *stringA phrase from the song: at least 2 words, at most 300 characters.
limitintegerDefault 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

GET/v1/fprint/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):

catalogstringCatalog id (e.g. 22) or source slug (e.g. audionetwork) — i.e. which Fprint database produced the match.
idintegerThe 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)

POST/v1/identify

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:

audiofilemultipart/form-data file field (alias file) — the audio to identify. Any common format, ≤ 60 MB.
urlstringPublic 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.
recognizersstringOptional. 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

GET/v1/identify/{job_id}

Poll an identify job. status is queued → running → done / error. When done, the matches arrive under result:

bestobjectThe single most likely match. A confident Fprint catalog hit wins (ours/licensable); otherwise a Shazam commercial match. source is "fprint" or "shazam".
fprint_matches[]arrayEvery 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.
shazamobjectApple 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)

POST/v1/lookup/isrc

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):

isrcsstring[]Required. Up to 10 000 entries. Case-insensitive; duplicates removed server-side.
callback_urlstringRequired. http(s):// URL we POST the results to when the batch completes.
client_idstringFree-form correlation id returned unchanged in the callback body.
enrich_missingbooleanDefault true. When true, ISRCs not found in any local catalog are looked up against Deezer. Set false to skip Deezer.
includestring[]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 equals record_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-empty record_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 that 75,000 → 40, 750,000 → 70 and 25,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.
    TierLabelScore≈ fans
    1Mega Artists≥ 85≥ 3,920,512
    2Mainstream Artists≥ 70≥ 750,000
    3Established Artists≥ 50≥ 127,568
    4Moderate Reach Artists≥ 21≥ 39,375
    5Long-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.

GroupFields
basic (always included)id, song_id, title, artist, album, record_label, record_labels[], duration_seconds, preview_url, source_url, isrc, mri_status
audio_featuresbpm, 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".
aiai_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
identifiersiswc, composer, upc, year, release_date, content_rating, track_number, disc_number, artist_id, album_id
linksapple_music_url, spotify_url, amazon_music_url, deezer_url, napster_url, pandora_url, tidal_url, yandex_url, artwork_url
lyricshas_lyrics
apple_specificapple_genre[], is_apple_digital_master, licensable, license_price_cents, deezer_popularity, trendy_at
popularityartist_deezer_fans, deezer_artist_id, artist_deezer_score, artist_deezer_tier, artist_deezer_tier_label. Artist-level, not track-level — see Artist popularity.
allEvery 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

GET/v1/lookup/isrc/{job_id}

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

POST/v1/tracks/apple/ensure

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):

isrcstringPreferred. Direct ISRC match in catalog, then fallback to iTunes Lookup ?isrc=.
apple_music_idstringApple's track id (also accepts integer).
titlestringFree-text fallback (best paired with artist).
artiststringDisambiguates the title search.

Response

trackobjectFull Apple-catalog row.
sourcestring"catalog" (already had it), "itunes_isrc", "itunes_id", or "itunes_search".
createdbooleantrue 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

GET/v1/tracks/{id}/similar

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):

limitintegerDefault 20, max 50.
catalog_idsinteger[] or csvRestrict the result pool.
exclude_same_artistbooleanSkip 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

POST/v1/search/similar-by-url

Find tracks similar to the audio at a URL. Two execution paths chosen automatically:

Body

url *stringMedia URL (YouTube, SoundCloud, Spotify, Bandcamp, Vimeo, or direct audio).
limitintegerDefault 5, max 50.
catalog_idsinteger[]Restrict to specific catalogs.
bypass_cachebooleanSkip 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());
Downloads can take a few seconds (yt-dlp / Spotify preview). Set a generous client timeout — at least 30 s. The cache key is the SHA-256 of the audio bytes, so a follow-up call with the same URL or a re-upload of the same file via /v1/search/similar-by-file hits the cache.

Similar to an uploaded audio file

POST/v1/search/similar-by-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 *fileThe audio to match against.
limitintegerDefault 5, max 50.
catalog_idsJSON stringJSON-encoded array of catalog ids, e.g. [6,4].
bypass_cachebooleanSkip 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

POST/v1/artists/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_namestringCanonical name as resolved on Last.fm.
listenersintegerLast.fm listener count (null if unknown).
playcountintegerLast.fm total play count (null if unknown).
lastfm_urlstringArtist page URL on Last.fm.
fetched_atstringISO-8601 timestamp of when these metrics were last refreshed.
not_foundbooleantrue 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

POST/v1/tracks/{id}/score

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_idintegerThe id you queried.
similarityfloat0.0–1.0 similarity score.
scoreintegerround(similarity * 100). Use this for UI display.
trackobject{id, title, artist} of the matched track.
audio_urlstringThe 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.