Skip to content
Web APIReferences / Playlists / Get Playlist Items

Get Playlist Items

Get full details of the items of a playlist owned by a Spotify user.

Important policy notes
Authorization scopes

Request

  • playlist_id
    string
    Required

    The Spotify ID of the playlist.

    Example: 3cEYpjA9oz9GiPac4AsH4n
  • market
    string

    An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned.
    If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
    Note: If neither market or user country are provided, the content is considered unavailable for the client.
    Users can view the country that is associated with their account in the account settings.

    Example: market=ES
  • fields
    string

    Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit:
    fields=total,limit
    A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder:
    fields=items(added_at,added_by.id)
    Use multiple parentheses to drill down into nested objects, for example:
    fields=items(track(name,href,album(name,href)))
    Fields can be excluded by prefixing them with an exclamation mark, for example:
    fields=items.track.album(!external_urls,images)

    Example: fields=items(added_by.id,track(name,href,album(name,href)))
  • limit
    integer

    The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

    Default: limit=20Range: 0 - 50Example: limit=10
  • offset
    integer

    The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

    Default: offset=0Example: offset=5
  • additional_types
    string

    A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode.
    Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future.
    In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the type field of each object.

Response

Pages of tracks

  • href
    string
    Required

    A link to the Web API endpoint returning the full result of the request

    Example: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
  • limit
    integer
    Required

    The maximum number of items in the response (as set in the query or by default).

    Example: 20
  • next
    string
    Required
    Nullable

    URL to the next page of items. ( null if none)

    Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
  • offset
    integer
    Required

    The offset of the items returned (as set in the query or by default)

    Example: 0
  • previous
    string
    Required
    Nullable

    URL to the previous page of items. ( null if none)

    Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
  • total
    integer
    Required

    The total number of items available to return.

    Example: 4
  • Required
    • added_at
      string [date-time]

      The date and time the track or episode was added. Note: some very old playlists may return null in this field.

    • The Spotify user who added the track or episode. Note: some very old playlists may return null in this field.

      • Known public external URLs for this user.

      • Information about the followers of this user.

        • href
          string
          Nullable

          This will always be set to null, as the Web API does not support it at the moment.

        • total
          integer

          The total number of followers.

      • href
        string

        A link to the Web API endpoint for this user.

      • id
        string

        The Spotify user ID for this user.

      • type
        string

        The object type.

        Allowed values: "user"
      • uri
        string

        The Spotify URI for this user.

    • is_local
      boolean

      Whether this track or episode is a local file or not.

    • track
      oneOf

      Information about the track or episode.

      Will be one of the following:
        • The album on which the track appears. The album object includes a link in href to full information about the album.

          • album_type
            string
            Required

            The type of the album.

            Allowed values: "album", "single", "compilation"Example: "compilation"
          • total_tracks
            integer
            Required

            The number of tracks in the album.

            Example: 9
          • available_markets
            array of strings
            Required

            The markets in which the album is available: ISO 3166-1 alpha-2 country codes. NOTE: an album is considered available in a market when at least 1 of its tracks is available in that market.

            Example: ["CA","BR","IT"]
          • Required

            Known external URLs for this album.

          • href
            string
            Required

            A link to the Web API endpoint providing full details of the album.

          • id
            string
            Required

            The Spotify ID for the album.

            Example: "2up3OPMp9Tb4dAKM2erWXQ"
          • Required

            The cover art for the album in various sizes, widest first.

            • url
              string
              Required

              The source URL of the image.

              Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
            • height
              integer
              Required
              Nullable

              The image height in pixels.

              Example: 300
            • width
              integer
              Required
              Nullable

              The image width in pixels.

              Example: 300
          • name
            string
            Required

            The name of the album. In case of an album takedown, the value may be an empty string.

          • release_date
            string
            Required

            The date the album was first released.

            Example: "1981-12"
          • release_date_precision
            string
            Required

            The precision with which release_date value is known.

            Allowed values: "year", "month", "day"Example: "year"
          • Included in the response when a content restriction is applied.

            • reason
              string

              The reason for the restriction. Albums may be restricted if the content is not available in a given market, to the user's subscription type, or when the user's account is set to not play explicit content. Additional reasons may be added in the future.

              Allowed values: "market", "product", "explicit"
          • type
            string
            Required

            The object type.

            Allowed values: "album"
          • uri
            string
            Required

            The Spotify URI for the album.

            Example: "spotify:album:2up3OPMp9Tb4dAKM2erWXQ"
          • Required

            The artists of the album. Each artist object includes a link in href to more detailed information about the artist.

            • Known external URLs for this artist.

            • href
              string

              A link to the Web API endpoint providing full details of the artist.

            • id
              string

              The Spotify ID for the artist.

            • name
              string

              The name of the artist.

            • type
              string

              The object type.

              Allowed values: "artist"
            • uri
              string

              The Spotify URI for the artist.

        • The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.

          • Known external URLs for this artist.

          • Information about the followers of the artist.

            • href
              string
              Nullable

              This will always be set to null, as the Web API does not support it at the moment.

            • total
              integer

              The total number of followers.

          • genres
            array of strings

            A list of the genres the artist is associated with. If not yet classified, the array is empty.

            Example: ["Prog rock","Grunge"]
          • href
            string

            A link to the Web API endpoint providing full details of the artist.

          • id
            string

            The Spotify ID for the artist.

          • Images of the artist in various sizes, widest first.

            • url
              string
              Required

              The source URL of the image.

              Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
            • height
              integer
              Required
              Nullable

              The image height in pixels.

              Example: 300
            • width
              integer
              Required
              Nullable

              The image width in pixels.

              Example: 300
          • name
            string

            The name of the artist.

          • popularity
            integer

            The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist's popularity is calculated from the popularity of all the artist's tracks.

          • type
            string

            The object type.

            Allowed values: "artist"
          • uri
            string

            The Spotify URI for the artist.

        • available_markets
          array of strings

          A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.

        • disc_number
          integer

          The disc number (usually 1 unless the album consists of more than one disc).

        • duration_ms
          integer

          The track length in milliseconds.

        • explicit
          boolean

          Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown).

        • Known external IDs for the track.

        • Known external URLs for this track.

        • href
          string

          A link to the Web API endpoint providing full details of the track.

        • id
          string

          The Spotify ID for the track.

        • is_playable
          boolean

          Part of the response when Track Relinking is applied. If true, the track is playable in the given market. Otherwise false.

        • Part of the response when Track Relinking is applied, and the requested track has been replaced with different track. The track in the linked_from object contains information about the originally requested track.

          • Included in the response when a content restriction is applied.

            • reason
              string

              The reason for the restriction. Supported values:

              • market - The content item is not available in the given market.
              • product - The content item is not available for the user's subscription type.
              • explicit - The content item is explicit and the user's account is set to not play explicit content.

              Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

          • name
            string

            The name of the track.

          • popularity
            integer

            The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
            The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.
            Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note: the popularity value may lag actual popularity by a few days: the value is not updated in real time.

          • preview_url
            string
            Nullable

            A link to a 30 second preview (MP3 format) of the track. Can be null

            Important policy note
          • track_number
            integer

            The number of the track. If an album has several discs, the track number is the number on the specified disc.

          • type
            string

            The object type: "track".

            Allowed values: "track"
          • uri
            string

            The Spotify URI for the track.

          • is_local
            boolean

            Whether or not the track is from a local file.

          • audio_preview_url
            string
            Required
            Nullable

            A URL to a 30 second preview (MP3 format) of the episode. null if not available.

            Important policy note
            Example: "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17"
          • description
            string
            Required

            A description of the episode. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

            Example: "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us."
          • html_description
            string
            Required

            A description of the episode. This field may contain HTML tags.

            Example: "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>"
          • duration_ms
            integer
            Required

            The episode length in milliseconds.

            Example: 1686230
          • explicit
            boolean
            Required

            Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown).

          • Required

            External URLs for this episode.

          • href
            string
            Required

            A link to the Web API endpoint providing full details of the episode.

            Example: "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ"
          • id
            string
            Required

            The Spotify ID for the episode.

            Example: "5Xt5DXGzch68nYYamXrNxZ"
          • Required

            The cover art for the episode in various sizes, widest first.

            • url
              string
              Required

              The source URL of the image.

              Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
            • height
              integer
              Required
              Nullable

              The image height in pixels.

              Example: 300
            • width
              integer
              Required
              Nullable

              The image width in pixels.

              Example: 300
          • is_externally_hosted
            boolean
            Required

            True if the episode is hosted outside of Spotify's CDN.

          • is_playable
            boolean
            Required

            True if the episode is playable in the given market. Otherwise false.

          • language
            string
            Deprecated

            The language used in the episode, identified by a ISO 639 code. This field is deprecated and might be removed in the future. Please use the languages field instead.

            Example: "en"
          • languages
            array of strings
            Required

            A list of the languages used in the episode, identified by their ISO 639-1 code.

            Example: ["fr","en"]
          • name
            string
            Required

            The name of the episode.

            Example: "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators"
          • release_date
            string
            Required

            The date the episode was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".

            Example: "1981-12-15"
          • release_date_precision
            string
            Required

            The precision with which release_date value is known.

            Allowed values: "year", "month", "day"Example: "day"
          • Required

            The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.

            • fully_played
              boolean

              Whether or not the episode has been fully played by the user.

            • resume_position_ms
              integer

              The user's most recent position in the episode in milliseconds.

          • type
            string
            Required

            The object type.

            Allowed values: "episode"
          • uri
            string
            Required

            The Spotify URI for the episode.

            Example: "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr"
          • Included in the response when a content restriction is applied.

            • reason
              string

              The reason for the restriction. Supported values:

              • market - The content item is not available in the given market.
              • product - The content item is not available for the user's subscription type.
              • explicit - The content item is explicit and the user's account is set to not play explicit content.

              Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

          • Required

            The show on which the episode belongs.

            • available_markets
              array of strings
              Required

              A list of the countries in which the show can be played, identified by their ISO 3166-1 alpha-2 code.

            • Required

              The copyright statements of the show.

              • text
                string

                The copyright text for this content.

              • type
                string

                The type of copyright: C = the copyright, P = the sound recording (performance) copyright.

            • description
              string
              Required

              A description of the show. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

            • html_description
              string
              Required

              A description of the show. This field may contain HTML tags.

            • explicit
              boolean
              Required

              Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown).

            • Required

              External URLs for this show.

            • href
              string
              Required

              A link to the Web API endpoint providing full details of the show.

            • id
              string
              Required

              The Spotify ID for the show.

            • Required

              The cover art for the show in various sizes, widest first.

              • url
                string
                Required

                The source URL of the image.

                Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
              • height
                integer
                Required
                Nullable

                The image height in pixels.

                Example: 300
              • width
                integer
                Required
                Nullable

                The image width in pixels.

                Example: 300
            • is_externally_hosted
              boolean
              Required

              True if all of the shows episodes are hosted outside of Spotify's CDN. This field might be null in some cases.

            • languages
              array of strings
              Required

              A list of the languages used in the show, identified by their ISO 639 code.

            • media_type
              string
              Required

              The media type of the show.

            • name
              string
              Required

              The name of the episode.

            • publisher
              string
              Required

              The publisher of the show.

            • type
              string
              Required

              The object type.

              Allowed values: "show"
            • uri
              string
              Required

              The Spotify URI for the show.

            • total_episodes
              integer
              Required

              The total number of episodes in the show.