Search
Search is the Cyanite product for finding tracks in your Library by how they sound. This guide shows you how to use each way to search, how to narrow the results with a metadata filter and how to read the results.
Search is currently a public alpha feature. The request and response shapes may change before general availability.
Want to know how search works, what the score means, which search to use when and how filters are applied? Read Understanding Search.
Prerequisites
- A Cyanite API key. All requests are authenticated with the
x-api-keyheader, exactly as in the Quick Start Guide. - At least one uploaded and analyzed track in your Library. Search only returns tracks that have finished analysis.
- Search by External Tracks only: the feature enabled for your account. Reach out to Cyanite to enable it.
All search requests accept a limit query parameter to control how many
results are returned (default 20). Search by Prompt and Search by Tracks
accept up to 500, Search by Track up to 50. The maximum drops to 30 when
requesting segment scores.
Choose a search
| Search | Starting point | Endpoint |
|---|---|---|
| Search by Prompt | A text description | POST /v1/library-tracks/prompt-search |
| Search by Track | One track from your Library | POST /v1/library-tracks/{id}/similar-tracks |
| Search by Tracks | Up to 10 tracks from your Library | POST /v1/library-tracks/similarity-search |
| Search by External Tracks | A Spotify or YouTube link | POST /v1/library-tracks/similarity-search |
Every search accepts a metadata filter, can return segment scores and returns the same response.
Search by Prompt
Describe what you're looking for in natural language, for example "an upbeat ska track with a fast tempo for a soft-drink ad", and receive the matching tracks from your Library, ordered by relevance.
POST https://rest-api.cyanite.ai/v1/library-tracks/prompt-search
API reference: Search by Prompt
The request body has one required field:
query: the natural-language description of the track you're looking for.metadataFilter(optional): restricts results to tracks matching structured criteria (see Filter by metadata).
- Typescript
- PHP
- Python
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
query:
"an upbeat ska track with a fast tempo for a soft-drink advertisement",
}),
},
);
const { items, pageInfo } = await response.json();
<?php
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post('https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20', [
'query' => 'an upbeat ska track with a fast tempo for a soft-drink advertisement',
]);
$result = $response->json();
import json
import os
import urllib.request
api_key = os.environ.get("CYANITE_API_KEY")
body = json.dumps({
"query": "an upbeat ska track with a fast tempo for a soft-drink advertisement",
}).encode("utf-8")
req = urllib.request.Request(
"https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20",
data=body,
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
Search by Track
Find the tracks in your Library that sound most similar to one track you
already have. The reference track is given as the {id} path parameter, and
results are ranked in descending order.
POST https://rest-api.cyanite.ai/v1/library-tracks/{id}/similar-tracks
API reference: Search by Track
{id}: the Library Track ID of the reference track (libtr_...).metadataFilter(optional, in the body): restricts the candidate results (see Filter by metadata).
- Typescript
- PHP
- Python
const trackId = "libtr_xxxxxxxxxxxxxxxxxxxxxx";
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/${trackId}/similar-tracks?limit=20`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
},
);
const { items, pageInfo } = await response.json();
<?php
use Illuminate\Support\Facades\Http;
$trackId = 'libtr_xxxxxxxxxxxxxxxxxxxxxx';
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post("https://rest-api.cyanite.ai/v1/library-tracks/{$trackId}/similar-tracks?limit=20", (object) []);
$result = $response->json();
import json
import os
import urllib.request
api_key = os.environ.get("CYANITE_API_KEY")
track_id = "libtr_xxxxxxxxxxxxxxxxxxxxxx"
req = urllib.request.Request(
f"https://rest-api.cyanite.ai/v1/library-tracks/{track_id}/similar-tracks?limit=20",
data=json.dumps({}).encode("utf-8"),
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
Search by Tracks
Blend up to 10 reference tracks into a single query, for example the tracks of a playlist or a moodboard of examples. Cyanite finds the tracks in your Library that match the common thread across all of them rather than any one track in particular (see how blending works).
POST https://rest-api.cyanite.ai/v1/library-tracks/similarity-search
API reference: Search by Tracks
tracks: an array of 1–10 reference tracks, each{ "id": "libtr_..." }. All tracks must belong to your account. Supplying a single track behaves the same as Search by Track. Instead of Library Tracks, the array can also hold a single Spotify or YouTube link,{ "url": "..." }. See Search by External Tracks.metadataFilter(optional): restricts the candidate results (see Filter by metadata).
- Typescript
- PHP
- Python
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
tracks: [
{ id: "libtr_xxxxxxxxxxxxxxxxxxxxxx" },
{ id: "libtr_yyyyyyyyyyyyyyyyyyyyyy" },
],
}),
},
);
const { items, pageInfo } = await response.json();
<?php
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post('https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20', [
'tracks' => [
['id' => 'libtr_xxxxxxxxxxxxxxxxxxxxxx'],
['id' => 'libtr_yyyyyyyyyyyyyyyyyyyyyy'],
],
]);
$result = $response->json();
import json
import os
import urllib.request
api_key = os.environ.get("CYANITE_API_KEY")
body = json.dumps({
"tracks": [
{"id": "libtr_xxxxxxxxxxxxxxxxxxxxxx"},
{"id": "libtr_yyyyyyyyyyyyyyyyyyyyyy"},
],
}).encode("utf-8")
req = urllib.request.Request(
"https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20",
data=body,
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
If a reference track doesn't belong to your account, or doesn't exist, the
request fails with a 404.
Search by External Tracks
Find the tracks in your Library that sound most similar to a track outside your Library, using its link as the reference. Currently, Spotify track and YouTube video links are supported. You don't need to upload the reference track to Cyanite. Typical uses are answering a brief like "something that sounds like this hit song" or finding a sound-alike from your catalogue for a temp track.
Search by External Tracks must be enabled for your account. Otherwise the
request fails with a 401. Reach out to Cyanite
to enable it.
How the reference is retrieved, what stays private and what "similar" means is explained in Understanding Search.
Send the Spotify track URL as the only reference in the tracks array of the
Search by Tracks endpoint:
POST https://rest-api.cyanite.ai/v1/library-tracks/similarity-search
API reference: Search by Tracks
- Typescript
- PHP
- Python
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
tracks: [
{ url: "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp" },
],
}),
},
);
const { items } = await response.json();
<?php
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post('https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20', [
'tracks' => [
['url' => 'https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp'],
],
]);
$result = $response->json();
import json
import os
import urllib.request
api_key = os.environ.get("CYANITE_API_KEY")
body = json.dumps({
"tracks": [
{"url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"},
],
}).encode("utf-8")
req = urllib.request.Request(
"https://rest-api.cyanite.ai/v1/library-tracks/similarity-search?limit=20",
data=body,
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
A search by a link can take longer than a search from your own tracks, because Cyanite first retrieves and analyzes the audio of the reference. Set your HTTP client's timeout accordingly.
Use a YouTube video instead
The request is the same for YouTube. Only the URL changes:
{
"tracks": [{ "url": "https://www.youtube.com/watch?v=XXXXXXXXXXX" }]
}
Metadata filters, segment scores and the response work exactly as for every other search. The reference track itself never appears in the results.
Supported links
| Platform | Accepted formats |
|---|---|
| Spotify | open.spotify.com/track/{id}, also with /intl-xx/ or /embed/; spotify:track:{id} |
| YouTube | youtube.com/watch?v={id}, youtu.be/{id}, /shorts/{id}, /embed/{id}, /live/{id} |
Query parameters such as ?si=... on Spotify links are ignored. Spotify
albums, playlists and artists, and YouTube playlists or channels are not
supported. Only a single track or video can be used as the reference.
Limitations
- A request can reference exactly one Spotify or YouTube link.
- A link can't be combined with Library Track references (
{ "id": "libtr_..." }) in the same request. To blend several of your own tracks, see Search by Tracks.
Filter by metadata
Add a metadataFilter to the request body of any search to only consider
tracks that also match structured criteria, for example "only between 120 and
140 BPM", "only rock or pop" or "no vocals". Omitting metadataFilter
applies no restriction.
A filter uses the track-level values of your tracks'
model outputs and your own customTags, so a track
can only match a condition on a model output it has. How filters are applied,
and why a filter can silently match nothing, is explained in
Understanding Search.
Add a filter to a search request
Each key of metadataFilter is a field,
written as <ModelVersion>.<field>, and each value is a condition with an
operator. This Search by Prompt only
returns tracks between 120 and 140 BPM:
- Typescript
- PHP
- Python
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "energetic workout music",
metadataFilter: {
"BpmV2.tag": { $gte: 120, $lte: 140 },
},
}),
},
);
const { items } = await response.json();
<?php
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post('https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20', [
'query' => 'energetic workout music',
'metadataFilter' => [
'BpmV2.tag' => ['$gte' => 120, '$lte' => 140],
],
]);
$result = $response->json();
import json
import os
import urllib.request
api_key = os.environ.get("CYANITE_API_KEY")
body = json.dumps({
"query": "energetic workout music",
"metadataFilter": {"BpmV2.tag": {"$gte": 120, "$lte": 140}},
}).encode("utf-8")
req = urllib.request.Request(
"https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?limit=20",
data=body,
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
The same metadataFilter object works in the body of every other search. The
examples below only show the metadataFilter object.
Filter by a number range
Combine $gte/$gt and $lte/$lt on a numeric field. Tracks produced
between 1980 and 1989:
{
"MusicalEraV2.estimatedProductionYear": { "$gte": 1980, "$lte": 1989 }
}
Tracks shorter than two minutes:
{
"AudioFileInfoV1.duration": { "$lt": 120 }
}
Filter by one of several values
Use $in to match any of the listed values. On tag lists such as
MainGenreV2.tags, a track matches if it has at least one of them. Rock or
pop tracks:
{
"MainGenreV2.tags": { "$in": ["rock", "pop"] }
}
Tracks in A minor or C major:
{
"KeyV2.tag": { "$in": ["aMinor", "cMajor"] }
}
Tag values are camelCase and must match the taxonomy exactly. Look them up in the vocabularies linked from the list of fields.
Exclude values
Use $nin to exclude tracks that have any of the listed values. No sad or
dark tracks:
{
"MoodSimpleV2.tags": { "$nin": ["sad", "dark"] }
}
Use $eq with false on a boolean field. Only tracks that aren't predicted to
be AI-generated:
{
"AiMusicDetectionV1.isAiMusic": { "$eq": false }
}
Require several tags
$in matches tracks with any of the values. To require all of them,
add one $in condition per value and combine them with $and. Tracks with both
piano and strings:
{
"$and": [
{ "InstrumentsV2.tags": { "$in": ["piano"] } },
{ "InstrumentsV2.tags": { "$in": ["strings"] } }
]
}
Combine conditions
Conditions on different fields in the same object must all match. Energetic tracks between 120 and 140 BPM:
{
"BpmV2.tag": { "$gte": 120, "$lte": 140 },
"MoodSimpleV2.tags": { "$in": ["energetic"] }
}
Use $or when at least one condition must match. Tracks that are fast or have
a high energy level:
{
"$or": [
{ "TempoV1.tag": { "$eq": "fast" } },
{ "ValenceArousalV2.energyLevel": { "$eq": "high" } }
]
}
$and and $or can be nested. Instrumental electronic or ambient tracks:
{
"$and": [
{ "VocalsV2.tags": { "$in": ["instrumental"] } },
{
"$or": [
{ "MainGenreV2.tags": { "$in": ["electronic"] } },
{ "MainGenreV2.tags": { "$in": ["ambient"] } }
]
}
]
}
Only use confident values
BPM, key and time signature come with a confidence. To only consider tracks
where the BPM is clear and steady, add a condition on
BpmV2.confidences.confidence:
{
"BpmV2.tag": { "$gte": 120, "$lte": 140 },
"BpmV2.confidences.confidence": { "$gte": 0.9 }
}
See Understanding Model Outputs for what the confidence means.
Filter by your own tags
customTags holds the custom tags you set when you create or update a Library
Track. Tracks you tagged as summer-campaign:
{
"customTags": { "$in": ["summer-campaign"] }
}
Custom tags match exactly, including case.
Get segment scores
To also learn where in each track the match is strongest, opt into segment
scores with the expand query parameter:
?expand[]=items.segmentScores
This works on every search endpoint. When requested, each result
gains a segmentScores.topScoringSegments array: the highest-scoring time
windows of the track, most relevant first, each with a startTime and
endTime in seconds. This is useful for jumping straight to the matching part
of a track in a preview player instead of playing from the start.
Requesting items.segmentScores caps limit at 30. Pass a higher limit alongside it and the request fails with a 422.
If you need more than one expansion in the future, repeat the key
(?expand[]=items.segmentScores&expand[]=...). A bare, unbracketed
?expand=items.segmentScores is also accepted. Build the query string with
your HTTP client's helper (URLSearchParams.append, urlencode with a list of
tuples, etc.) rather than a literal template string, so it's serialized
correctly.
- Typescript
- PHP
- Python
const params = new URLSearchParams({ limit: "20" });
params.append("expand[]", "items.segmentScores");
const response = await fetch(
`https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?${params}`,
{
method: "POST",
headers: {
"x-api-key": process.env.CYANITE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "an upbeat ska track with a fast tempo for a soft-drink advertisement",
}),
},
);
const { items, pageInfo } = await response.json();
// items[0].segmentScores.topScoringSegments
<?php
use Illuminate\Support\Facades\Http;
// http_build_query() turns an array into indexed keys (expand[0]=...),
// so pass the single expansion as the bare `expand` parameter
$query = http_build_query([
'limit' => 20,
'expand' => 'items.segmentScores',
]);
$response = Http::withHeaders([
'x-api-key' => env('CYANITE_API_KEY'),
])->post("https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?{$query}", [
'query' => 'an upbeat ska track with a fast tempo for a soft-drink advertisement',
]);
$items = $response->json('items');
// $items[0]['segmentScores']['topScoringSegments']
import json
import os
import urllib.request
from urllib.parse import urlencode
api_key = os.environ.get("CYANITE_API_KEY")
query = urlencode([("limit", "20"), ("expand[]", "items.segmentScores")])
body = json.dumps({
"query": "an upbeat ska track with a fast tempo for a soft-drink advertisement",
}).encode("utf-8")
req = urllib.request.Request(
f"https://rest-api.cyanite.ai/v1/library-tracks/prompt-search?{query}",
data=body,
headers={
"x-api-key": api_key,
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req) as response:
result = json.loads(response.read().decode("utf-8"))
Example result with segment scores expanded:
{
"score": 0.87,
"track": {
"id": "libtr_01KFGMPCN97HQYHQR6",
"title": "Summer Vibes",
"externalId": "my-track-123"
},
"segmentScores": {
"topScoringSegments": [
{ "startTime": 10, "endTime": 15, "score": 0.92 },
{ "startTime": 45, "endTime": 50, "score": 0.81 }
]
}
}
Read the results
All search endpoints share the same response shape, a list of scored results ordered best match first:
API reference: LibraryTrackListScoredSearchResponse
{
"items": [
{
"score": 0.87,
"track": {
"id": "libtr_01KFGMPCN97HQYHQR6",
"title": "Summer Vibes",
"externalId": "my-track-123"
}
}
],
"pageInfo": {}
}
| Field | Description |
|---|---|
items | The results, ordered best match first. |
items[].score | A number between 0 and 1 for the quality of the match: relevance to your text for Search by Prompt, similarity to the reference track(s) for the other searches. |
items[].track.id | The track's Cyanite Library ID (libtr_...). |
items[].track.title | The track's title. |
items[].track.externalId | Your own ID for the track, if provided at upload. May be null. |
items[].segmentScores | Only present when items.segmentScores is requested via expand. See Get segment scores and the SegmentScores schema. |
pageInfo | Always an empty object. |
Use the returned track.id to fetch full analysis for a result, for example
its model outputs.
These endpoints don't support pagination: pageInfo is always
{}, and there's no parameter to request a further page. Use limit to
control how many results you get back from a single call.
Troubleshooting
| Status | Cause | What to do |
|---|---|---|
401 | Missing or invalid API key, or Search by External Tracks isn't enabled. | Check x-api-key, or contact Cyanite. |
403 | The API key isn't permitted to use this endpoint. | Contact Cyanite. |
404 | Search by Track(s) only: a reference track isn't in your account, or a link's audio couldn't be retrieved. | Check the reference track IDs or the link. |
422 | Invalid input, for example an empty query, a metadataFilter that isn't a JSON object, an invalid reference, an unsupported or more than one Spotify/YouTube link, a link mixed with Library Tracks, or limit above 30 with segment scores. | The error's detail explains the cause. |
429 | Rate limit exceeded. | Wait for retry-after seconds, see Rate limits. |
500 | The metadataFilter uses an operator that isn't supported. | Use only the supported operators. |
Filter returns no results
A filter that doesn't match any track returns an empty or unexpectedly short
items list instead of an error. Check:
- Field names. They're case-sensitive and include the version, e.g.
BpmV2.tag, notbpmorBpmV2.Tag. Compare with the list of fields. - Tag values. They're camelCase, e.g.
acousticGuitaroraMinor, and must exist in the taxonomy of that model output. - Value types. A value must have the type of the field. A number sent as
a string, like
{ "BpmV2.tag": { "$eq": "120" } }, and a range on a text field, like{ "KeyV2.tag": { "$gte": 5 } }, match no track. - Too strict. Remove conditions one by one to find the one that excludes everything.
- Missing model outputs. A track only matches a condition on a model output it has. See Missing fields.
A 422 means metadataFilter isn't a JSON object, for example a JSON-encoded
string or an array. A 500 means the filter uses an operator that isn't
supported, such as $regex, $not or $all, or a range operator with a text
value, like { "$gte": "120" }. Send numbers as JSON numbers.
Next steps
- Understanding Search: how the searches work, how filters are applied and how to interpret the results.
- Fields and operators: everything a metadata filter can use.
- See the full request and response schemas in the API Reference: Search by Prompt, Search by Track and Search by Tracks.