Batch lookup

POST/api/v1/metadata/lookups

Look up up to 100 identifiers in one request. This is the path to check a batch before you send it, or to preload a catalogue: one request instead of one per asset. Same auth as the single endpoint, with the metadata:read scope or the older covers:read. The same endpoint answers at /api/v1/metadata/album-covers, its original name, kept for the partner that calls it today.

One request spends at most 20 seconds on our cover source, shared by all its items. An item that needs the cover source after that answers source_unavailable. Retry those items in a later request.

Request body#

{
  "items": [
    { "id": "row-1", "isrc": "USRC12345678", "title": "Black Sheep", "artist": "Kng Ego" },
    { "id": "row-2", "iswc": "T-123.456.789-0" },
    { "id": "row-3", "external_id": "A12345" }
  ],
  "allow_title_fallback": false
}

• Each item takes the same fields as the single endpoint (isrc, iswc, external_id, plus optional title/artist/album for verification).
• id is optional; we echo it back so you can map results without relying on order (results are also returned in input order).
• allow_title_fallback is a single top-level flag applied to every item (off by default; still gated on our side).
• Max 100 items per request; more returns a 400.

Response#

{
  "schema_version": "1.0",
  "results": [
    { "id": "row-1", "status": "ok", "result": { /* same shape as the single endpoint */ } },
    { "id": "row-2", "status": "not_found" },
    { "id": "row-3", "status": "invalid", "error": { "code": "INVALID_IDENTIFIER", "message": "...", "param": "isrc" } }
  ]
}

Each item carries a status of ok, not_found, invalid or source_unavailable. A not_found item carries hint when we can say why. It is the same text the single lookup gives, for a song code we do not cover or a stale copy of the Apple catalogue. A source_unavailable item is a temporary failure at the cover source, and its hint says to retry it. One bad item never fails the whole batch.

A not_found item that we refused for its title also carries refusal, title_near_miss or title_mismatch, as in the single lookup. Send a title_near_miss item to a person to check.

Retry only the items whose status is source_unavailable. The failure belongs to the cover source, not to the identifier, so all such items recover at the same time. Wait 60 seconds, then send one request with 1 to 5 of them as a check. When the check returns no source_unavailable, retry the rest. When it does not, double the wait, up to 5 minutes.

Do not resend full batches while the source is slow: each one holds connections that other lookups need.

Two reference sources reload once a week, and source_unavailable is more likely while they do:

• The Apple catalogue reloads on Sunday from 00
  UTC, for up to about 18 hours. It slows every lookup.
• The MLC data that links an ISWC or a song code to its recordings reloads at the weekend. The reload can end early on Monday UTC. It affects only iswc and external_id lookups, and an isrc lookup still answers.

An ok item's result is the full single-lookup body. It carries matched.confidence, verification and warnings, with the same meaning as on the single endpoint. Review an item before you publish it when its confidence is low or its warnings array is not empty. The batch response carries one x-request-id for all its items. Store it with each cover you keep.

The request itself returns 400 only for a malformed body, such as bad JSON or an empty or oversized items. It returns 401 or 403 for auth. It returns 503 only when the cover source is down for the whole request.

Rate limit: 120 batch requests/minute per key (each request already covers up to 100 assets).

curl -s -X POST -H "Authorization: Bearer $TRK_KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"id":"1","isrc":"USRC12345678"},{"id":"2","iswc":"T-123.456.789-0"}]}' \
  "https://ingest.takerecord.com/api/v1/metadata/lookups"