Spotify

1. Overview

Spotify is a world-renowned digital music, podcast, and video streaming service that gives you access to millions of songs and other content from creators all over the world.

The GoInsight Spotify node allows you to integrate Spotify's vast music library and playback controls directly into your automated workflows. You can manage user libraries, control playback on connected devices, and search for content across Spotify's entire catalog. Key capabilities include:

• Playlist Management: Create new playlists, add or remove tracks, and retrieve playlist details.
• Music Discovery: Search for tracks, albums, artists, and playlists based on keywords.
• Library Access: Get a user's saved tracks, followed artists, and recently played songs.
• Playback Control: Start, stop, pause, and skip tracks, as well as control volume and transfer playback between devices (requires Spotify Premium).

2. Prerequisites

Before using this node, you will need to have a valid Spotify account. Please note that many playback control operations, such as starting or pausing playback, require an active Spotify Premium subscription.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Album, Artist, Playback, Playlist, Track, and User.

Operation Details

Get Album Tracks

This tool retrieves catalog information about an album's tracks, with optional pagination and market filtering.

Input Parameters:

• AlbumId: The Spotify ID of the album. Obtain from: (1) Search Album action response field Id, (2) album URL https://open.spotify.com/album/{AlbumId}. Format: 22-character Base62 string. Example: 4aawyAB9vmqN3uQ7FjRGTy

Options:

• Market: Country code to filter tracks available in that market (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return tracks from all markets. Example: US
• Limit: Maximum number of items to return per page. Valid range: 1-50, default 20. Example: 20
• Offset: The index of the first item to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.

Output:

• Tracks (object-array): Array of track objects. Each object contains: Id (string, track ID), Name (string, track name), TrackNumber (number, position in album), DurationMs (number, duration in ms), Explicit (boolean, explicit content flag), Artists (array of {Id, Name, Uri}), Uri (string, spotify:track:{id}), ExternalUrls (object, {spotify: url}).
• Total (number): Total number of tracks in the album
• Limit (number): Maximum number of items returned
• Offset (number): Index of the first item returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get an Album

This tool retrieves detailed information about a specific Spotify album, including its tracks, artists, and metadata.

Input Parameters:

• AlbumId: The Spotify album ID. Obtain from: Search Albums action (AlbumId field), or the Spotify album URL after '/album/'. Example: 4aawyAB9vmqN3uQ7FjRGTy (from https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy)

Options:

• Market: Country code to filter album availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return globally available content. Example: US

Output:

• AlbumId (string): The Spotify album ID of the requested album. Format: 22-character alphanumeric string. Example: 4aawyAB9vmqN3uQ7FjRGTy
• AlbumName (string): Album name
• AlbumType (string): Album type (album, single, compilation)
• ReleaseDate (string): Album release date
• TotalTracks (number): Total number of tracks in the album
• Artists (object-array): Array of album artist objects. Each object contains: Id (string, Spotify artist ID), Name (string, artist name), Type (string, typically 'artist'), Uri (string, spotify:artist:{id}).
• Images (object-array): Array of album cover image objects, sorted by resolution descending. Each object contains: Url (string, image URL), Height (number, pixels), Width (number, pixels).
• ExternalUrls (object): External URLs object. Contains: spotify (string, Spotify web player link for the album).
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get User Albums

Get a list of the albums saved in the current Spotify user's 'Your Music' library with pagination support.

Options:

• Limit: The maximum number of albums to return, default 20, minimum 1, maximum 50
• Offset: The index of the first album to return, default 0
• Market: Optional ISO 3166-1 alpha-2 country code to filter albums available in that market

Output:

• Albums (object-array): Array of saved album objects. Each object contains: Id (string, Spotify album ID), Name (string, album title), Artists (array of {Id, Name, ExternalUrls}), ReleaseDate (string, YYYY-MM-DD), TotalTracks (number, total track count), AlbumType (string, album/single/compilation), ExternalUrls (object, {spotify: url}), Images (array of {Url, Height, Width}), AddedAt (string, ISO 8601 timestamp when saved to library).
• Total (number): Total number of albums available
• Limit (number): Maximum number of albums returned in this request
• Offset (number): The offset used for this request
• Next (string): URL to the next page of results
• Previous (string): URL to the previous page of results
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Search Album

This tool searches for albums on Spotify using keywords, with optional market filtering and pagination.

Input Parameters:

• Query: Search keywords for albums. Supports album name, artist name, or combined search. Multiple words narrow results. Example: 'Global Warming Pitbull' or 'Abbey Road'

Options:

• Market: Country code to filter album availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return albums from all markets. Example: US
• Limit: Maximum number of items to return per page. Valid range: 1-50, default 20. Example: 20
• Offset: The index of the first item to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.

Output:

• Albums (object-array): Array of album objects matching the search query. Each object contains: Id (string, Spotify album ID), Name (string, album title), AlbumType (string, album/single/compilation), ReleaseDate (string, release date), TotalTracks (number, total track count), Artists (array of {Id, Name}), Images (array of {Url, Height, Width}, sorted by resolution descending), ExternalUrls ({spotify: web player link}), Uri (string, spotify:album:{id}).
• Total (number): Total number of albums matching the search
• Limit (number): Maximum number of items returned
• Offset (number): Index of the first item returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Following Artists

This tool retrieves the list of artists that the current user is following on Spotify, with cursor-based pagination.

Options:

• Limit: Maximum number of artists to return in one request. Valid range: 1-50. Default: 20. If the total number of followed artists exceeds this limit, use the After parameter to retrieve subsequent pages.
• After: Pagination cursor (artist ID). Leave empty for the first request. For subsequent pages, use the value from the Next field in the previous response. This enables cursor-based pagination to retrieve all followed artists.

Output:

• Artists (object-array): Array of followed artist information objects. Each object contains: Id (string, Spotify artist ID), Name (string, artist name), Genres (array of strings, music genres), Popularity (number, 0-100), Followers (number, total follower count), Images (array of {Url, Height, Width}), ExternalUrls ({spotify: url}), Uri (string, spotify:artist:{id}).
• Total (number): Total number of artists the user is following
• Limit (number): Maximum number of items returned
• Next (string): Cursor for retrieving the next page of results
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Search Artist

This tool searches for artists on Spotify using keywords, with optional market filtering and pagination support.

Input Parameters:

• Query: Search keywords for artists. Use the artist's name or partial name. Multiple words narrow results. Example: 'Pharrell Williams' or 'The Beatles'

Options:

• Market: Country code to filter artist availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return artists from all markets. Example: US
• Limit: Maximum number of items to return per page. Valid range: 1-50, default 20. Example: 20
• Offset: The index of the first item to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.

Output:

• Artists (object-array): Array of artist objects matching the search query. Each object contains: Id (string, Spotify artist ID), Name (string, artist name), Genres (array of strings, music genres), Popularity (number, 0-100), Followers (number, total follower count), Images (array of {Url, Height, Width}, sorted by resolution descending), ExternalUrls ({spotify: web player link}), Uri (string, spotify:artist:{id}).
• Total (number): Total number of artists matching the search
• Limit (number): Maximum number of items returned
• Offset (number): Index of the first item returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Add Song to Queue

This tool adds a track to the end of the user's current playback queue on Spotify.

Input Parameters:

• TrackUri: The Spotify URI of the track to add. Format: spotify:track:{track_id}. Obtain from: (1) Search Track action response field uri, (2) track URL https://open.spotify.com/track/{track_id} → URI spotify:track:{track_id}, (3) Spotify app: right-click track → Share → Copy Spotify URI. Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the current active device. Obtain device IDs from the Get Available Devices action response field id. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Available Devices

This tool retrieves the list of devices (smartphones, computers, smart speakers, TVs, etc.) registered to the user's Spotify account that are available for remote playback control. Use the returned device Id values with Start or Resume Playback and Transfer Playback actions to control which device plays music.

Output:

• Devices (object-array): Array of available Spotify playback devices. Each device object contains: Id (string, unique device identifier used for playback control), Name (string, device display name), Type (string, device type), IsActive (boolean), IsRestricted (boolean, whether Spotify blocks Web API playback control on this device), IsPrivateSession (boolean, whether the device is currently in a private session), VolumePercent (number), SupportsVolume (boolean).
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Current Playing Tracks

This tool retrieves information about the user's currently playing track, including playback state, device, and track details.

Options:

• Market: Country code to filter track availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to use the default market linked to the user's account. Example: US

Output:

• IsPlaying (bool): Whether a track is currently playing
• CurrentTrack (object): Current track details. Contains: Id (string, track ID), Name (string, track name), DurationMs (number, total duration in ms), Explicit (boolean), Popularity (number, 0-100), Artists (array of {Id, Name}), Album ({Id, Name, ReleaseDate, Images}), ExternalUrls ({spotify: url}), Uri (string, spotify:track:{id}). Empty object {} if nothing is playing.
• Device (object): Active playback device details. Contains: Id (string, device ID), Name (string, device name), Type (string, computer/smartphone/speaker), IsActive (boolean), VolumePercent (number, 0-100). Empty object {} if nothing is playing.
• ProgressMs (number): Current playback position in milliseconds
• ShuffleState (bool): Whether shuffle is enabled
• RepeatState (string): Repeat mode: off=no repeat, track=repeat current track (single loop), context=repeat current playlist or album (list loop).
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Recently Played Tracks

Retrieve the user's recently played tracks with optional time-based filtering.

Options:

• Limit: Maximum number of items to return (1-50)
• After: Unix timestamp in milliseconds to filter playback history (optional). Returns tracks played after this time. Set to 0 to disable. Cannot be used simultaneously with Before. Example: 1609459200000 (represents 2021-01-01)
• Before: Unix timestamp in milliseconds to filter playback history (optional). Returns tracks played before this time. Set to 0 to disable. Cannot be used simultaneously with After. Example: 1735689600000 (represents 2025-01-01)

Output:

• Tracks (object-array): Array of recently played track objects. Each object contains: Id (string, Spotify track ID), Name (string, track title), DurationMs (number, length in ms), Explicit (boolean), Popularity (number, 0-100), Artists (array of {Id, Name}), Album ({Id, Name, ReleaseDate, Images: [{Url, Height, Width}]}), PlayedAt (string, ISO 8601 timestamp of when track was played), ExternalUrls (object, {spotify: url}), Uri (string, spotify:track:{id}).
• Total (number): Number of tracks returned
• Limit (number): Maximum number of items returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Next Song

This tool skips to the next track in the user's playback queue (the list of upcoming songs) on Spotify. Requires a Spotify Premium subscription — free users will receive a 403 Forbidden error. Note: the current track's playback progress will be lost after skipping.

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the currently active device (requires at least one Spotify client to be open). If no active device exists and DeviceId is empty, a 404 error ('No active device found') will be returned. Obtain device IDs from the Get Available Devices (spotify_get_available_devices) action — each device object in the Devices array contains an Id field. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string ('') when the operation succeeded. Common errors: 'API Error (404): No active device found' (no Spotify client is open), 'API Error (404): Device not found' (invalid DeviceId), 'API Error (403): Premium required' (free user account).

Pause Playback

This tool pauses the user's current playback on their active device or a specified device. Requires a Spotify Premium subscription. Free users will receive a 403 Forbidden error (ErrorMessage will contain 'Premium required'). If DeviceId is not specified, the pause affects the currently active device.

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to pause the current active device. Obtain device IDs from the Get Available Devices (spotify_get_available_devices) action — each device object in the Devices array contains an Id field. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Previous Song

This tool skips to the previous track in the user's playback queue on Spotify.

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the current active device. Obtain device IDs from the Get Available Devices action response field Id. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Set Volume

This tool sets the playback volume for the user's current or specified Spotify device.

Input Parameters:

• VolumePercent: The volume level to set as a percentage. Range: 0-100. 0=mute (silent), 100=maximum volume. Example: 50 (half volume)

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the currently active device. Obtain device IDs from the Get Available Devices action response field Id. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Start or Resume Playback

This tool starts a new context or resumes the current playback on the user's active device. Requires a Spotify Premium subscription.

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the currently active device. Obtain device IDs from the Get Available Devices action (Id field). Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e
• ContextUri: Spotify URI of the context to play (optional). Supports albums, artists, or playlists. Mutually exclusive with Uris — provide one or the other, not both. Obtain from: Get an Album (Uri field), Get an Artist, Get a Playlist (Uri field). Format: spotify:{type}:{id}. Example: spotify:album:4aawyAB9vmqN3uQ7FjRGTy
• Uris: Comma-separated list of Spotify track URIs to play (optional). Mutually exclusive with ContextUri — provide one or the other, not both. Obtain URIs from: Search Track action (Uri field), Get Playlist Items action (Uri field). Format: spotify:track:{id}. Example: spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M
• PositionMs: Position to start playback from, in milliseconds (optional). Set to 0 to start from the beginning. Useful for resuming a track at a specific timestamp. Example: 30000 starts playback at 30 seconds in.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Toggle Playback Shuffle

This tool toggles shuffle on or off for a user's playback. Requires a Spotify Premium subscription. Side effects: the change takes effect immediately on the active playback session and affects the order of upcoming tracks in the queue. It does not pause, resume, or skip the current track. If no active device is available, the request may fail with a device-related error.

Input Parameters:

• State: The shuffle state to set: true to enable shuffle, false to disable shuffle. This parameter is required — the action will fail with a validation error if not provided. Example: true

Options:

• DeviceId: The ID of the target playback device (optional). Leave empty to use the currently active device. Obtain device IDs from the Get Available Devices action response field Id. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e

Output:

• ShuffleState (bool): Echo of the input parameter State (not retrieved from Spotify API). Spotify returns 204 No Content for this operation, so this field reflects the requested shuffle state only. To verify the actual live player state, call Get Current Playing Tracks or another playback status action after this request.
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed. Empty string indicates success. Non-empty values usually follow the format 'API Error (status): message'. Common errors include 'API Error (401): The access token expired', 'API Error (403): Premium required', and 'API Error (404): Device not found'.

Transfer Playback

This tool transfers playback to a different device, including Google Cast devices (e.g., Chromecast, Google Home). Requires a Spotify Premium subscription.

Input Parameters:

• DeviceId: Target device ID to transfer playback to (from Get_Available_Devices)

Options:

• Play: Whether to start playing immediately after transfer, default true

Output:

• DeviceId (string): The device ID that playback was transferred to. Format: 40-character alphanumeric string. Example: 5fbb3ba6aa454b5534c4ba43a8c7e8e45a63ad0e
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Add Items to Playlist

This tool adds one or more items to a user's playlist on Spotify at a specified position. Common use cases: (1) add newly discovered tracks to a personal playlist, (2) bulk import songs or podcast episodes from search results, (3) insert items at a specific position to reorder a playlist. Related actions: use Get Current User Playlists or Search Playlist to find playlist IDs; use Search Track or Get Playlist Items to find item URIs; use Remove Playlist Items to remove items.

Input Parameters:

• PlaylistId: The Spotify ID of the playlist. Obtain from: (1) playlist URL https://open.spotify.com/playlist/{PlaylistId}, (2) Get Current User Playlists or Search Playlist action response field id.
• ItemUris: One or more Spotify item identifiers (URIs) to add, comma-separated. Each URI is the unique ID of a track or episode and must follow the format spotify:track:{track_id} or spotify:episode:{episode_id}. Supports both English comma (,) and Chinese comma (，). Max 100 items per request.

Options:

• Position: The position to insert the items. 0 (default) = append to the end of the playlist.

Output:

• SnapshotId (string): The snapshot ID of the playlist after the operation. This is the current playlist version after items were added. Use it to detect whether the playlist changed later, especially in collaborative or multi-step automation scenarios.
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Create a Playlist

⚠️ Risk Level: Medium. This action creates a new playlist immediately when Confirm=true. Side effects: a new playlist is added to the target account; public playlists may appear on the user's profile and in Spotify search results, and followers may see the new playlist depending on their notification settings. Use Public=false for private playlists. If Collaborative=true, Spotify requires the playlist to be private (Public=false).

Input Parameters:

• Name: The name for the new playlist. Maximum length: 100 characters. Supports emojis and special characters. Example: My Favorite Tracks 2024

Options:

• Description: The playlist description (optional). Maximum length: 300 characters. Plain text only, no HTML or Markdown. Example: A personal collection of favorite songs from 2024
• Public: Whether the playlist should be public (true) or private (false). Public playlists are visible to all Spotify users and may appear in search results. Private playlists are only visible to you and users you explicitly share them with. Default: true
• Collaborative: Whether the playlist should allow collaborative editing by other users you share it with. Collaborative playlists let invited collaborators add, remove, and reorder tracks. Spotify requires collaborative playlists to be private, so set Public=false when Collaborative=true. Default: false
• Confirm: Safety gate for playlist creation. Must be set to true to execute this create action. This helps prevent accidental playlist creation in automated workflows. Example: true

Output:

• PlaylistId (string): The Spotify ID of the newly created playlist
• PlaylistName (string): The name of the playlist
• PlaylistUrl (string): The external Spotify URL for the playlist
• SnapshotId (string): A version identifier for the playlist used to track changes. Format: Base64-encoded string representing the playlist version. Required when modifying the playlist (e.g., adding/removing tracks) to ensure you're working with the latest version. Example: JbtmHBDBAYu3/bt8BOXKjzKx3i0b6LCa/wVjyl6qQ2Yf6nFXkbmzuEa+ZI/U1yF+
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if playlist creation failed. Empty string indicates success. Common validation errors include missing Confirm=true and invalid Public/Collaborative combinations.

Get a Playlist

Get detailed information about a Spotify playlist including metadata, owner information, and track count.

Input Parameters:

• PlaylistId: The Spotify playlist ID. Obtain from: Search Playlists action (PlaylistId field), or the Spotify playlist URL after '/playlist/'. Example: 37i9dQZF1DXcBWIGoYBM5M (from https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M)

Options:

• Market: Country code to filter track availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Affects which tracks are shown as available based on regional licensing. Leave empty to use the default market. Example: US

Output:

• PlaylistId (string): The Spotify ID of the playlist
• PlaylistName (string): The name of the playlist
• PlaylistDescription (string): The playlist description
• PlaylistUrl (string): The external Spotify URL for the playlist
• Owner (object): Playlist owner information object. Contains: display_name (string, owner's display name), id (string, owner's Spotify user ID), uri (string, spotify:user:{id}), external_urls ({spotify: url}).
• IsPublic (bool): Whether the playlist is public
• Collaborative (bool): Whether the playlist is collaborative
• SnapshotId (string): The snapshot ID of the playlist
• TotalTracks (number): Total number of items in the playlist
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Current User Playlists

This tool gets the playlists for the current authenticated Spotify user, with pagination support.

Options:

• Limit: Maximum number of playlists to return (1-50)
• Offset: The index of the first result to return

Output:

• Playlists (object-array): Array of playlist objects. Each object contains: Id (string, Spotify playlist ID), Name (string, playlist name), Description (string, playlist description), Public (boolean), Collaborative (boolean), SnapshotId (string, version identifier), TracksTotal (number, total item count), ExternalUrl (string, Spotify web player URL), Owner (string, playlist owner display name), OwnerId (string, playlist owner user ID).
• Total (number): Total number of playlists available
• Limit (number): The maximum number of playlists returned
• Offset (number): The offset of the playlists returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Playlist Items

This tool gets full details of the items in a playlist, with pagination support.

Input Parameters:

• PlaylistId: The Spotify playlist ID. Obtain from: Search Playlist action (id field), Get a Playlist action, or the Spotify playlist URL after '/playlist/'. Example: 37i9dQZF1DXcBWIGoYBM5M

Options:

• Limit: Maximum number of items to return per page. Valid range: 1-100, default 20. Example: 20
• Offset: The index of the first item to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.

Output:

• Items (object-array): Array of playlist item objects. Each object contains: Id (string), Type (string, track or episode), Name (string), Uri (string), DurationMs (number), ExternalUrl (string), AddedAt (string), AddedBy (string). Track items also include Artists and Album; episode items include Show.
• Total (number): Total number of items in the playlist
• Limit (number): The maximum number of items returned
• Offset (number): The offset of the items returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Remove Playlist Items

This tool removes one or more items from a user's playlist on Spotify. WARNING: This operation is permanent and cannot be undone. Removed items must be manually re-added if you want to restore them.

Input Parameters:

• PlaylistId: The Spotify playlist ID. Obtain from: Get a Playlist action (PlaylistId field), Search Playlist action, or the Spotify playlist URL after '/playlist/'. Example: 37i9dQZF1DXcBWIGoYBM5M
• ItemUris: Comma-separated list of Spotify item URIs to remove. Each URI may be spotify:track:{TrackId} or spotify:episode:{EpisodeId}. Obtain from Get Playlist Items action (Uri field) or Search Track action. Supports both full and half-width commas.

Options:

• SnapshotId: Playlist snapshot ID for version control (optional). Use this when multiple users or automations may be editing the same playlist simultaneously — if the playlist has been modified since you obtained this ID, the operation will fail, preventing accidental deletions. For most single-user scenarios, leave this empty to always apply the removal to the latest version. Format: Base64-encoded string, typically 60-80 characters. Obtain from Get a Playlist action (SnapshotId field). Example: MCwxNjc5NTc4NDAwMDAwLDAwMDAwMDAwMDAwMGQ0MWQ4Y2Q5OGYwMGIyMDRlOTgwMDk5OGVjZjg0Mjdl

Output:

• SnapshotId (string): The snapshot ID of the playlist after the removal operation. Format: Base64-encoded string, typically 60-80 characters long. Represents the new playlist version and can be passed as SnapshotId in subsequent Remove Playlist Items operations for optimistic concurrency control.
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Search Playlist

This tool searches for playlists on Spotify that match a query string, with pagination support.

Input Parameters:

• Query: Search keyword for playlists. Matches against playlist name, description, and creator. Multiple keywords (space-separated) narrow results. Example: Chill Vibes

Options:

• Market: Country code to filter playlists by market availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return results from all markets. Example: US
• Limit: Maximum number of playlists to return (1-50)
• Offset: Number of results to skip for pagination. Use 0 for the first page. For the next page, set to the current Limit value (e.g., page 1: Offset=0, page 2: Offset=20 when Limit=20). Default: 0

Output:

• Playlists (object-array): Array of playlist objects. Each object contains: Id (string, Spotify playlist ID), Name (string, playlist name), Description (string), Public (boolean), Collaborative (boolean), TracksTotal (number, track count), ExternalUrl (string, Spotify web link), Owner (string, creator name), Images (array of {Url, Height, Width}), SnapshotId (string, version identifier).
• Total (number): Total number of playlists matching the search
• Limit (number): The maximum number of playlists returned
• Offset (number): The offset of the playlists returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get a Track

This tool gets detailed information about a specific track on Spotify.

Input Parameters:

• TrackId: The Spotify track ID. Obtain from: Search Track action (id field), or the Spotify track URL after '/track/'. Example: 4iV5W9uYEdYUVa79Axb7Rh (from https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh)

Options:

• Market: Country code to check track availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Affects whether IsPlayable is true. Leave empty to use the user's account region. Example: US

Output:

• TrackId (string): The Spotify ID of the track
• TrackName (string): The name of the track
• TrackUri (string): The Spotify URI of the track in the format spotify:track:{id}. Used to open or play the track directly in the Spotify app.
• DurationMs (number): Track duration in milliseconds
• Explicit (bool): Whether the track contains explicit content
• Popularity (number): Track popularity (0-100)
• TrackNumber (number): The track number on the album
• DiscNumber (number): The disc number
• Artists (object-array): Array of artist information objects. Each object contains: Name (string, artist name), Id (string, Spotify artist ID), Uri (string, spotify:artist:{id}).
• Album (object): Album information object. Contains: Name (string, album name), Id (string, Spotify album ID), ReleaseDate (string, YYYY-MM-DD), TotalTracks (number, total tracks on album), Images (array of {Url, Height, Width}).
• ExternalUrl (string): The external Spotify URL for the track
• IsPlayable (bool): Whether the track is playable in the given market
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Liked Tracks

This tool retrieves the current user's saved (liked) tracks, with pagination support and optional market filtering.

Options:

• Limit: Maximum number of items to return per page. Valid range: 1-50, default 20. Example: 20
• Offset: The index of the first item to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.
• Market: Country code to filter track availability (optional). Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return all tracks regardless of market. Example: US

Output:

• Tracks (object-array): Array of liked track objects. Each object contains: Id (string, Spotify track ID), Name (string, track title), DurationMs (number, length in ms), Explicit (boolean, true if explicit content), Popularity (number, 0-100), Artists (array of {Id, Name}), Album ({Id, Name, ReleaseDate, Images: array of {Url, Height, Width}}), AddedAt (string, ISO 8601 timestamp when liked), ExternalUrls ({spotify: web player link}), Uri (string, spotify:track:{id}).
• Total (number): Total number of liked tracks in the user's library
• Limit (number): Maximum number of items returned
• Offset (number): Index of the first item returned
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Search Track

This tool searches for tracks on Spotify that match a query string, with pagination support.

Options:

• Query: Search keyword for tracks. Required unless NextUrl is provided for pagination. Supports simple and field-specific syntax: simple search ("Bohemian Rhapsody" searches all fields), or field-specific operators: track:Imagine (by track name), artist:Queen (by artist), album:A Night at the Opera (by album), year:1975 (by release year), genre:rock (by genre). Combine operators: "track:Imagine artist:John Lennon year:1971". Leave empty only when using NextUrl to fetch the next page. Example: track:Bohemian Rhapsody artist:Queen
• Market: Country code to filter tracks by regional availability (optional). Due to copyright restrictions, some tracks are only licensed for playback in specific countries. Use a two-letter country code: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany). Leave empty to return all tracks regardless of regional licensing. Example: US
• Limit: Maximum number of tracks to return per page. Valid range: 1-50, default: 20. Values outside this range will return a parameter validation error (StatusCode=-1). Example: 20
• Offset: The index of the first result to return, used for pagination. Default 0. Example: 20 to get the second page when Limit is 20.
• NextUrl: URL to fetch the next page of results. Leave empty for the first request. For subsequent pages, use the value from the Next field in the previous response. When provided, all other parameters (Query, Market, Limit, Offset) are ignored. Example: https://api.spotify.com/v1/search?query=queen&type=track&offset=20&limit=20

Output:

• Tracks (object-array): Array of track objects. Each track contains: Id (string, 22-char Spotify track ID — use with Play Track, Add Items to Playlist, or Get a Track APIs), Name (string, track title), Uri (string, Spotify internal playback protocol in format spotify:track:{id}, use with Spotify client; for web link use ExternalUrl instead), DurationMs (number, length in ms), Explicit (boolean), Popularity (number, 0-100), Artists (array of artist objects, each with Name (string) and Id (string, 22-char Spotify artist ID)), Album (object with Name (string), Id (string, 22-char Spotify album ID), ReleaseDate (string, YYYY-MM-DD), Images (array of {Url, Height, Width} in pixels)), ExternalUrl (string, Spotify web player link).
• Total (number): Total number of tracks matching the search
• Limit (number): The maximum number of tracks returned
• Offset (number): The offset of the tracks returned
• Next (string): URL to the next page of items
• Previous (string): URL to the previous page of items
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed

Get Current User Profile

Required scopes: user-read-email (for Email), user-read-private (for Country and Product). If these scopes were not granted during OAuth authorization, the corresponding fields may be empty. Retrieves the profile of the currently authenticated Spotify user. Use the returned UserId to confirm playlist ownership when comparing against Owner.id from Get a Playlist. The Product field indicates whether the user has a Premium subscription, which is required for playback control actions.

Output:

• UserId (string): The current user's Spotify ID. Use this value to confirm playlist ownership when comparing against Owner.id from Get a Playlist. Example: johnsmith or 31jxf8k2l3m4n5o6p7q8r9s0t1u2
• DisplayName (string): The user's display name on Spotify. May be empty if not set.
• Email (string): The user's registered email address. Requires user-read-email scope.
• Country (string): The country of the user's Spotify account as a two-letter country code (e.g., US, CN, GB). Requires user-read-private scope.
• Product (string): The user's Spotify subscription level. Values: premium (paid subscription), free (ad-supported). Requires user-read-private scope.
• Followers (number): The total number of followers of the user.
• Uri (string): The Spotify URI for the user. Format: spotify:user:{id}. Example: spotify:user:johnsmith
• ExternalUrl (string): The Spotify web player URL for the user's profile. Example: https://open.spotify.com/user/johnsmith
• Images (object-array): Array of the user's profile image objects. Each contains: Url (string, image URL), Height (number, pixel height), Width (number, pixel width). Empty array if no profile image is set. Example: [{"Url": "https://i.scdn.co/image/abc123", "Height": 300, "Width": 300}]
• OriginalStatusCode (number): The original HTTP status code returned by the Spotify API. 0=request did not reach upstream. 200/201/204=success. 4xx=client error (check ErrorMessage).
• StatusCode (number): Operation status code: 200=execution completed (check ErrorMessage for business errors), -1=parameter validation error, 500=network error (may retry).
• ErrorMessage (string): Error message if operation failed. Empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to create a new playlist in your Spotify account.

The workflow will consist of three nodes: Start -> Create a Playlist -> Answer.

1. Add the Spotify Node

• In the workflow canvas, click the + button to add a new node.
• Select the "Tools" tab in the pop-up panel.
• Find and select "Spotify" from the list of tools.
• From the list of supported operations for Spotify, click on "Create a Playlist" to add the node to your canvas.

2. Configure the Node

• Click on the newly added "Create a Playlist" node to open its configuration panel on the right.
• Credentials: Find the credentials field at the top of the panel. Click the dropdown menu and select your pre-configured Spotify credentials.
• Parameters: Fill in the required input parameters for the action.
  • UserId: Enter your Spotify User ID. You can typically find this by logging into your account on the Spotify website and checking your profile details.
  • Name: Provide a name for your new playlist, for example, My GoInsight Workflow Playlist.
  • You can also optionally provide a Description or set the Public status for the playlist.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Run Test" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the logs icon in the top-right corner to view the detailed input and output of the node. You should see outputs like PlaylistId and PlaylistUrl, confirming that the playlist was created successfully.

After completing these steps, your workflow is fully configured. When you run it, a new playlist will be created in your Spotify account.

6. FAQs

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: This typically indicates a problem with your credentials or the permissions (scopes) granted to your application. Please check the following:

• Ensure your API credentials are correct and have been selected in the node.
• Verify that your Spotify application has been granted the necessary scopes for the operation you are trying to perform (e.g., playlist-modify-public for creating public playlists, user-modify-playback-state for controlling playback).

Q: Why do playback control actions like 'Pause Playback' or 'Next Song' not work?

A: Many playback control operations are restricted to Spotify Premium users. Please ensure the Spotify account linked to your credentials has an active Premium subscription.

Q: How do I find a Track URI or Album ID?

A: You can find these identifiers directly within the Spotify app or web player.

• On the desktop app or web player, click the "..." (More) button next to a track, album, or playlist.
• Go to the "Share" submenu.
• Select "Copy Spotify URI" or "Copy Link". The URI is a string like spotify:track:12345..., and the ID is the last part of the URI or URL.

7. Official Documentation

For more in-depth information about the capabilities and technical details of the Spotify API, please refer to the official documentation:

Spotify for Developers Official API Documentation