Skip to main content

Fetching Library Tracks

A library track describes an audio file that is analyzed with the available classifiers upon creation. Whenever we release or update a new model a library track can be reanalyzed. On our API the GraphQL type that describes the data that can be queried is called LibraryTrack.

A library track is automatically created by uploading a new audio file into your library on the Cyanite Web App Library View.

All those library tracks created via the web app, as well as those created via the API can be fetched via the API.

Empty Library?

In case no tracks were imported via the web app or the API before the library is empty. We recommend importing some tracks via the web app, for testing the GraphQL operations mentioned in this guide. The next guide will cover how library tracks can be imported via the API.

Fetching a paginated list of Library Tracks#

A paginated list of all LibraryTracks can be retrieved via the Query.libraryTracks field.

The Cyanite API uses cursor based pagination, which means that more items can be fetched by querying with the cursor of the last item of the previous page.

The Query.libraryTracks field will always return the library tracks sorted by creation date descending.

The first argument describes the amount of items that should be fetched. It is optional and cannot be set to any value higher than 50. If not provided the first value is automatically set to 50.

It is also possible to filter the library tracks by its title by using the LibraryTracksFilter.filter argument.

Fetching a library Track with a specific ID#

It is also possible to directly fetch a single LibraryTrack via the Query.libraryTrack field.

This is handy in a scenario where a system got notified by a webhook and data for that specific track should be retrieved.

The Query.libraryTracks field returns a GraphQL union type with the name LibraryTrackResult. The union describes the possible results that the field can return. In case a track with the given id does not exist in the library, a LibraryTrackNotFoundError is returned. Otherwise, the result will be a LibraryTrack.


The selection set on the GraphQL operation is quite small. We recommend selecting different fields for getting a better feel and overview of the available data.

Find library tracks with a specific file hash#

In huge libraries duplicates may occur. The Query.libraryTracks field allows searching for a specific track via the SHA256 hash of the audio file. This allows checking whether a track already exists within the library in order to avoid uploading duplicates.

Most platforms and programming languages come with utilities for computing SHA256 hashes from files.


$ sha256sum file.mp3
bf0c36fdcee7d808188e140c780dbe1c51a15fcf88c9280f928b16321702f3c2 file.mp3


$ openssl dgst -sha256 file.mp3


/** generateSHA256ForFilePath.mjs */
import * as crypto from "crypto";
import * as fs from "fs";
const generateSHA256ForFilePath = (filePath: string) =>
new Promise((resolve, reject) => {
const hash = crypto.createHash("sha256");
const stream = fs.createReadStream(filePath);
stream.on("data", (data) => {
stream.on("end", () => {
stream.on("error", (err) => {
// prints bf0c36fdcee7d808188e140c780dbe1c51a15fcf88c9280f928b16321702f3c2

Example Operation for searching tracks via SHA256 hash

query LibraryTracksFilteredBySHA256Query($sha256: String!) {
libraryTracks(filter: { sha256: $sha256 }) {
pageInfo {
edges {
node {

Further reading#

You can get a better overview over the GrapHQL fields and types in our generated schema documentation.

The next guide will cover how to upload new library tracks via the API.