Get playlist by Spotify ID

get

https://api.artist.tools/v2/playlists/{id}

Returns a single playlist with optional flags to control how much data is returned or whether the database should be refreshed first. Playlist objects include track summary fields and, when available, tracks.items with per-track metadata. Keyword snapshots are opt-in, default to a rolling 30-day window, and use v2 only unless legacy history is explicitly enabled. Legacy history ends on November 18, 2025 (UTC). Legacy access is strongly discouraged unless your application specifically requires that older data; it is monitored and may be subject to separate usage limits. See includeLegacyKeywordSnapshots before enabling it. Snapshot flags accept true or false; invalid flags or keyword snapshot bounds return HTTP 400.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Spotify Playlist ID

Query Params

lean

boolean

Returns database-only data, unless the entity has not been ingested yet. Useful for speed.

update

boolean

Force the service to refresh the data before returning. This will increase latency but provide the most up-to-date data.

databaseOnly

boolean

Performs a database-only lookup, skipping external API calls. Useful for speed, or testing if we've ingested the data.

includeSnapshots

boolean

Include historical snapshots.

includeDiscoveredOnAnalysis

boolean

Include the last Discovered On Analysis snapshot for this playlist

includeKeywordSnapshots

boolean

Defaults to false

Include keyword ranking snapshots in keywordSnapshots. Omitted or false skips keyword snapshot reads. Defaults to the last 30 days of v2 data across all keywords and markets. Regular includeSnapshots does not enable keyword snapshots. Older legacy history requires includeLegacyKeywordSnapshots=true and an age window extending before November 19, 2025.

keywordSnapshotsMaxAgeDays

integer

≥ 1

Defaults to 30

Rolling age window for keyword snapshots, in days (snapshot timestamp >= now minus this value). Applies only when includeKeywordSnapshots=true. A positive integer overrides the 30-day default; zero, negative, fractional, invalid, or unrepresentable date ranges return HTTP 400. Unless includeLegacyKeywordSnapshots=true, the API automatically caps the effective age to the largest whole-day window since v2 began on November 19, 2025 (UTC). This cap grows daily rather than remaining fixed at 300 days. A large value such as 99999 is capped to that v2 window and never enables legacy reads by itself. Explicit legacy opt-in removes this cap, allowing the requested window to reach older history. Broad windows may increase latency and response size.

keywordSnapshotsLimit

integer

≥ 1

Optional maximum number of keyword snapshot rows returned per playlist, newest first, across all keywords and markets and both sources when legacy is enabled. No limit is applied when omitted. This limit is applied after matching history is fetched and merged; it reduces response size, not database read volume. Use keywordSnapshotsMaxAgeDays to bound reads.

includeLegacyKeywordSnapshots

boolean

Defaults to false

Strongly discouraged unless your application specifically requires pre-v2 history. This option is provided for backward compatibility and historical coverage, not routine ranking tracking or new integrations. Do not enable it merely to request as much data as possible; use v2-only data whenever it meets your application requirements.

Coverage: legacy history ends on November 18, 2025 (UTC), with timestamps strictly before 2025-11-19T00:00:00Z. V2 history begins on November 19, 2025. Enabling legacy only adds available history before that boundary; it does not add newer coverage. Requires includeKeywordSnapshots=true and a keywordSnapshotsMaxAgeDays window reaching before that boundary. The 30-day default still applies unless overridden. Request only the historical window your application needs.

Format and performance: legacy snapshots are not guaranteed to have any specific or consistent payload format; fields may differ from v2 or be missing. Legacy reads can increase request latency by one or two orders of magnitude (roughly 10-100x), depending on the playlist and requested history; this is not a latency guarantee.

Usage policy: use of this option is monitored. We reserve the right to apply separate usage limits to legacy reads, which may differ from standard playlist request limits. Sustained or excessive use may prompt us to contact the application owner to understand the use case and agree on appropriate access. Legacy usage may be limited or restricted following review.

Cannot be combined with collapseByKeyword=latestAndPrevious.

includeExtendedData

boolean

Include extended data (full curator object for playlists)

Responses

400

Invalid snapshot boolean, keyword snapshot age, limit, or incompatible legacy collapse options.

200Single playlist with follower metrics, quality analysis, curator info, and track summary

404Resource not found