Tracks

Individual songs with lyrics, metadata, and album associations

Resource Overview

Tracks represent individual songs within your music catalog. Each track contains detailed metadata including lyrics, duration, and explicit content flags, and can be associated with album.

Base Endpoint
/tracks
Resource Type
tracks
User Scope
Owner-restricted

Schema

Required Attributes

Field Type Validation Description
title string Required · up to 300 characters Track title
is-explicit boolean Required Explicit content flag
rights-owner-year integer Required · 1900 or later Rights ownership year
rights-owner-name string Required · up to 200 characters Rights owner name
order integer Required · 1 or greater · unique per album Track order within album
full-audiofile-url string Required, except for a music video · up to 500 characters Full audio file URL

Optional Attributes

Field Type Validation Description
isrc-code string Optional · up to 100 characters International Standard Recording Code
version-description string Optional · up to 200 characters Version as free text (e.g., "Radio Edit", "Extended"). Takes priority over version relationship — if set, version_id is cleared automatically.
length string Optional · time format Track duration (HH:MM:SS)
lyrics string Optional Track lyrics
preview-start integer Optional · 0 or greater Preview start time in seconds
is-video boolean Optional Marks the track as a music video. Changed only when sent. See Music Videos
video-content-type string Optional · music videos only · official, performance_live or performance_cover The kind of music video. See Spotify Videos
related-audio-isrc string Optional · music videos only · 12-character ISRC, different from the track's own isrc-code, of an audio track in your catalogue whose release was delivered and not taken down from Spotify. Check one first with POST /related-audio-check ISRC of the audio recording the video belongs to. Stored uppercase, without dashes
video-thumbnail string (URL) Optional · music videos only · JPEG or PNG, 16:9, at least 1920x1080, up to 15 MB URL of the video's thumbnail. The image is downloaded and stored; the response returns the stored copy's URL
extended-credits array Optional · up to 200 items Instrument and additional role credits, as a list of {role, name, artist-id, position} objects. Sending it replaces the track's full set; omitting it leaves the credits untouched. See Extended Credits
allow-fingerprint-scan boolean Optional · default true Whether the track is sent to fingerprint DSPs (YouTube Content ID, Meta and TikTok). Send false to opt this track out; omitting it on an update leaves it unchanged. Cannot be false on a music video.

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last update timestamp

Required Relationships

Relationship Related Resource Description
albums albums Album associations (at least one required)
primary-genre genres Primary genre classification
language languages Track language

Optional Relationships

Relationship Related Resource Description
secondary-genre genres Secondary genre classification
track-artists track-artists Artist associations with roles
version versions Version type reference (from predefined list). Alternative to version-description attribute.
artists artists Direct artist associations

Version: two ways to set it

  • • Free text: Use the version-description attribute to enter any version text (e.g., "Radio Edit", "Extended Mix").
  • • Predefined: Use the version relationship to select from the predefined versions list.
  • • If both are sent in the same request, free text takes priority and the version relationship is cleared automatically.
  • • If only the relationship is sent, the version text is auto-populated from the selected version name.

Read-only Relationships

Relationship Related Resource Description
user users Track owner (auto-assigned)
album-tracks album-tracks Album tracks

Extended Credits

The extended-credits attribute carries the credits of a track beyond the core artist roles: instruments and additional roles such as engineer or co-producer. It can be sent on POST /tracks and PATCH /tracks/{id}, and it is returned on every track read. Each credit can also be read as a track credit resource.

Item Shape

Member Type Validation Description
role string Required A key from credit roles (e.g., "violin")
name string Required · 1 to 255 characters Name of the credited person or entity
artist-id integer | null Optional · positive integer Optional. ID of one of your artists, for your own reference. Send a JSON number or null
position integer | null Optional · 1 or greater Order of the credit within its role

Write Rules

  • • Omitted: a PATCH without extended-credits leaves the track's credits untouched.
  • • Sent: the list replaces the track's full set of extended credits. Always send every credit you want to keep.
  • • Empty array: [] removes all extended credits. null is rejected.
  • • Positions: renumbered 1..n within each role, ordered by the position you send; items without one go last, in the order they appear in the list.
  • • Accepted roles: any role listed by GET /credit-roles. Core artist roles (e.g., producer, composer) are never accepted here; use track artists.
  • • Credits already on the track: a credit the track already has can be sent again unchanged even if its role is no longer listed in GET /credit-roles.
  • • Artist reference: artist-id must be one of your artists.
  • • No duplicates: the same name cannot appear twice under the same role (names compared case-insensitively), whatever the artist-id.
  • • All errors at once: every invalid item is reported in a single 422 response, and nothing is saved.

Validation Errors

Each error points at the offending item through source.pointer, using its index in the list starting at 0 (e.g., /data/attributes/extended-credits/0/role).

Error Response Example

422 Unprocessable Entity 
{
  "errors": [
    {
      "status": "422",
      "detail": "Unknown credit role \"guitarr\". See GET /credit-roles.",
      "source": { "pointer": "/data/attributes/extended-credits/0/role" }
    },
    {
      "status": "422",
      "detail": "The name is required and must be 1 to 255 characters.",
      "source": { "pointer": "/data/attributes/extended-credits/1/name" }
    }
  ]
}

Music Videos

is-video switches a track between a song and a music video. Its masters are managed through /track-assets.

  • • Changing the type: setting is-video to true removes the track's Dolby Atmos master and, when the track is not shared with other albums, its audio file reference (full-audiofile-url, md5); length is kept. Setting it back to false removes the video master.
  • • Clearing is-video is always allowed, except on a video release.
  • • Audio file: a music video needs no full-audiofile-url; every other track does. A release of any other format may mix songs and music videos.
  • • Video releases: every track of a release in the Video format is a music video. A track created on one without is-video is stored as a music video.

Spotify Videos

  • • Attributes: video-content-type, related-audio-isrc and video-thumbnail are accepted on music videos only; sending them for any other track answers 422. Only the values a request sends are checked.
  • • Store: the Spotify Videos DSP can only be added to a release of exactly one track, a music video, and not while another official video of the same related-audio-isrc is on that store.
  • • Before distribution, a release with that DSP needs: exactly one track, which is a music video; a video-content-type; a related-audio-isrc when the type is official, not already used by another official video on that store; a video-thumbnail; and a valid video master in ProRes 422 HQ (or H.264 Main/High, HEVC or AV1), up to 4096x2160, progressive, at 23.976, 24, 25, 29.97, 30, 50, 59.94 or 60 fps, with no subtitle or caption streams, and stereo AAC or PCM audio at 48 or 96 kHz. Otherwise the distribution request answers 422 listing what is missing.
  • • Error codes: every Spotify Videos error message ends with its code in brackets, for example Spotify Videos requires a video thumbnail. [spotify_video_thumbnail_missing].
Code When
invalid_video_content_typevideo-content-type is not one of the three values.
invalid_related_audio_isrcrelated-audio-isrc is not a valid ISRC.
related_audio_isrc_is_own_isrcrelated-audio-isrc is the video's own ISRC.
related_isrc_not_in_your_catalogNo audio track in your catalogue has that ISRC.
related_isrc_not_deliveredThe release holding that audio was not delivered.
related_isrc_taken_downEvery release holding that audio was taken down from Spotify.
video_thumbnail_format · video_thumbnail_too_heavy · video_thumbnail_too_small · video_thumbnail_ratioThe thumbnail is not a JPEG or PNG, is over 15 MB, is under 1920x1080, or is not 16:9.
video_thumbnail_upload_failedThe thumbnail could not be stored. Try again.
spotify_video_single_trackDistribution: the release is not exactly one music video.
spotify_video_type_missing · spotify_video_related_isrc_missing · spotify_video_thumbnail_missingDistribution: that attribute is missing.
spotify_video_related_isrc_already_has_official_videoAnother official video of the same audio is already on Spotify Videos.
spotify_video_master_not_prores_hqDistribution: no valid stored master, or a ProRes master that is not 422 HQ.
spotify_video_master_*Distribution: the master breaks one of the rules above; the suffix names which (for example spotify_video_master_frame_rate_not_accepted, spotify_video_master_audio_channels_not_accepted).
 
{
  "data": {
    "type": "related-audio-checks",
    "id": "ARAAA2600050",
    "attributes": {
      "ok": true,
      "track": {"title": "The Song", "artists": "Ana,Bea ft Cora"},
      "album": {"title": "The Single", "upc": "7798000000017"}
    }
  }
}

When it cannot be used: {"ok": false, "reason": "related_isrc_taken_down", "message": "..."}, with reason one of invalid_related_audio_isrc, related_isrc_not_in_your_catalog, related_isrc_not_delivered, related_isrc_taken_down.

Status Code When
403 video_read_only Creating, editing or deleting a track of a video album, by an account without music videos enabled.
403 video_not_allowed Sending is-video: true from an account without music videos enabled.
422 video_track_is_shared Turning into a video a track that belongs, or would belong, to more than one album. A track that is already a video can still be edited.
422 video_release_accepts_only_videos Sending is-video: false for a track of a video release, or adding a track that is not a music video to one through /album-tracks.

Error Response Example

403 Forbidden 
{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "code": "video_not_allowed",
      "detail": "This account is not enabled for music videos. Contact support to have it enabled."
    }
  ]
}

Related Endpoints

Endpoint Method Description Documentation
/tracks/{id}/trends GET Get performance trends for a track (plays by date, DSP, country, album) View Trends →
/track-credits?filter[track]={id} GET List a track's extended credits as individual resources (read-only) View Track Credits →
/credit-roles GET Catalog of role keys accepted in extended-credits View Credit Roles →

List Tracks

GET /tracks 
GET /tracks
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[title] - Filter by track title (partial match)
  • • filter[is-explicit] - Filter by explicit content flag (true/false)
  • • filter[order] - Filter by track order within album
  • • filter[rights-owner-year] - Filter by rights ownership year
  • • filter[primary-genre] - Filter by primary genre ID
  • • filter[isrc-code] - Filter by ISRC code (exact match)
  • • filter[album] - Filter by album ID to get all tracks from a specific album
  • • filter[created-at-gte] - Filter tracks created on or after date (YYYY-MM-DD)
  • • filter[created-at-lte] - Filter tracks created on or before date (YYYY-MM-DD)

Other Parameters

  • • include - Include relationships
  • • sort - Sort by field
  • • page[number] - Page number
  • • page[size] - Results per page

Example Request

GET /tracks?include=albums,primary-genre,language&filter[title]=City&sort=order

Success Response

200 OK 
{
  "data": [
    {
      "type": "tracks",
      "id": "1",
      "attributes": {
        "title": "City Lights",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Indie Music Co.",
        "order": 1,
        "isrc-code": "US-S1Z-99-00001",
        "version-description": "Original Mix",
        "length": "00:03:42",
        "lyrics": "Walking through the city lights tonight...",
        "preview-start": 30,
        "allow-fingerprint-scan": true,
        "publishing": "2024 Indie Music Co.",
        "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav",
        "created-at": "2024-08-01T10:00:00Z",
        "updated-at": "2024-08-15T14:30:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "1" }
          ]
        },
        "primary-genre": {
          "data": { "type": "genres", "id": "3" }
        },
        "language": {
          "data": { "type": "languages", "id": "1" }
        },
        "secondary-genre": {
          "data": { "type": "genres", "id": "8" }
        },
        "track-artists": {
          "data": [
            { "type": "track-artists", "id": "1" },
            { "type": "track-artists", "id": "2" }
          ]
        }
      }
    },
    {
      "type": "tracks",
      "id": "2",
      "attributes": {
        "title": "Midnight Drive",
        "is-explicit": false,
        "rights-owner-year": 2024,
        "rights-owner-name": "Indie Music Co.",
        "order": 2,
        "length": "00:04:15",
        "full-audiofile-url": "https://storage.example.com/tracks/midnight-drive.wav",
        "created-at": "2024-08-02T11:30:00Z",
        "updated-at": "2024-08-02T11:30:00Z"
      },
      "relationships": {
        "albums": {
          "data": [
            { "type": "albums", "id": "1" }
          ]
        },
        "primary-genre": {
          "data": { "type": "genres", "id": "3" }
        },
        "language": {
          "data": { "type": "languages", "id": "1" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "albums",
      "id": "1",
      "attributes": {
        "title": "Electric Dreams",
        "artwork": "https://storage.example.com/artwork/electric-dreams.jpg"
      }
    },
    {
      "type": "genres",
      "id": "3",
      "attributes": {
        "name": "Electronic"
      }
    },
    {
      "type": "languages",
      "id": "1",
      "attributes": {
        "name": "English",
        "code": "en"
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 12,
      "last-page": 1
    }
  }
}
POST /tracks

Create a new track with complete metadata and album associations.

Request Body

{
  "data": {
    "type": "tracks",
    "attributes": {
      "title": "City Lights",
      "is-explicit": false,
      "rights-owner-year": 2024,
      "rights-owner-name": "Indie Music Co.",
      "order": 1,
      "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav",
      "extended-credits": [
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 },
        { "role": "engineer", "name": "Studio X", "artist-id": 12 }
      ]
    },
    "relationships": {
      "albums": {
        "data": [
          {
            "type": "albums",
            "id": "1"
          }
        ]
      },
      "primary-genre": {
        "data": {
          "type": "genres",
          "id": "3"
        }
      },
      "language": {
        "data": {
          "type": "languages",
          "id": "1"
        }
      }
    }
  }
}

Required Fields

Attributes
  • • title - Track title (max 300 characters)
  • • is-explicit - Explicit content flag (boolean)
  • • rights-owner-year - Rights year
  • • rights-owner-name - Rights owner (max 200 characters)
  • • order - Track order in album (min 1, unique per album)
  • • full-audiofile-url - Audio file URL (max 500 characters)
Relationships
  • • albums - At least one album association required
  • • primary-genre - Primary genre classification
  • • language - Track language
GET /tracks/{id}

Retrieve a specific track with its complete information and relationships.

Example Response

200 OK 
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights",
      "is-explicit": false,
      "rights-owner-year": 2024,
      "rights-owner-name": "Indie Music Co.",
      "order": 1,
      "isrc-code": "US-S1Z-99-00001",
      "version-description": "Original Mix",
      "length": "00:03:42",
      "lyrics": "Walking through the city lights tonight...",
      "preview-start": 30,
      "publishing": "2024 Indie Music Co.",
      "full-audiofile-url": "https://storage.example.com/tracks/city-lights.wav",
      "extended-credits": [
        { "role": "engineer", "name": "Studio X", "artist-id": 12, "position": 1 },
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 }
      ],
      "created-at": "2024-08-01T10:00:00Z",
      "updated-at": "2024-08-15T14:30:00Z"
    },
    "relationships": {
      "albums": {
        "data": [
          { "type": "albums", "id": "1" }
        ]
      },
      "primary-genre": {
        "data": { "type": "genres", "id": "3" }
      },
      "language": {
        "data": { "type": "languages", "id": "1" }
      },
      "secondary-genre": {
        "data": { "type": "genres", "id": "8" }
      }
    }
  }

}

Include Parameters

Use the include parameter to load related resources:

?include=albums,primary-genre,language
?include=track-artists.artist,track-artists.artist-role
?include=albums.label,albums.artists
PATCH /tracks/{id}

Update specific attributes of an existing track.

Request Body Example - Update Title

{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights"
    }
  }
}

Success Response

200 OK

Other Update Examples

Update Relationships
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "title": "City Lights 2"
    },
    "relationships": {
      "secondary-genre": {
        "data": { "type": "genres", "id": "12" }
      }
    }
  }
}
Replace Extended Credits
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "extended-credits": [
        { "role": "violin", "name": "Ana Pérez", "artist-id": null, "position": 1 },
        { "role": "violin", "name": "Marc Duval", "position": 2 },
        { "role": "engineer", "name": "Studio X", "artist-id": 12 }
      ]
    }
  }
}
Remove All Extended Credits
{
  "data": {
    "type": "tracks",
    "id": "1",
    "attributes": {
      "extended-credits": []
    }
  }
}
DELETE /tracks/{id}

Remove a track from the system.

Key Features & Use Cases

Key Features

  • • Multi-album associations support
  • • Comprehensive metadata management
  • • Explicit content classification
  • • Track ordering within albums
  • • Rights ownership tracking
  • • Audio file URL management
  • • ISRC code support
  • • Lyrics and preview handling
  • • Instrument and role credits

Common Use Cases

  • • Adding songs to albums
  • • Managing track metadata and lyrics
  • • Handling compilation albums
  • • Organizing track sequences
  • • Content classification and rights
  • • Multi-format releases (Single + Album)
  • • Track version management
  • • Audio file quality control