--- updatedAt: 2026-08-20T21:35:19.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Get a playlist's Spotify Rankings Returns stored keyword and market combinations for which the playlist appeared in Spotify's top 50 during the selected 30-, 60-, or 90-day window. This endpoint never triggers bulk provider searches. Lifecycle status and freshness are intentionally separate: active means present in the latest successful check, lost means a later successful check confirmed absence, and unknown means no later check was conclusive; fresh, stale, and missing describe the age of that check. Filters apply before the exact summary and pagination totals are calculated. History contains at most one point per UTC day and is loaded only for the returned page. Estimated position volume is modeled from keyword volume and position; it is not observed traffic. # 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": [] } ], "tags": [ { "name": "SEO", "description": "Read-only search visibility and press coverage analytics for Spotify entities. Google Rankings and Press Mentions refresh missing or stale stored data automatically; playlist Spotify Rankings use stored observations only." } ], "paths": { "/playlists/{id}/spotify-rankings": { "get": { "tags": [ "SEO" ], "summary": "Get a playlist's Spotify Rankings", "description": "Returns stored keyword and market combinations for which the playlist appeared in Spotify's top 50 during the selected 30-, 60-, or 90-day window. This endpoint never triggers bulk provider searches. Lifecycle status and freshness are intentionally separate: active means present in the latest successful check, lost means a later successful check confirmed absence, and unknown means no later check was conclusive; fresh, stale, and missing describe the age of that check. Filters apply before the exact summary and pagination totals are calculated. History contains at most one point per UTC day and is loaded only for the returned page. Estimated position volume is modeled from keyword volume and position; it is not observed traffic.", "parameters": [ { "$ref": "#/components/parameters/PlaylistId" }, { "$ref": "#/components/parameters/PlaylistRankingQuery" }, { "$ref": "#/components/parameters/PlaylistRankingMarket" }, { "$ref": "#/components/parameters/PlaylistRankingStatus" }, { "$ref": "#/components/parameters/PlaylistRankingMovement" }, { "$ref": "#/components/parameters/PositionMin" }, { "$ref": "#/components/parameters/PositionMax" }, { "$ref": "#/components/parameters/HistoryWindow" }, { "$ref": "#/components/parameters/IncludeHistory" }, { "$ref": "#/components/parameters/PlaylistRankingSortBy" }, { "$ref": "#/components/parameters/SortDirection" }, { "$ref": "#/components/parameters/AnalyticsPage" }, { "$ref": "#/components/parameters/AnalyticsLimit" } ], "responses": { "200": { "$ref": "#/components/responses/PlaylistSpotifyRankingsResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "PlaylistId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "37i9dQZF1DWUBCiFp3lAyi" }, "description": "Spotify Playlist ID" }, "AnalyticsPage": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "One-based result page. Invalid values return HTTP 400." }, "AnalyticsLimit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Primary rows per page. Invalid values are rejected rather than clamped." }, "SortDirection": { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction. Google and playlist ranking endpoints default to asc; Press Mentions defaults to desc." }, "PlaylistRankingQuery": { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 150 }, "description": "Case-insensitive keyword search." }, "PlaylistRankingMarket": { "name": "market", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z]{2}$" }, "description": "Supported two-letter keyword market. Omit to include every market." }, "PlaylistRankingStatus": { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "lost", "unknown" ], "default": "all" }, "description": "active means present in the latest successful top-50 check; lost means a later successful check confirmed absence; unknown means no later check was conclusive." }, "PlaylistRankingMovement": { "name": "movement", "in": "query", "schema": { "type": "string", "enum": [ "new", "rising", "declining", "unchanged" ] }, "description": "Movement between the newest and previous distinct daily appearance. Omit to include all movement states." }, "PositionMin": { "name": "positionMin", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }, "description": "Best last-known Spotify position to include. Must be less than or equal to positionMax." }, "PositionMax": { "name": "positionMax", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 }, "description": "Worst last-known Spotify position to include. Must be greater than or equal to positionMin." }, "HistoryWindow": { "name": "historyWindow", "in": "query", "schema": { "type": "string", "enum": [ "30d", "60d", "90d" ], "default": "30d" }, "description": "Stored observation window ending at request time. It controls which keyword appearances are eligible and the maximum history returned; it does not initiate new Spotify searches." }, "IncludeHistory": { "name": "includeHistory", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "When false, history arrays are omitted. Lifecycle timestamps still use stored observations." }, "PlaylistRankingSortBy": { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "position", "keyword", "lastSeenAt" ], "default": "position" }, "description": "Primary sort field. position uses lastKnownPosition; lastSeenAt uses the newest stored appearance. Market and keyword are stable tie-breakers." } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "integer", "example": 200 } }, "required": [ "success", "status" ] }, "AnalyticsPagination": { "type": "object", "description": "Pagination metadata for the complete filtered result. Collection responses contain no more than 100 primary rows.", "properties": { "page": { "type": "integer", "minimum": 1, "description": "Current one-based page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Requested maximum primary rows per page." }, "total": { "type": "integer", "minimum": 0, "description": "Exact number of rows matching all filters before pagination." }, "totalPages": { "type": "integer", "minimum": 0, "description": "Number of pages at the requested limit; zero when total is zero." }, "hasNextPage": { "type": "boolean", "description": "Whether a later page exists." }, "hasPreviousPage": { "type": "boolean", "description": "Whether an earlier non-empty page exists." } }, "required": [ "page", "limit", "total", "totalPages", "hasNextPage", "hasPreviousPage" ] }, "AnalyticsEntity": { "type": "object", "description": "The Spotify entity whose analytics are returned.", "properties": { "type": { "type": "string", "enum": [ "artist", "track", "playlist", "curator" ], "description": "Normalized entity type matching the endpoint resource." }, "spotifyId": { "type": "string", "description": "Raw Spotify ID supplied in the request path." } }, "required": [ "type", "spotifyId" ] }, "PositionObservation": { "type": "object", "description": "One distinct UTC-day ranking observation.", "properties": { "observedAt": { "type": "string", "format": "date-time", "description": "UTC observation timestamp." }, "position": { "type": "integer", "minimum": 1, "description": "One-based search-result position observed at that time." } }, "required": [ "observedAt", "position" ] }, "PlaylistSpotifyRanking": { "type": "object", "description": "One keyword and market combination for which the playlist appeared during the selected window.", "properties": { "keyword": { "type": "string", "description": "Normalized Spotify search phrase." }, "market": { "type": "string", "description": "Lowercase market code for the stored search." }, "status": { "type": "string", "enum": [ "active", "lost", "unknown" ], "description": "active when the playlist is in the keyword's latest successful top-50 check; lost when a later successful check confirmed absence; unknown when no later successful check was conclusive." }, "freshness": { "type": "string", "enum": [ "fresh", "stale", "missing" ], "description": "Separate from lifecycle status: fresh within 30 days, stale after 30 days, missing without a successful-check timestamp." }, "movement": { "type": "string", "enum": [ "new", "rising", "declining", "unchanged" ], "description": "Change from the previous distinct daily appearance within the selected window." }, "currentPosition": { "type": "integer", "minimum": 1, "maximum": 50, "nullable": true, "description": "Latest top-50 position for active rows; null for lost and unknown rows." }, "previousPosition": { "type": "integer", "minimum": 1, "maximum": 50, "nullable": true, "description": "Previous distinct daily position, or null when this is the first appearance in the window." }, "lastKnownPosition": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Most recently observed top-50 position, retained when currentPosition is null." }, "positionChange": { "type": "integer", "nullable": true, "description": "previousPosition minus lastKnownPosition; positive means the playlist improved." }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "UTC timestamp of the keyword's latest successful Spotify check, or null when no check timestamp is stored." }, "firstSeenInWindowAt": { "type": "string", "format": "date-time", "description": "Earliest returned daily appearance within the resolved history window." }, "lastSeenAt": { "type": "string", "format": "date-time", "description": "Most recent stored appearance within the resolved history window." }, "keywordMetrics": { "type": "object", "properties": { "google": { "type": "object", "description": "Stored Google keyword metrics associated with this Spotify keyword and market.", "properties": { "volume": { "type": "number", "minimum": 0, "description": "Estimated monthly Google query volume; not observed playlist traffic." }, "growth": { "type": "number", "description": "Google volume growth ratio; 1 means 100% growth and -0.25 means a 25% decline." }, "demand": { "type": "string", "enum": [ "huge", "high", "steady", "low" ], "description": "Demand band derived from volume: huge is 50,000+, high is 10,000-49,999, steady is 400-9,999, and low is below 400." } }, "required": [ "volume", "growth", "demand" ] }, "spotify": { "type": "object", "description": "Stored aggregate metrics for playlists in the keyword's latest Spotify top-50 result.", "properties": { "followerReach": { "type": "number", "minimum": 0, "description": "Combined Spotify followers of top-result playlists with usable data; overlap is not deduplicated into unique listeners." }, "followerGrowthRate": { "type": "number", "description": "Average projected monthly follower-growth percentage across contributing playlists; 20 means 20%." }, "followerGrowthPerDay": { "type": "number", "description": "Average net followers gained per day by a contributing playlist; may be negative." }, "followerGrowthPerDayTotal": { "type": "number", "description": "Sum of net followers gained per day across contributing playlists; may be negative." }, "playlistsWithData": { "type": "number", "minimum": 0, "description": "Number of top-result playlists with usable stored metrics." }, "competition": { "type": "string", "enum": [ "dominated", "crowded", "moderate", "easy" ], "description": "Follower-reach band: dominated is 50,000,000+, crowded is 10,000,000-49,999,999, moderate is 1,000,000-9,999,999, and easy is below 1,000,000." }, "momentum": { "type": "string", "enum": [ "declining", "surging", "breakout", "steady_growth", "stable_base" ], "description": "Application momentum band derived from follower-growth rate and daily growth; use the numeric growth fields when exact thresholds matter." }, "genreFocus": { "type": "number", "minimum": 0, "description": "Share of contributing playlists assigned the most common genre; 1 means every contributing playlist shared that genre." }, "genres": { "type": "array", "maxItems": 10, "description": "Up to ten leading genres, normalized to shares across the genres returned here.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Stored Spotify genre label." }, "share": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized share among the returned leading genres." } }, "required": [ "name", "share" ] } } }, "required": [ "followerReach", "followerGrowthRate", "followerGrowthPerDay", "followerGrowthPerDayTotal", "playlistsWithData", "competition", "momentum", "genreFocus", "genres" ] } }, "required": [ "google", "spotify" ] }, "estimatedPositionVolume": { "type": "number", "minimum": 0, "description": "Modeled estimate based on keyword volume and position; not observed traffic." }, "history": { "type": "array", "maxItems": 90, "description": "At most one observation per UTC day within the resolved history window. Omitted when includeHistory=false.", "items": { "$ref": "#/components/schemas/PositionObservation" } } }, "required": [ "keyword", "market", "status", "freshness", "movement", "currentPosition", "previousPosition", "lastKnownPosition", "positionChange", "lastCheckedAt", "firstSeenInWindowAt", "lastSeenAt", "keywordMetrics", "estimatedPositionVolume" ] }, "PlaylistSpotifyRankingsData": { "type": "object", "description": "Filtered Spotify-ranking rows, exact pre-pagination totals, and the resolved observation window.", "properties": { "entity": { "$ref": "#/components/schemas/AnalyticsEntity" }, "historyWindow": { "type": "object", "description": "Resolved UTC boundaries used to select stored playlist appearances.", "properties": { "value": { "type": "string", "enum": [ "30d", "60d", "90d" ], "description": "Requested window preset." }, "from": { "type": "string", "format": "date-time", "description": "Inclusive UTC lower boundary." }, "to": { "type": "string", "format": "date-time", "description": "UTC request time used as the upper boundary." } }, "required": [ "value", "from", "to" ] }, "summary": { "type": "object", "description": "Totals for the complete filtered result before pagination.", "properties": { "total": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 }, "lost": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 }, "estimatedPositionVolume": { "type": "number", "minimum": 0, "description": "Sum of modeled estimatedPositionVolume across every filtered row before pagination; not observed traffic." } }, "required": [ "total", "active", "lost", "unknown", "estimatedPositionVolume" ] }, "rankings": { "type": "array", "maxItems": 100, "description": "Current page only. Full history is fetched only for keyword/market pairs on this page.", "items": { "$ref": "#/components/schemas/PlaylistSpotifyRanking" } }, "pagination": { "$ref": "#/components/schemas/AnalyticsPagination" } }, "required": [ "entity", "historyWindow", "summary", "rankings", "pagination" ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "success", "error", "status" ] } }, "responses": { "PlaylistSpotifyRankingsResponse": { "description": "Stored Spotify keyword rankings for one playlist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "playlist_spotify_rankings" ] }, "data": { "$ref": "#/components/schemas/PlaylistSpotifyRankingsData" } }, "required": [ "type", "data" ] } ] }, "examples": { "activeRanking": { "summary": "Active, fresh ranking with history", "value": { "success": true, "status": 200, "type": "playlist_spotify_rankings", "data": { "entity": { "type": "playlist", "spotifyId": "2SM6rniZl84fEyMCB5KMQB" }, "historyWindow": { "value": "30d", "from": "2026-07-21T12:00:00.000Z", "to": "2026-08-20T12:00:00.000Z" }, "summary": { "total": 1, "active": 1, "lost": 0, "unknown": 0, "estimatedPositionVolume": 4953 }, "rankings": [ { "keyword": "workout playlist 2026", "market": "us", "status": "active", "freshness": "fresh", "movement": "rising", "currentPosition": 2, "previousPosition": 5, "lastKnownPosition": 2, "positionChange": 3, "lastCheckedAt": "2026-08-19T12:00:00.000Z", "firstSeenInWindowAt": "2026-07-25T00:00:00.000Z", "lastSeenAt": "2026-08-19T00:00:00.000Z", "keywordMetrics": { "google": { "volume": 12100, "growth": 0.15, "demand": "high" }, "spotify": { "followerReach": 5230000, "followerGrowthRate": 6.18, "followerGrowthPerDay": 412.7, "followerGrowthPerDayTotal": 16920.7, "playlistsWithData": 41, "competition": "moderate", "momentum": "surging", "genreFocus": 0.68, "genres": [ { "name": "workout", "share": 1 } ] } }, "estimatedPositionVolume": 4953, "history": [ { "observedAt": "2026-08-19T00:00:00.000Z", "position": 2 } ] } ], "pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } } } }, "lostAndUnknown": { "summary": "Lost and inconclusive lifecycle states", "value": { "success": true, "status": 200, "type": "playlist_spotify_rankings", "data": { "entity": { "type": "playlist", "spotifyId": "2SM6rniZl84fEyMCB5KMQB" }, "historyWindow": { "value": "60d", "from": "2026-06-21T12:00:00.000Z", "to": "2026-08-20T12:00:00.000Z" }, "summary": { "total": 2, "active": 0, "lost": 1, "unknown": 1, "estimatedPositionVolume": 1320 }, "rankings": [ { "keyword": "gym music", "market": "us", "status": "lost", "freshness": "fresh", "movement": "declining", "currentPosition": null, "previousPosition": 7, "lastKnownPosition": 12, "positionChange": -5, "lastCheckedAt": "2026-08-19T12:00:00.000Z", "firstSeenInWindowAt": "2026-06-25T00:00:00.000Z", "lastSeenAt": "2026-08-10T00:00:00.000Z", "keywordMetrics": { "google": { "volume": 2400, "growth": -0.08, "demand": "steady" }, "spotify": { "followerReach": 820000, "followerGrowthRate": -1.2, "followerGrowthPerDay": -4.5, "followerGrowthPerDayTotal": -31.5, "playlistsWithData": 7, "competition": "easy", "momentum": "declining", "genreFocus": 0.57, "genres": [ { "name": "workout", "share": 1 } ] } }, "estimatedPositionVolume": 133, "history": [ { "observedAt": "2026-08-10T00:00:00.000Z", "position": 12 } ] }, { "keyword": "fitness motivation", "market": "ca", "status": "unknown", "freshness": "missing", "movement": "new", "currentPosition": null, "previousPosition": null, "lastKnownPosition": 20, "positionChange": null, "lastCheckedAt": null, "firstSeenInWindowAt": "2026-07-12T00:00:00.000Z", "lastSeenAt": "2026-07-12T00:00:00.000Z", "keywordMetrics": { "google": { "volume": 2900, "growth": 0, "demand": "steady" }, "spotify": { "followerReach": 0, "followerGrowthRate": 0, "followerGrowthPerDay": 0, "followerGrowthPerDayTotal": 0, "playlistsWithData": 0, "competition": "easy", "momentum": "stable_base", "genreFocus": 0, "genres": [] } }, "estimatedPositionVolume": 32, "history": [ { "observedAt": "2026-07-12T00:00:00.000Z", "position": 20 } ] } ], "pagination": { "page": 1, "limit": 25, "total": 2, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } } } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } ```