Comprehensive Search

Comprehensive Search Endpoints

Comprehensive Search executes a fixed comparison profile composed of three distinct similarity alignment metrics:

Track-level alignment
Light-stem alignment (Vocals and Accompaniment separation)
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

Field	Type	Required For	Description
`search_type`	string	✅ all	”1:1”, “1:n”, or “m:n”.
`limit`	int		Max matches to return.
`verbose_output`	boolean		Detailed frame-by-frame similarities.
`query_url`	string	1:1, 1:n	blob_name of the query track.
`candidate_url`	string	1:1	blob_name of the candidate track.
`candidate_dataset_name`	string	1:n, m:n	Dataset name to search against.
`query_dataset_name`	string	m:n	The 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"
}

{
  "search_type": "1:n",
  "query_url": "dataset/987f6543-e21b-12d3-a456-426614174000_query.wav",
  "candidate_dataset_name": "my-reference-catalog",
  "limit": 3
}

{
  "search_type": "m:n",
  "query_dataset_name": "incoming-batch-01",
  "candidate_dataset_name": "reference-catalog",
  "limit": 3
}

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
  }
}

​Comprehensive Search Endpoints

​Request Body Fields

​Examples

​Response

Comprehensive Search Endpoints

Request Body Fields

Examples

Response