--- updatedAt: 2026-05-29T15:12:00.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Search playlists Performs a keyword, genre, playlist ID, or owner-based search and returns paginated playlists. Playlist IDs and owner IDs are combined with AND by default; pass `idsOwnerOperator=or` to match either explicit playlist IDs or owner filters. `excludeIds` and `excludeOwnerIds` always exclude matching playlists after positive filters are applied. Playlist objects include track summary fields and, when available, `tracks.items` with per-track metadata. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "artist.tools V2 API", "description": "REST API for accessing artist.tools data about Spotify playlists, tracks, artists and curators, as well as miscellaneous utilities. All endpoints are read-only and require an `x-api-key` sent as a request header.", "version": "2.0.0" }, "servers": [ { "url": "https://api.artist.tools/v2", "description": "Production server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/playlists/search": { "get": { "tags": [ "Playlists" ], "summary": "Search playlists", "description": "Performs a keyword, genre, playlist ID, or owner-based search and returns paginated playlists. Playlist IDs and owner IDs are combined with AND by default; pass `idsOwnerOperator=or` to match either explicit playlist IDs or owner filters. `excludeIds` and `excludeOwnerIds` always exclude matching playlists after positive filters are applied. Playlist objects include track summary fields and, when available, `tracks.items` with per-track metadata.", "parameters": [ { "$ref": "#/components/parameters/SearchQuery" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/QueryExactly" }, { "$ref": "#/components/parameters/QueryExclude" }, { "$ref": "#/components/parameters/Genres" }, { "$ref": "#/components/parameters/ArtistNames" }, { "$ref": "#/components/parameters/ArtistIds" }, { "$ref": "#/components/parameters/TrackIds" }, { "$ref": "#/components/parameters/Ids" }, { "$ref": "#/components/parameters/ExcludeIds" }, { "$ref": "#/components/parameters/MinFollowers" }, { "$ref": "#/components/parameters/MaxFollowers" }, { "$ref": "#/components/parameters/MinListeners" }, { "$ref": "#/components/parameters/MaxListeners" }, { "$ref": "#/components/parameters/HasContact" }, { "$ref": "#/components/parameters/Contacts" }, { "$ref": "#/components/parameters/HideCrap" }, { "$ref": "#/components/parameters/HideInactive" }, { "$ref": "#/components/parameters/NewestTrackDate" }, { "$ref": "#/components/parameters/ExcludeEditorials" }, { "$ref": "#/components/parameters/EditorialOnly" }, { "$ref": "#/components/parameters/BottedOnly" }, { "$ref": "#/components/parameters/ActiveOnly" }, { "$ref": "#/components/parameters/AvgDailyFollowers" }, { "$ref": "#/components/parameters/OwnerId" }, { "$ref": "#/components/parameters/OwnerIds" }, { "$ref": "#/components/parameters/ExcludeOwnerIds" }, { "$ref": "#/components/parameters/IdsOwnerOperator" }, { "$ref": "#/components/parameters/CollaboratorIds" }, { "$ref": "#/components/parameters/HideRemoved" }, { "$ref": "#/components/parameters/IncludeCurators" }, { "$ref": "#/components/parameters/MinAge" } ], "responses": { "200": { "$ref": "#/components/responses/SearchPlaylistsResponse" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "SearchQuery": { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Primary search string" }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number for paginated searches" }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 500 }, "description": "Number of items per page (max 500)" }, "Sort": { "name": "sort", "in": "query", "schema": { "type": "string", "example": "{\"followers.total\":-1}" }, "description": "Mongo-style JSON object describing sort order (URL-encoded)" }, "QueryExactly": { "name": "queryExactly", "in": "query", "schema": { "type": "string" }, "description": "Exact phrase search in playlist names and descriptions" }, "QueryExclude": { "name": "queryExclude", "in": "query", "schema": { "type": "string" }, "description": "Words to exclude from search results" }, "Genres": { "name": "genres", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of genres that playlists must contain" }, "ArtistNames": { "name": "artistNames", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of artist names that playlists must contain" }, "ArtistIds": { "name": "artistIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of Spotify artist IDs" }, "TrackIds": { "name": "trackIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of Spotify track IDs" }, "Ids": { "name": "ids", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of Spotify playlist IDs to filter results" }, "ExcludeIds": { "name": "excludeIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of Spotify playlist IDs to exclude from results" }, "MinFollowers": { "name": "minFollowers", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum number of followers" }, "MaxFollowers": { "name": "maxFollowers", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Maximum number of followers" }, "MinListeners": { "name": "minListeners", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum number of monthly listeners" }, "MaxListeners": { "name": "maxListeners", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Maximum number of monthly listeners" }, "HasContact": { "name": "hasContact", "in": "query", "schema": { "type": "boolean" }, "description": "Filter playlists that have contact information available" }, "Contacts": { "name": "contacts", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "email", "instagram", "submithub", "groover", "submitlink", "dailyplaylists" ] } }, "style": "form", "explode": false, "description": "Specific contact types to filter by" }, "HideCrap": { "name": "hideCrap", "in": "query", "schema": { "type": "boolean" }, "description": "Hide low quality playlists (quality score >= -10)" }, "HideInactive": { "name": "hideInactive", "in": "query", "schema": { "type": "boolean" }, "description": "Hide playlists inactive for more than 30 days" }, "NewestTrackDate": { "name": "newestTrackDate", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Filter playlists updated within the last N days" }, "ExcludeEditorials": { "name": "excludeEditorials", "in": "query", "schema": { "type": "boolean" }, "description": "Exclude Spotify editorial playlists" }, "EditorialOnly": { "name": "editorialOnly", "in": "query", "schema": { "type": "boolean" }, "description": "Show only Spotify editorial playlists" }, "BottedOnly": { "name": "bottedOnly", "in": "query", "schema": { "type": "boolean" }, "description": "Show only playlists detected as botted" }, "ActiveOnly": { "name": "activeOnly", "in": "query", "schema": { "type": "boolean" }, "description": "Show only playlists with high daily follower growth" }, "AvgDailyFollowers": { "name": "avgDailyFollowers", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum average daily follower growth" }, "OwnerId": { "name": "ownerId", "in": "query", "schema": { "type": "string" }, "description": "Filter by specific playlist owner ID" }, "OwnerIds": { "name": "ownerIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of playlist owner IDs" }, "ExcludeOwnerIds": { "name": "excludeOwnerIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated list of playlist owner IDs to exclude from results" }, "IdsOwnerOperator": { "name": "idsOwnerOperator", "in": "query", "schema": { "type": "string", "enum": [ "and", "or" ], "default": "and" }, "description": "Controls how `ids` combines with `ownerId` and `ownerIds`. Use `and` to require both playlist ID and owner filters, or `or` to match either. Exclusion filters still apply." }, "CollaboratorIds": { "name": "collaboratorIds", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "style": "form", "explode": false, "description": "Comma-separated list of curator Spotify User IDs to filter playlists where the curator is a collaborator (max 10)" }, "HideRemoved": { "name": "hideRemoved", "in": "query", "schema": { "type": "boolean" }, "description": "Hide playlists marked as removed" }, "IncludeCurators": { "name": "includeCurators", "in": "query", "schema": { "type": "boolean" }, "description": "Include curator search results alongside playlists" }, "MinAge": { "name": "minAge", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum number of days since the playlist was first ingested into our dataset" } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "integer", "example": 200 } }, "required": [ "success", "status" ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "success", "error", "status" ] }, "Playlist": { "type": "object", "description": "Playlist model", "properties": { "_id": { "type": "string", "description": "Internal database ID" }, "spotifyId": { "type": "string", "description": "Spotify ID of the playlist" }, "name": { "type": "string", "description": "Name of the playlist" }, "coverArtUrl": { "type": "string", "description": "URL of the playlist's cover art" }, "popularity": { "type": "integer", "description": "Popularity score of the playlist" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date the playlist was ingested by artist.tools" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date the playlist was last updated in our database, for any reason" }, "dataUpdatedAt": { "type": "string", "format": "date-time", "description": "Date the playlist's core metrics were last updated" }, "isRemoved": { "type": "boolean", "description": "Whether the playlist has been removed from Spotify" }, "entityType": { "type": "string", "enum": [ "playlist" ], "description": "Entity type identifier" }, "contactData": { "type": "object", "description": "Available contact data for the curator", "properties": { "email": { "type": "string", "nullable": true, "description": "Email address of the curator" }, "instagram": { "type": "string", "nullable": true, "description": "Instagram handle of the curator" }, "submithub": { "type": "string", "nullable": true, "description": "Submithub handle of the curator (great indicator the playlist is legit)" }, "groover": { "type": "string", "nullable": true, "description": "Groover handle of the curator" }, "submitlink": { "type": "string", "nullable": true, "description": "Submitlink handle of the curator (great indicator the playlist is legit)" }, "dailyplaylists": { "type": "string", "nullable": true, "description": "Dailyplaylists handle of the curator" } } }, "hasContact": { "type": "boolean", "description": "Whether the curator has contact data available" }, "listenerData": { "type": "object", "description": "Upper and lower estimates of the playlist's listener count", "properties": { "min": { "type": "integer", "description": "Minimum estimated listener count" }, "max": { "type": "integer", "description": "Maximum estimated listener count" } } }, "listeners": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "deprecated": true, "description": "Deprecated: Use listenerData instead. Remains on some playlist entities for backwards compatibility." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Genres of the playlist, calculated from aggregating genres from artists within the playlist" }, "description": { "type": "string", "description": "Description of the playlist" }, "followers": { "type": "object", "description": "Followers of the playlist", "properties": { "total": { "type": "integer", "description": "Total number of followers of the playlist" }, "avgDaily": { "type": "number", "description": "Average number of daily followers of the playlist over the last 14 days" } } }, "qualityScore": { "type": "number", "description": "Quality score of the playlist, -50 and lower is considered possibly botted, -900 and lower is considered definitely botted, anything above -50 is considered legit, and 0 is considered unknown" }, "qualityData": { "type": "object", "description": "Quality analysis data for the playlist", "properties": { "override": { "type": "object", "description": "Override data for the playlist" }, "indicators": { "type": "array", "items": { "type": "string" }, "description": "Behavioral indicators of the playlist" }, "fraudData": { "type": "array", "items": { "type": "object" }, "description": "Fraud detection data with dates and reasons" }, "fraudDates": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Deprecated: Use fraudData instead. Remains for backwards compatibility." }, "ignoreDates": { "type": "array", "items": { "type": "object" }, "deprecated": true, "description": "Deprecated: No longer being updated." }, "botted": { "type": "boolean", "description": "Whether the playlist is detected as botted, based on the qualityScore and other indicators" } } }, "ownerData": { "type": "object", "description": "Information about the playlist owner/curator", "properties": { "spotifyId": { "type": "string", "description": "Spotify ID of the curator" }, "followers": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of followers" } }, "description": "Follower information" }, "name": { "type": "string", "description": "Name of the curator" }, "private": { "type": "boolean", "description": "Whether the curator's profile is private" }, "coverArtUrl": { "type": "string", "description": "Cover art URL of the curator" } } }, "tracks": { "type": "object", "description": "Track information for the playlist", "properties": { "audioPreviewUrl": { "type": "string", "nullable": true, "description": "Audio preview URL for the playlist" }, "topArtists": { "type": "array", "description": "Top artists in the playlist", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Artist name" }, "spotifyId": { "type": "string", "description": "Artist Spotify ID" } } } }, "newestDate": { "type": "string", "format": "date-time", "description": "Date of the newest track added" }, "uniqueCount": { "type": "integer", "description": "Number of unique tracks in the playlist after duplicate track occurrences are collapsed" }, "duplicateCount": { "type": "integer", "description": "Number of duplicate track occurrences in the playlist" }, "items": { "type": "array", "description": "Track metadata embedded in this playlist, ordered by playlist position when available.", "items": { "$ref": "#/components/schemas/PlaylistTrackItem" } }, "total": { "type": "integer", "description": "Total number of tracks in playlist" }, "uniquePrimaryArtistIds": { "type": "array", "items": { "type": "string" }, "description": "Unique primary artist IDs" } } }, "snapshots": { "type": "array", "items": { "type": "object" }, "description": "Historical snapshots of the playlist" }, "keywordSnapshots": { "type": "array", "description": "Keyword ranking history when includeKeywordSnapshots=true, newest first. V2 payloads normally contain keyword, market, position, and createdAt. With explicit legacy inclusion, payload fields and format are not guaranteed and may differ or be missing.", "items": { "type": "object", "additionalProperties": true } } } }, "PlaylistTrackItem": { "type": "object", "description": "Track item embedded in a playlist's `tracks.items` array.", "properties": { "spotifyId": { "type": "string", "description": "Spotify ID of the track.", "example": "5nEYtrqLFQWk333KtmNcsK" }, "name": { "type": "string", "description": "Track name.", "example": "I'm Tryin'" }, "spotifyArtistIds": { "type": "array", "description": "Spotify IDs of artists credited on the track.", "items": { "type": "string" }, "example": [ "7G89FpUPUFxkMwkosdRB0X", "7oBoHwrzoHVMhlY8T7xOnm" ] }, "spotifyArtistNames": { "type": "array", "description": "Names of artists credited on the track.", "items": { "type": "string" }, "example": [ "Example Artist", "Featured Artist" ] }, "addedAt": { "type": "string", "format": "date-time", "description": "Date/time this track was added to the playlist.", "example": "2022-06-24T16:36:23.295Z" }, "releasedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Track release date when available.", "example": null }, "audioPreviewUrl": { "type": "string", "nullable": true, "description": "Spotify audio preview URL for this track when available.", "example": "" }, "position": { "type": "array", "description": "One or more 0-based positions for this track in the playlist. Multiple positions indicate duplicate occurrences.", "items": { "type": "integer" }, "example": [ 0 ] } } }, "Curator": { "type": "object", "description": "Curator model", "properties": { "_id": { "type": "string", "description": "Internal database ID" }, "spotifyId": { "type": "string", "description": "Spotify ID of the curator" }, "name": { "type": "string", "description": "Name of the curator" }, "coverArtUrl": { "type": "string", "description": "URL of the curator's cover art" }, "popularity": { "type": "integer", "description": "Popularity score of the curator" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date the curator was ingested by artist.tools" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date the curator was last updated in our database, for any reason" }, "dataUpdatedAt": { "type": "string", "format": "date-time", "description": "Date the curator's core metrics were last updated" }, "isRemoved": { "type": "boolean", "description": "Whether the curator has been removed from Spotify" }, "entityType": { "type": "string", "enum": [ "curator" ], "description": "Entity type identifier" }, "contactData": { "type": "object", "description": "Available contact data for the curator", "properties": { "email": { "type": "string", "nullable": true, "description": "Email address of the curator" }, "instagram": { "type": "string", "nullable": true, "description": "Instagram handle of the curator" }, "submithub": { "type": "string", "nullable": true, "description": "Submithub handle of the curator (great indicator the playlist is legit)" }, "groover": { "type": "string", "nullable": true, "description": "Groover handle of the curator" }, "submitlink": { "type": "string", "nullable": true, "description": "Submitlink handle of the curator (great indicator the playlist is legit)" }, "dailyplaylists": { "type": "string", "nullable": true, "description": "Dailyplaylists handle of the curator" } } }, "followers": { "type": "object", "description": "Total number of followers and following count of the curator", "properties": { "total": { "type": "integer", "description": "Total number of followers" }, "followingCount": { "type": "integer", "description": "Number of accounts the curator follows" } } }, "hasContact": { "type": "boolean", "description": "Whether the curator has contact data available" }, "listenerData": { "type": "object", "description": "Upper and lower estimates of the curator's listener count", "properties": { "min": { "type": "integer", "description": "Minimum estimated listener count" }, "max": { "type": "integer", "description": "Maximum estimated listener count" } } }, "private": { "type": "boolean", "description": "Whether the curator's profile is manually marked as private, hiding followers/following counts" }, "verified": { "type": "boolean", "description": "Whether the curator's profile is verified by Spotify (and has the verified badge)" }, "playlists": { "type": "object", "description": "Playlists created by the curator", "properties": { "total": { "type": "integer", "description": "Total number of playlists the curator has created" }, "followerReach": { "type": "integer", "description": "Total number of followers of the playlists the curator has created" }, "fraud": { "type": "integer", "description": "Number of playlists the curator has created that are detected as botted" }, "fraudSpotifyIds": { "type": "array", "items": { "type": "string" }, "description": "Spotify IDs of the playlists the curator has created that are detected as botted" }, "spotifyIds": { "type": "array", "items": { "type": "string" }, "description": "Spotify IDs of the playlists the curator has created" }, "popularity": { "type": "integer", "description": "Popularity score of the playlists the curator has created" }, "listeners": { "type": "integer", "description": "Total number of estimated low-end listeners of the playlists the curator has created" }, "followers": { "type": "object", "description": "Follower metrics for curator's playlists", "properties": { "total": { "type": "integer", "description": "Total number of followers of the playlists" }, "avgDaily": { "type": "number", "description": "Average daily followers of the playlists" } } } } }, "snapshots": { "type": "array", "items": { "type": "object" }, "description": "Historical snapshots of the curator" } } }, "PlaylistSearchPage": { "type": "object", "description": "Paginated playlists response", "properties": { "docs": { "type": "array", "items": { "$ref": "#/components/schemas/Playlist" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPrevPage": { "type": "boolean" }, "curators": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Curator" }, "description": "Curator search results (included when includeCurators=true)" } } } }, "responses": { "SearchPlaylistsResponse": { "description": "Paginated playlist search results with optional curator data", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search_playlists" ] }, "data": { "$ref": "#/components/schemas/PlaylistSearchPage" } } } ] }, "example": { "success": true, "status": 200, "type": "search_playlists", "data": { "docs": [ { "spotifyId": "37i9dQZF1DWUBCiFp3lAyi", "name": "Chill Vibes", "coverArtUrl": "https://i.scdn.co/image/ab67706f00000002example", "popularity": 78, "entityType": "playlist", "followers": { "total": 1250000, "avgDaily": 420.5 }, "qualityScore": 72, "qualityData": { "override": {}, "indicators": [ "consistent_growth" ], "fraudData": [], "botted": false }, "genres": [ "chill", "ambient" ], "hasContact": true, "listenerData": { "min": 85000, "max": 120000 }, "ownerData": { "spotifyId": "spotify", "name": "Spotify" }, "tracks": { "audioPreviewUrl": "https://p.scdn.co/mp3-preview/example.mp3", "total": 85, "uniqueCount": 83, "duplicateCount": 2, "uniquePrimaryArtistIds": [ "5INjqkS1o8h1imAzPqGZBb" ], "topArtists": [ { "name": "Tame Impala", "spotifyId": "5INjqkS1o8h1imAzPqGZBb" } ], "newestDate": "2026-04-05T00:00:00.000Z", "items": [ { "spotifyId": "1irAliF0T8sLIOPJp6n7rU", "name": "Eventually", "spotifyArtistIds": [ "5INjqkS1o8h1imAzPqGZBb" ], "spotifyArtistNames": [ "Tame Impala" ], "addedAt": "2026-03-29T14:22:10.000Z", "releasedAt": "2015-07-17T00:00:00.000Z", "audioPreviewUrl": "https://p.scdn.co/mp3-preview/example-track-1.mp3", "position": [ 0 ] } ] } } ], "page": 1, "limit": 25, "hasNextPage": true, "hasPrevPage": false } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } ```