NotOnQ docs

Artists only, for this hackathon

NotOnQ fills gaps for music artists (urn:entity:artist). Requests for any other entity type, and any request Qloo can answer, pass straight through to Qloo unchanged.

Quickstart

Change one base URL. Qloo always answers first with your own key; NotOnQ only adds to the response when Qloo has a gap for an artist, and never removes or reorders anything Qloo returned.

Two environment variables, no new install

# The official Qloo MCP server (@qloo/qloo-harness), unchanged. Only its base URL points at NotOnQ:QLOO_API_KEY=<your Qloo key> \QLOO_BASE_URL=https://<notonq-host>/q/app/my-app \QLOO_TRUSTED_BASE_URL=https://<notonq-host>/q/app/my-app \qloo mcp

Both variables are needed: the harness only sends your key to a base URL you have marked as trusted (true for Qloo's own hackathon host as well). my-app is your app's name in the Ledger; leave out /app/my-app to stay unlabelled. Same tools, same results; see MCP for what changes.

When NotOnQ steps in

Gap	How Qloo shows it	What NotOnQ does
Unknown (G1)	/search has no artist with the exact name (404 or other names only)	Adds the artist after Qloo's results, filled from open data, or every artist the name could be when it is ambiguous
Not in the taste graph (G2)	Search finds it, but /v2/insights answers 400 for it as a signal	Swaps it for stand-ins: similar artists Qloo does know
None	Qloo answers	Steps aside: Qloo's response passes through unchanged

Same shape as Qloo, 1:1

A filled artist has exactly the keys and types Qloo returns. Its entity ID is a UUID like Qloo's (the MusicBrainz ID, or a stable ID NotOnQ makes), so any Qloo client can send it back; properties.short_description starts with "Not in Qloo" and names the stand-ins. Genre tag IDs and keys Qloo doesn't have start with notonq:. Qloo's own values are never changed. Send a NotOnQ ID back as a signal and NotOnQ swaps in its stand-ins.

Qloo

NotOnQ fallback

{{  "results": [{  "results": [{    "entity_id": "B8BEE72B-…",    "entity_id": "502cf908-…",    "name": "sombr",    "name": "sombr",    "types": ["urn:entity:artist"],    "types": ["urn:entity:artist"],    "tags": [{    "tags": [{      "tag_id": "urn:tag:genre:pop",      "tag_id": "notonq:urn:tag:genre:pop",      "type": "urn:tag:genre"      "type": "urn:tag:genre"    }],    }],    "properties": {    "properties": {      "short_description": "American singer…",      "short_description": "Not in Qloo: filled by NotOnQ… American singer…",      "external": {      "external": {      "lastfm": { "id", "listeners" },      "lastfm": { "id", "listeners" },
      "notonq:deezer": { "id", "fans" }    } },    } },  }],  }],
  "notonq": { "served_by", "provenance", … }}}

Every value has proof

The notonq.provenance block maps each field to its sources: source, record URL, licence, retrieval time and method.

method	Means
copied	Taken as-is from the cited record (MusicBrainz, Wikidata, Wikipedia, Last.fm, Deezer)
derived	Computed by NotOnQ from cited inputs, with the formula in the note (popularity)
qloo_proxy	Qloo's own answer, for the stand-ins listed
researched	Found by the research agent; the exact quote was re-checked on the cited page by plain code

Caching, demand and budgets

Fallbacks are open data, so they are shared: filled artists refresh weekly, misses and fills with a failed source retry after a day.
Qloo responses are cached per caller key only, never shared between callers.
Every artist lookup counts towards the Ledger, against a salted hash of your key and your app label (/q/app/<label> or X-NotOnQ-App). Keys are never stored.
Each caller has a daily budget of real Qloo calls (default 1500; cache hits are free). Over it, NotOnQ answers 429 until 00:00 UTC.

Inside Qloo

NotOnQ shows the behaviour, not the data pipeline. The open sources it uses here (MusicBrainz, Wikidata, Wikipedia, Last.fm, Deezer) stand in for whatever Qloo would use. Built into Qloo, the same flow would run on Qloo's own licensed sources and taste graph: fill the gap, label it, answer taste questions through similar artists, and step aside once the artist is in the catalogue. The Ledger shows which missing artists people actually ask for. Artists first, for this hackathon; the same pattern fits other entity types.

Known limits

Artists only. Other entity types pass through to Qloo.
/v2/trending: no fallback series yet, so Qloo's answer passes through (it has had no data since about May 2026).
An artist with no similar artist Qloo knows gets an empty taste answer (its label says why), never a guess.
Research needs an AI Gateway credential on the host; without one the Research step reports it is off.