BulkLookupResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/freqblog-com/json-schema/freqblog-com-bulk-lookup-response-schema.json",
  "title": "BulkLookupResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/freqblog-com-openapi.json#/components/schemas/BulkLookupResponse",
  "properties": {
    "results": {
      "items": {
        "$ref": "#/$defs/BulkTrackResult"
      },
      "type": "array",
      "title": "Results"
    },
    "found": {
      "type": "integer",
      "title": "Found",
      "description": "Number of tracks found in the catalog."
    },
    "not_found": {
      "type": "integer",
      "title": "Not Found",
      "description": "Number of tracks not found (includes skipped items)."
    },
    "requests_used": {
      "type": "integer",
      "title": "Requests Used",
      "description": "Number of quota requests consumed by this call."
    },
    "skipped": {
      "type": "integer",
      "title": "Skipped",
      "description": "Items echoed but NOT processed or charged this call — either past the 50-track per-call cap (`backfill_status=\"over_limit\"`) or missing both `isrc` and `track` (`backfill_status=\"invalid_no_query\"`). Resubmit the over-limit tail in batches of ≤50; fix the malformed rows. 0 on a normal batch.",
      "default": 0
    },
    "hint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Hint",
      "description": "Plain-English guidance, present only when MORE THAN HALF of the processed items came back unfinished (`backfill_status` `queued` or `processing`) — typically a first import of tracks we have not analysed yet. It says how to collect them: re-send the same rows in ~30-60s, or register a webhook with `POST /me/webhook`. Null otherwise. For humans and logs: the wording may change, so branch on the per-item `backfill_status`, never on this text."
    }
  },
  "type": "object",
  "required": [
    "results",
    "found",
    "not_found",
    "requests_used"
  ],
  "$defs": {
    "BulkTrackResult": {
      "properties": {
        "track": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Track",
          "description": "Track name as submitted (null for ISRC-only items)."
        },
        "artist": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Artist",
          "description": "Artist name as submitted in the request."
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Isrc",
          "description": "ISRC for this item, when one was supplied — echoed back so you can map results onto ISRC-keyed inputs."
        },
        "found": {
          "type": "boolean",
          "title": "Found",
          "description": "True if the track was found in any source (catalog or fallback chain)."
        },
        "result": {
          "anyOf": [
            {
              "$ref": "#/$defs/TrackLookupResponse"
            },
            {
              "type": "null"
            }
          ],
          "description": "Audio features. Null if track not found."
        },
        "backfill_status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Backfill Status",
          "description": "`queued` when a field-backfill or on-demand ingest was started for this item (retry later to collect it); `processing` when the server time-box was hit before it resolved (retry to collect it); `deferred` when this call had already started its per-request maximum of new ingests (resend it in a later call); `unavailable` for a terminal verdict — see `terminal`, `reason`, `retry_after_days`; `ingest_limit_reached` when a Free key's monthly on-demand ingest allowance is spent; `over_limit` when the item was past this call's 50-track processing cap; `invalid_no_query` when the item carried neither `isrc` nor `track`; null when there is no match anywhere and nothing to queue. Among `found=false` items only `queued` is charged."
        },
        "terminal": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Terminal",
          "description": "True when `backfill_status` is `unavailable`: we already tried this track and re-sending it before `retry_after_days` will not change the answer. Null otherwise."
        },
        "reason": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reason",
          "description": "Why an `unavailable` item is terminal: `not_on_streaming`, `no_preview_audio`, `ingest_failed` or `ingested_unmatched` — the same values `/lookup` returns on its terminal 404. Null otherwise."
        },
        "retry_after_days": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Retry After Days",
          "description": "For an `unavailable` item, how long to treat it as a negative result before asking again (the catalogue grows daily, so never cache it permanently). Null otherwise."
        }
      },
      "type": "object",
      "required": [
        "found"
      ],
      "title": "BulkTrackResult"
    },
    "ExtendedAudioFeatures": {
      "properties": {
        "gender": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Gender",
          "description": "Always null since 2026-10-02. Was a vocal-gender classification (`male` / `female`) from AcousticBrainz; it was too unreliable on real catalogue tracks to serve. The key is kept so existing parsers don't break."
        },
        "timbre": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Timbre",
          "description": "Timbral brightness classification: `bright` / `dark`. Bright = strong high-frequency content (cymbals, electric guitar); dark = bass-dominant."
        },
        "tonal_atonal": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Tonal Atonal",
          "description": "Tonality classification: `tonal` / `atonal`. Tonal = clear key centre; atonal = ambiguous or shifting tonality (typical of avant-garde / drone)."
        }
      },
      "type": "object",
      "title": "ExtendedAudioFeatures",
      "description": "Higher-level categorical labels from AcousticBrainz. Each value is the\nmost-confident class from a binary classifier — useful for filtering /\nbucketing but not for fine-grained analysis."
    },
    "TrackLookupResponse": {
      "properties": {
        "track_name": {
          "type": "string",
          "title": "Track Name",
          "description": "Track name as indexed in the catalogue or from MusicBrainz."
        },
        "artist_name": {
          "type": "string",
          "title": "Artist Name",
          "description": "Artist name."
        },
        "album_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Album Name",
          "description": "Album or single title. Populated for catalog tracks."
        },
        "itunes_track_id": {
          "type": "string",
          "title": "Itunes Track Id",
          "description": "iTunes track ID for catalog tracks; 'mb:{mbid}' for AcousticBrainz-sourced tracks. (The former 'fma:' / 'msd:' ids no longer resolve.)"
        },
        "isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Isrc",
          "description": "International Standard Recording Code. Uniquely identifies this specific master recording."
        },
        "mbid": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Mbid",
          "description": "MusicBrainz Recording ID (UUID). Cross-reference to the open music encyclopedia."
        },
        "is_remix": {
          "type": "boolean",
          "title": "Is Remix",
          "description": "True when this recording is a third-party remix/bootleg (not an original mix or same-performance version). Parsed from the title + credit at ingest. Always present; false for originals and fallback-layer tracks.",
          "default": false
        },
        "remixer": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Remixer",
          "description": "The third-party artist credited with the remix, when attributable; null for style-descriptor or unnamed remixes."
        },
        "mix_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Mix Name",
          "description": "Version/mix descriptor for any variant (remix OR version), e.g. 'Extended Mix', 'Alesso Remix'. Null for a plain original."
        },
        "remix_of_isrc": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Remix Of Isrc",
          "description": "ISRC of the ORIGINAL recording this remix is based on, when the original is in the catalog (matched by base title + artist). Lets you jump from a remix to its source recording. Null for originals, unmatched remixes, and fallback-layer tracks."
        },
        "release_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Release Date",
          "description": "Release date in ISO 8601 format (YYYY-MM-DD), from catalogue metadata. Null for fallback-layer tracks."
        },
        "duration_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Duration Ms",
          "description": "Full track duration in milliseconds, from catalogue metadata. Distinct from `duration_seconds` (which is the analysed 30s window)."
        },
        "explicit": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Explicit",
          "description": "True if the track is marked explicit by the source. Null when not reported."
        },
        "bpm": {
          "type": "number",
          "maximum": 300.0,
          "minimum": 20.0,
          "title": "Bpm",
          "description": "Tempo in beats per minute."
        },
        "bpm_alt": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bpm Alt",
          "description": "Half-time corrected alternative BPM (twice the detected `bpm`), when our heuristic is fairly confident Essentia locked onto half the beat grid. Only offered for tracks detected at 70-88 BPM; null otherwise (drum & bass detected at 108-122 BPM instead gets 1.5x, e.g. 115 -> 172.5: the detector often reads a 174 BPM break at two-thirds speed). **Never** replaces `bpm` — use this when your downstream tooling expects the perceived rather than detected tempo (e.g. pop tracks like 'Blinding Lights' where Essentia returns ~85 but the perceived BPM is ~171)."
        },
        "bpm_confidence": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bpm Confidence",
          "description": "Beat-strength score from Essentia RhythmExtractor2013, about 0–5.3 (catalogue median ~2.9). Below ~1.5 the tempo is worth checking by ear: on crowd-tapped electronic tracks our BPM matched a listener's tempo 57% of the time below 1.0 and 99% at 3.5–4. Null for AcousticBrainz-sourced tracks."
        },
        "key": {
          "type": "string",
          "title": "Key",
          "description": "Musical key and scale, e.g. `C#-Minor`."
        },
        "key_confidence": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Key Confidence",
          "description": "Key detection confidence [0–1]. Null for AcousticBrainz-sourced tracks."
        },
        "mode": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Mode",
          "description": "Spotify-compatible mode integer: 0 = minor, 1 = major."
        },
        "key_int": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 11.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Key Int",
          "description": "Spotify-compatible pitch-class integer for the key: 0 = C, 1 = C♯/D♭, 2 = D, … 11 = B. `null` when the key is undetected/atonal (the Spotify-shaped `/v1/audio-features/{id}` endpoint reports `-1` in that case, matching Spotify's convention)."
        },
        "camelot": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Camelot",
          "description": "Camelot wheel notation, e.g. `12A`."
        },
        "open_key": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Open Key",
          "description": "Open Key notation, e.g. `5m` (C#-Minor). d=major, m=minor."
        },
        "energy": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Energy",
          "description": "Perceived energy [0–1] of the 30-second preview: a PANNs-based model (Kong et al. 2020, CC BY 4.0) placed on our existing energy scale (median ~0.65). It agrees better with human listener ratings than the RMS loudness it replaced (checked on two independent rating datasets); tracks the model has not reached yet still carry the RMS value."
        },
        "loudness_db": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Loudness Db",
          "description": "Integrated loudness in dBFS."
        },
        "danceability": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Danceability",
          "description": "How suitable the track is for dancing [0–1], on AcousticBrainz's scale: AcousticBrainz's classifier where a recording has it, otherwise a model built on PANNs embeddings (Kong et al. 2020, CC BY 4.0) and trained on AcousticBrainz labels."
        },
        "valence": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Valence",
          "description": "Musical positiveness [0–1] of the 30-second preview (high = happy/uplifting, low = sad/dark), from a PANNs-based model (Kong et al. 2020, CC BY 4.0) placed on our existing valence scale (median ~0.48). It agrees better with human listener ratings than the signal heuristic it replaced on two of three independent rating datasets; it still partly tracks energy, so treat it as a sorting aid. Tracks the model has not reached yet carry the heuristic value."
        },
        "speechiness": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Speechiness",
          "description": "Spoken word presence [0–1]. Null for catalogue tracks for now."
        },
        "instrumentalness": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Instrumentalness",
          "description": "Likelihood [0–1] that the 30-second preview has no vocals, from a model on PANNs embeddings (Kong et al. 2020, CC BY 4.0) trained on the vocal/no-vocal labels of the MUSAN corpus (Snyder et al. 2015, CC BY 4.0). Describes the preview, not the whole track. Null where a track has not been through the model yet."
        },
        "liveness": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Liveness",
          "description": "Live performance likelihood [0–1]. Null for catalogue tracks for now (not measured reliably enough to serve)."
        },
        "acousticness": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Acousticness",
          "description": "Acousticness [0–1]: AcousticBrainz's classifier where available, otherwise a model built on PANNs embeddings (Kong et al. 2020, CC BY 4.0) and trained on AcousticBrainz labels."
        },
        "time_signature": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Time Signature",
          "description": "Beats per bar. ASSUMED 4 (4/4) for every track we analyse, not measured: no meter estimator we have tested beats a constant 4 on a mostly 4/4 catalogue. Kept in the Spotify response shape for compatibility; do not filter or branch on it."
        },
        "mood": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Mood",
          "description": "MIREX-style mood category: happy, calm, sad, tense, energetic, melancholic, or neutral."
        },
        "mood_vector": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": "number"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Mood Vector",
          "description": "Dimensional mood scores [0–1] across five axes: `happy`, `sad`, `aggressive`, `relaxed`, `party`. Populated when an AcousticBrainz high-level match is found; `null` otherwise."
        },
        "onset_rate": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Onset Rate",
          "description": "Onset events per second from AcousticBrainz low-level analysis. Higher values indicate more rhythmic or percussive content. Populated when an AcousticBrainz match is found; `null` otherwise."
        },
        "dynamic_complexity": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dynamic Complexity",
          "description": "Loudness variation over the track (dB), from AcousticBrainz low-level analysis. Higher values mean wider dynamic range; lower values mean more compressed mastering. Populated when an AcousticBrainz match is found; `null` otherwise."
        },
        "tuning_frequency": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Tuning Frequency",
          "description": "Estimated A4 reference frequency in Hz, from AcousticBrainz tonal analysis. Modern recordings cluster near 440 Hz; older or non-Western recordings may diverge. Populated when an AcousticBrainz match is found; `null` otherwise."
        },
        "average_loudness": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Average Loudness",
          "description": "Average loudness as a normalised value [0–1] from AcousticBrainz low-level analysis. Distinct from `loudness_db` (which is dBFS from this service's own analysis). Populated when an AcousticBrainz match is found; `null` otherwise."
        },
        "genre": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Genre",
          "description": "Broad genre classification (e.g. electronic, rock, pop, hip-hop, jazz). From catalogue metadata, with AcousticBrainz as a fallback."
        },
        "extended": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExtendedAudioFeatures"
            },
            {
              "type": "null"
            }
          ],
          "description": "Higher-level AcousticBrainz classifications. Populated when the track has an AcousticBrainz match — null otherwise. Counts as ONE of the 43 response fields (it is a single nested object), but its members are categorical labels rather than analysis values, so they are not counted individually."
        },
        "feature_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Feature Source",
          "description": "Provenance of the audio feature data. One of: `essentia_preview` (analysed from a 30s preview by this service), `acousticbrainz` (matched by MBID against the AcousticBrainz dump), `user_upload` (analysed from a file the user uploaded). (`fma` and `msd` were retired on 2026-09-29 and no longer appear.)"
        },
        "backfill_status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Backfill Status",
          "description": "Backfill job status if one was queued: 'queued', 'processing', 'completed', 'failed'. Null if no backfill was needed."
        },
        "backfill_notification_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Backfill Notification Id",
          "description": "Notification ID for tracking backfill progress. Use to query backfill_notifications table."
        },
        "chart_peak": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Chart Peak",
          "description": "Best chart position we know this track reached, 1-100 where **100 = a number-one**. `null` means no chart placement we hold — which is the vast majority of the catalogue, so treat null as *unknown*, not as *unpopular*. ⚠ NOT an audience-size measure: it does not tell you monthly listeners or followers. Placements come from the Apple Music and Deezer charts we track (best position seen since August 2026) and Billboard's year-end charts (1960-2025), so most tracks have none. Present on the browse endpoints too — see `TrackStub.chart_peak`."
        },
        "bpm_snapped": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bpm Snapped",
          "description": "`bpm` rounded to a whole number — the grid tempo, in the form every DJ tool reports. Traktor, Serato and Rekordbox return clean integers because they derive a BEAT GRID, and a grid has exactly one tempo by construction; our `bpm` is a *measurement* of the audio, so it carries a decimal. For grid-produced music the true tempo is almost certainly the whole number and the decimal is our error — `bpm_confidence` correlates with how close we land to an integer, which is the evidence for that. **Always populated, never null.** Use `bpm` when you want the measurement (beatmatching by ear, where 127.89 vs 128.00 is the point) and `bpm_confidence` to judge how far to trust either.",
          "readOnly": true
        }
      },
      "type": "object",
      "required": [
        "track_name",
        "artist_name",
        "itunes_track_id",
        "bpm",
        "key",
        "bpm_snapped"
      ],
      "title": "TrackLookupResponse"
    }
  }
}