Skip to main content

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.

Public alpha (subject to change)

Search is currently a public alpha feature. The request and response shapes may change before general availability.

tip

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-key header, 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.


SearchStarting pointEndpoint
Search by PromptA text descriptionPOST /v1/library-tracks/prompt-search
Search by TrackOne track from your LibraryPOST /v1/library-tracks/{id}/similar-tracks
Search by TracksUp to 10 tracks from your LibraryPOST /v1/library-tracks/similarity-search
Search by External TracksA Spotify or YouTube linkPOST /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).
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();

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).
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();

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).
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();
note

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.

info

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

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();
note

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.

PlatformAccepted formats
Spotifyopen.spotify.com/track/{id}, also with /intl-xx/ or /embed/; spotify:track:{id}
YouTubeyoutube.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:

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();

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.

info

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.

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

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": {}
}
FieldDescription
itemsThe results, ordered best match first.
items[].scoreA 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.idThe track's Cyanite Library ID (libtr_...).
items[].track.titleThe track's title.
items[].track.externalIdYour own ID for the track, if provided at upload. May be null.
items[].segmentScoresOnly present when items.segmentScores is requested via expand. See Get segment scores and the SegmentScores schema.
pageInfoAlways an empty object.

Use the returned track.id to fetch full analysis for a result, for example its model outputs.

note

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​

StatusCauseWhat to do
401Missing or invalid API key, or Search by External Tracks isn't enabled.Check x-api-key, or contact Cyanite.
403The API key isn't permitted to use this endpoint.Contact Cyanite.
404Search 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.
422Invalid 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.
429Rate limit exceeded.Wait for retry-after seconds, see Rate limits.
500The 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, not bpm or BpmV2.Tag. Compare with the list of fields.
  • Tag values. They're camelCase, e.g. acousticGuitar or aMinor, 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​