> ## Documentation Index
> Fetch the complete documentation index at: https://help.soundverse.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Comprehensive Search

> Queue a Comprehensive Search similarity search using baseline similarity alignments (Track, Light Stem, and Motif).

import React from 'react';

export const Method = ({ type, children }) => {
  const styles = {
    POST: {
      backgroundColor: "#16a34a",
      color: "white",
      padding: "3px 6px",
      borderRadius: "6px",
      fontSize: "0.85rem",
      fontWeight: "bold",
      display: "inline-block",
      marginRight: "8px"
    }
  };
  return <span style={styles[type] || styles.POST}>{children || type}</span>;
};

## **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:

* <Method type="POST">POST</Method> `/trace/v1/comprehensive1/type1` (Legacy)
* <Method type="POST">POST</Method> `/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**

<CodeGroup>
  ```json 1:1 Search theme={null}
  {
    "search_type": "1:1",
    "query_url": "dataset/987f6543-e21b-12d3-a456-426614174000_query.wav",
    "candidate_url": "dataset/123e4567-e89b-12d3-a456-426614174000_candidate.wav"
  }
  ```

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

  ```json M:N Search theme={null}
  {
    "search_type": "m:n",
    "query_dataset_name": "incoming-batch-01",
    "candidate_dataset_name": "reference-catalog",
    "limit": 3
  }
  ```
</CodeGroup>

***

### **Response**

**Status 202 Accepted**

```json theme={null}
{
  "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
  }
}
```