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.

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. The last one is a transient per-item failure at the cover source. One bad item never fails the whole batch. Retry only the items whose status is source_unavailable, and wait before you do.

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"