Get a playlist's Spotify Rankings

get

https://api.artist.tools/v2/playlists/{id}/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Spotify Playlist ID

Query Params

string

length ≤ 150

Case-insensitive keyword search.

market

string

^[a-zA-Z]{2}$

Supported two-letter keyword market. Omit to include every market.

status

string

enum

Defaults to all

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.

Allowed:

movement

string

enum

Movement between the newest and previous distinct daily appearance. Omit to include all movement states.

Allowed:

positionMin

integer

1 to 50

Defaults to 1

Best last-known Spotify position to include. Must be less than or equal to positionMax.

positionMax

integer

1 to 50

Defaults to 50

Worst last-known Spotify position to include. Must be greater than or equal to positionMin.

historyWindow

string

enum

Defaults to 30d

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.

Allowed:

includeHistory

boolean

Defaults to true

When false, history arrays are omitted. Lifecycle timestamps still use stored observations.

sortBy

string

enum

Defaults to position

Primary sort field. position uses lastKnownPosition; lastSeenAt uses the newest stored appearance. Market and keyword are stable tie-breakers.

Allowed:

sortDirection

string

enum

Sort direction. Google and playlist ranking endpoints default to asc; Press Mentions defaults to desc.

Allowed:

page

integer

≥ 1

Defaults to 1

One-based result page. Invalid values return HTTP 400.

limit

integer

1 to 100

Defaults to 25

Primary rows per page. Invalid values are rejected rather than clamped.

Responses

200Stored Spotify keyword rankings for one playlist.

400Client error

404Resource not found