Skip to main content

​
Comprehensive Search Endpoints

Comprehensive Search executes a fixed comparison profile composed of three distinct similarity alignment metrics:
  1. Track-level alignment
  2. Light-stem alignment (Vocals and Accompaniment separation)
  3. Motif alignment (Micro-melodic motif detection on Vocals and Accompaniment/Other stems)
These endpoints return a job_id immediately. You must poll GET /trace/v1/comprehensive1/jobs/{job_id} to retrieve results. Two routing variants are available depending on the similarity model used:
  • /trace/v1/comprehensive1/type1 (Legacy)
  • /trace/v1/comprehensive1/type2 (New Efficient)

​
Request Body Fields

FieldTypeRequired ForDescription
search_typestring✅ all”1:1”, “1:n”, or “m:n”.
limitintMax matches to return.
verbose_outputbooleanDetailed frame-by-frame similarities.
query_urlstring1:1, 1:nblob_name of the query track.
candidate_urlstring1:1blob_name of the candidate track.
candidate_dataset_namestring1:n, m:nDataset name to search against.
query_dataset_namestringm:nThe query dataset name (for bulk matching).

​
Examples

{
  "search_type": "1:1",
  "query_url": "dataset/987f6543-e21b-12d3-a456-426614174000_query.wav",
  "candidate_url": "dataset/123e4567-e89b-12d3-a456-426614174000_candidate.wav"
}

​
Response

Status 202 Accepted 
{
  "success": true,
  "data": {
    "job_id": "search_job_f5g6h7j8-k9l0-1a2b-3c4d-5e6f7g8h9i0j",
    "status": "pending",
    "usecase_id": "comprehensive1",
    "search_type": "1:1",
    "n": 1,
    "m": 1,
    "cost_usd": 0.15
  }
}