--- updatedAt: 2026-08-20T14:44:30.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Get a playlist's Discovered On analysis Returns the latest analysis of whether the artists carried by this playlist show the playlist in Spotify's `Discovered On` section. The endpoint is cache-first: persisted snapshots up to 30 days old are returned without rerunning the analysis, while older snapshots are refreshed automatically. A fresh Spotify analysis also runs when no snapshot exists, or when `update=true` is supplied and the latest snapshot is at least 24 hours old. If `update=true` is supplied within 24 hours of the latest analysis, that cached snapshot is returned with a root-level `details` explanation. Fresh analyses inspect the playlist, up to 750 unique primary artists, each artist's Spotify monthly-listener and top-city data, and each artist's top 50 `Discovered On` playlists, so they are slower and more expensive than cached reads. # 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/{id}/discovered-on-analysis": { "get": { "tags": [ "Playlists" ], "summary": "Get a playlist's Discovered On analysis", "description": "Returns the latest analysis of whether the artists carried by this playlist show the playlist in Spotify's `Discovered On` section. The endpoint is cache-first: persisted snapshots up to 30 days old are returned without rerunning the analysis, while older snapshots are refreshed automatically. A fresh Spotify analysis also runs when no snapshot exists, or when `update=true` is supplied and the latest snapshot is at least 24 hours old. If `update=true` is supplied within 24 hours of the latest analysis, that cached snapshot is returned with a root-level `details` explanation. Fresh analyses inspect the playlist, up to 750 unique primary artists, each artist's Spotify monthly-listener and top-city data, and each artist's top 50 `Discovered On` playlists, so they are slower and more expensive than cached reads.", "parameters": [ { "$ref": "#/components/parameters/PlaylistId" }, { "name": "update", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Leave omitted or set to `false` to return a persisted snapshot that is no more than 30 days old; older snapshots are refreshed automatically. Set to `true` to request a fresh analysis. An explicit refresh runs only when the latest snapshot is at least 24 hours old; newer snapshots are returned from cache with a root-level `details` explanation. Values other than `true` or `false` return HTTP 400." } ], "responses": { "200": { "$ref": "#/components/responses/PlaylistDiscoveredOnAnalysisResponse" }, "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" } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "integer", "example": 200 } }, "required": [ "success", "status" ] }, "DiscoveredOnDemographic": { "type": "object", "description": "A Spotify listener-location signal. These locations belong to an artist's audience; they are not the playlist's followers and should be treated as an estimate of the playlist audience.", "properties": { "city": { "type": "string", "description": "Highest-listener city observed for this country among the contributing artist data.", "example": "Los Angeles" }, "country": { "type": "string", "description": "Country name reported by Spotify for the listener location.", "example": "United States" }, "region": { "type": "string", "nullable": true, "description": "State, province, or region reported by Spotify when available.", "example": "California" }, "listenerCount": { "type": "integer", "description": "Artist monthly listeners attributed to the contributing city records. In `topIncludedDemographics`, this is summed across supporting artists and is a ranking signal, not a count of playlist followers.", "example": 182400 }, "score": { "type": "number", "description": "Internal location-ranking weight. Repeated country appearances within and across supporting artists increase this value; it is not a percentage or listener count.", "example": 13 }, "occurrenceCount": { "type": "integer", "description": "Number of artist top-city records that contributed to this country result.", "example": 5 }, "supportingArtistCount": { "type": "integer", "description": "Number of sampled included artists whose top-city data contributed to this combined location. Present on the summary demographic results.", "example": 3 } }, "required": [ "city", "country", "listenerCount" ] }, "DiscoveredOnTrackPosition": { "type": "object", "description": "One track by this artist found in the analyzed playlist.", "properties": { "position": { "type": "integer", "minimum": 1, "description": "One-based position of the artist's track in the playlist at analysis time. **artist.tools app:** every `positions[].position` value is shown, comma-separated, in the artist table's `Playlist Position` column.", "example": 12 }, "addedAt": { "type": "string", "format": "date-time", "description": "When Spotify says this track was added to the playlist.", "example": "2026-07-29T14:22:10.000Z" }, "daysAgo": { "type": "integer", "minimum": 0, "description": "Whole days between `addedAt` and the time this snapshot was generated. This stored value does not continue increasing when a cached snapshot is read later. **artist.tools app:** `positions[0].daysAgo` is shown in the artist table's `Days In Playlist` column.", "example": 22 } }, "required": [ "position", "addedAt", "daysAgo" ] }, "DiscoveredOnArtist": { "type": "object", "description": "An artist represented in the playlist. The containing `included` or `excluded` array says whether the playlist was visible in that artist's Spotify `Discovered On` top 50 when the analysis ran.", "properties": { "spotifyId": { "type": "string", "description": "Spotify artist ID. **artist.tools app:** used as the destination of the artist link in the analysis tables.", "example": "5INjqkS1o8h1imAzPqGZBb" }, "name": { "type": "string", "description": "Artist name from Spotify. **artist.tools app:** shown in the analysis tables' `Artist` column.", "example": "Tame Impala" }, "coverArtUrl": { "type": "string", "format": "uri", "description": "Artist profile image URL, or the artist.tools fallback image when Spotify has no avatar. **artist.tools app:** shown as the avatar in the `Artist` column.", "example": "https://i.scdn.co/image/ab6761610000e5ebexample" }, "monthlyListeners": { "type": "integer", "minimum": 0, "description": "Artist's Spotify monthly listeners at analysis time. **artist.tools app:** shown in the analysis tables' `Monthly Listeners` column.", "example": 24700000 }, "demographic": { "type": "array", "description": "Artist's Spotify top listener cities. These are artist-audience measurements, not playlist-follower locations. **artist.tools app:** `demographic[0]` supplies the city, country, and listener count shown in the artist table's `Top City` column.", "items": { "$ref": "#/components/schemas/DiscoveredOnDemographic" } }, "discoveredOnPosition": { "type": "integer", "minimum": 0, "description": "One-based rank of this playlist in the artist's Spotify `Discovered On` top 50. Included artists have ranks 1-50; excluded artists normally have 0 because the playlist was absent. **artist.tools app:** shown with a `#` prefix in the included-artists table's `Discovered On Position` column; the excluded-artists table does not display this field.", "example": 4 }, "positions": { "type": "array", "description": "Every playlist track attributed to this artist, with its playlist position and add date. **artist.tools app:** backs the `Days In Playlist` and `Playlist Position` columns; see the child-field descriptions for the exact mapping.", "items": { "$ref": "#/components/schemas/DiscoveredOnTrackPosition" } }, "trackCount": { "type": "integer", "minimum": 0, "description": "Number of this artist's track occurrences in the playlist; equivalent to `positions.length`.", "example": 2 }, "trackShare": { "type": "number", "minimum": 0, "maximum": 1, "description": "Share of analyzed playlist track occurrences attributed to this artist, from 0 to 1.", "example": 0.025 }, "weight": { "type": "number", "description": "Legacy signed artist contribution retained for compatibility. Positive values represent included artists; excluded artists contribute zero or negatively. Prefer the versioned `new*` fields for auditing the current score.", "example": 91.4 }, "legacyNormalizedListenerWeight": { "type": "number", "description": "Legacy 0-100 weight based on this artist's monthly listeners relative to the largest artist in the playlist.", "example": 91.4 }, "legacySignedWeight": { "type": "number", "description": "Legacy signed scoring contribution: positive for included artists and negative for excluded artists.", "example": 91.4 }, "newRawRepWeight": { "type": "number", "description": "Current-model raw representation weight derived from track share before artist-scale blending.", "example": 0.1581 }, "newScaleBlend": { "type": "number", "description": "Current-model multiplier blending track representation with the artist's absolute monthly-listener scale.", "example": 0.9481 }, "newRepWeight": { "type": "number", "description": "Current-model representation weight after applying `newScaleBlend`; used when averaging rank, difficulty, and competitiveness signals.", "example": 0.1499 }, "newEntryDifficulty": { "type": "number", "minimum": 0, "maximum": 1, "description": "Estimated difficulty, from 0 to 1, of appearing in this artist's `Discovered On`, based on monthly-listener scale.", "example": 0.936 }, "newRankQuality": { "type": "number", "minimum": 0, "maximum": 1, "description": "Quality of the playlist's `Discovered On` rank, from 0 to 1. Higher values mean a position closer to number 1; excluded artists receive 0.", "example": 0.9576 }, "newRawPos": { "type": "number", "minimum": 0, "maximum": 1, "description": "Raw rank-strength value before adjusting for artist size. It currently mirrors `newRankQuality`.", "example": 0.9576 }, "newSizeMult": { "type": "number", "minimum": 0, "maximum": 1, "description": "Artist-size multiplier applied to raw rank strength so high ranks for larger artists carry more evidence.", "example": 0.9392 }, "newAdjPos": { "type": "number", "minimum": 0, "maximum": 1, "description": "Final position-strength signal after combining entry difficulty, rank quality, and artist size.", "example": 0.9132 }, "newAbsoluteArtistScale": { "type": "number", "minimum": 0, "maximum": 1, "description": "Artist-size score from 0 to 1 based on absolute monthly listeners.", "example": 0.8962 }, "newRelativeScaleScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Artist-size score from 0 to 1 relative to the playlist's follower count.", "example": 0.6618 }, "newCompetitivenessComposite": { "type": "number", "minimum": 0, "maximum": 1, "description": "Combined absolute and relative artist-scale score used to calculate the playlist-level competitiveness factor.", "example": 0.7087 } }, "required": [ "spotifyId", "name", "monthlyListeners", "positions" ] }, "DiscoveredOnEdgeArtist": { "type": "object", "description": "The smallest- or largest-monthly-listener artist in a listener-stat bucket.", "properties": { "spotifyId": { "type": "string", "description": "Spotify artist ID." }, "name": { "type": "string", "description": "Artist name." }, "monthlyListeners": { "type": "integer", "description": "Artist's Spotify monthly listeners at analysis time." }, "trackCount": { "type": "integer", "description": "Number of this artist's track occurrences in the playlist." }, "discoveredOnPosition": { "type": "integer", "nullable": true, "description": "One-based `Discovered On` rank for an included artist, or null for an excluded artist." } } }, "DiscoveredOnListenerBucket": { "type": "object", "description": "Monthly-listener distribution for all, included, or excluded artists.", "properties": { "count": { "type": "integer", "description": "Number of artists in this bucket.", "example": 18 }, "avg": { "type": "number", "nullable": true, "description": "Arithmetic mean monthly listeners, or null when the bucket is empty.", "example": 3842100 }, "min": { "nullable": true, "description": "Artist with the fewest monthly listeners, or null when empty.", "allOf": [ { "$ref": "#/components/schemas/DiscoveredOnEdgeArtist" } ] }, "max": { "nullable": true, "description": "Artist with the most monthly listeners, or null when empty.", "allOf": [ { "$ref": "#/components/schemas/DiscoveredOnEdgeArtist" } ] } } }, "PlaylistDiscoveredOnAnalysis": { "type": "object", "description": "A persisted or newly generated snapshot of a playlist's effect on artist discovery. Field descriptions marked **artist.tools app:** identify values rendered by the current Meteor playlist overview; unmarked fields are API metadata, scoring inputs, or audit details that page does not display directly.", "properties": { "spotifyId": { "type": "string", "description": "Spotify playlist ID analyzed.", "example": "37i9dQZF1DWUBCiFp3lAyi" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this persisted snapshot was generated. Present on cached snapshots; an immediately generated response may omit it until persistence has assigned the timestamp. **artist.tools app:** rendered as the relative `Last analyzed ... ago` text in the `Discovered On Analysis` header.", "example": "2026-08-18T14:32:10.000Z" }, "updatedCount": { "type": "integer", "minimum": 1, "description": "Service accounting count for this generated response: one playlist plus the number of unique primary artists found in it. Returned only when a fresh analysis runs; omitted for cached snapshots.", "example": 19 }, "analysis": { "type": "object", "description": "Measurements captured during this analysis run, including top-level rollups and the per-artist evidence behind them.", "properties": { "duration": { "type": "integer", "minimum": 0, "description": "Wall-clock time in milliseconds spent generating the snapshot. This does not measure cache-read latency.", "example": 18432 }, "summary": { "type": "object", "description": "Playlist-level rollups derived from the included and excluded artist rows.", "properties": { "artists": { "type": "object", "description": "Artist coverage and estimated audience-location summary.", "properties": { "topIncludedDemographics": { "type": "array", "maxItems": 5, "description": "Ranked estimate of likely playlist-audience locations. It combines Spotify top-city data from up to ten included artists that rank this playlist in their top three `Discovered On` positions; when more than ten qualify, the ten with the fewest monthly listeners are sampled. These are the artists' listeners, not the playlist's followers. **artist.tools app:** supplies the ranked city and country rows in the playlist overview's `Listener Locations (Estimated)` section.", "items": { "$ref": "#/components/schemas/DiscoveredOnDemographic" } }, "percentInDiscoveredOn": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Percentage of analyzed playlist artists who show this playlist in their Spotify `Discovered On` top 50. Higher coverage can be a positive engagement signal and suggests the playlist may be helping listeners discover its artists. **artist.tools app:** this exact value is displayed as `Discovered On Coverage` with a `%` suffix.", "example": 67 } } }, "tracks": { "type": "object", "description": "Track-occurrence totals represented by the artist analysis.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total artist-track occurrences represented by the analysis. A collaboration can contribute to more than one artist record, so this may differ from the playlist's unique track count.", "example": 24 } } }, "quality": { "type": "object", "description": "Versioned listener-engagement score plus the measurements needed to audit it. This evaluates discovery evidence; it is separate from the playlist bot/quality score returned by playlist endpoints.", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Final listener-engagement score from 0 to 100: `proofScore × competitivenessFactor`, clamped to 0-100. **artist.tools app:** this exact value is displayed as `Listener Engagement`, formatted to two decimal places with a `%` suffix. The app derives its adjacent badge from this score: 70+ `Highly Engaged`, 40-69.99 `Engaged`, 10-39.99 `Slightly Engaged`, greater than 0 but below 10 `Barely Engaged`, and 0 `Not Engaged`.", "example": 72.4 }, "rating": { "type": "string", "enum": [ "Amazing", "Good", "Okay", "Bad" ], "description": "Plain-English API band for `score`: Amazing is 70+, Good is 40-69.99, Okay is 10-39.99, and Bad is below 10. The current artist.tools playlist overview does not display this value; its `Listener Engagement` badge is derived directly from `score` and uses different labels.", "example": "Amazing" }, "version": { "type": "integer", "description": "Current scoring-model version. Use this when comparing snapshots because model changes can alter scores independently of playlist behavior.", "example": 3 }, "proofScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Discovery-evidence score before the competitiveness multiplier. It combines artist coverage, track coverage, and strength of included `Discovered On` positions.", "example": 65.8 }, "competitivenessFactor": { "type": "number", "description": "Multiplier derived from the scale of included artists, currently ranging from 0.25 to 1.20. Values above 1 lift `proofScore`; values below 1 discount it.", "example": 1.1003 }, "competitivenessScore": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized 0-1 measure of how competitive the included artists are, using their absolute monthly listeners and their size relative to playlist followers.", "example": 0.8951 }, "weight": { "type": "number", "description": "Legacy normalized playlist weight retained for compatibility. Prefer `score`, `proofScore`, and `competitivenessFactor` for current decisions.", "example": 14.2 }, "metrics": { "type": "object", "description": "Raw counts and coverage percentages used by the score.", "properties": { "totalArtists": { "type": "integer", "description": "Unique primary artists successfully analyzed.", "example": 18 }, "includedArtists": { "type": "integer", "description": "Artists whose top 50 `Discovered On` playlists included this playlist.", "example": 12 }, "excludedArtists": { "type": "integer", "description": "Artists successfully checked whose top 50 did not include this playlist.", "example": 6 }, "totalTracks": { "type": "integer", "description": "Analyzed artist-track occurrences across the playlist.", "example": 24 }, "includedTracks": { "type": "integer", "description": "Track occurrences attributed to included artists.", "example": 17 }, "excludedTracks": { "type": "integer", "description": "Track occurrences attributed to excluded artists.", "example": 7 }, "percentArtistsIncluded": { "type": "number", "minimum": 0, "maximum": 100, "description": "Unrounded-model percentage of analyzed artists included in `Discovered On`; closely corresponds to summary `percentInDiscoveredOn`.", "example": 66.67 }, "percentTracksIncluded": { "type": "number", "minimum": 0, "maximum": 100, "description": "Percentage of analyzed artist-track occurrences attributed to included artists.", "example": 70.83 }, "playlistFollowers": { "type": "integer", "nullable": true, "description": "Playlist follower count used to compare artist scale with playlist scale. Null means follower data was unavailable.", "example": 1250000 } } }, "breakdown": { "type": "object", "description": "Intermediate current-model values. Ratios are 0-1; point fields contribute directly to the 0-100 `proofScore`.", "properties": { "proof": { "type": "object", "description": "Coverage and position-strength inputs that add up to `proofScore`.", "properties": { "rawArtistCoverageRatio": { "type": "number", "description": "Included artists divided by all analyzed artists.", "example": 0.6667 }, "difficultyWeightedArtistCoverageRatio": { "type": "number", "description": "Artist coverage weighted so inclusion for larger, harder-to-enter artists contributes more.", "example": 0.7412 }, "artistCoverageRatio": { "type": "number", "description": "Blend of raw and difficulty-weighted artist coverage used for scoring.", "example": 0.6928 }, "rawTrackCoverageRatio": { "type": "number", "description": "Track occurrences by included artists divided by all analyzed artist-track occurrences.", "example": 0.7083 }, "difficultyWeightedTrackCoverageRatio": { "type": "number", "description": "Track coverage weighted by artist entry difficulty.", "example": 0.7624 }, "trackCoverageRatio": { "type": "number", "description": "Blend of raw and difficulty-weighted track coverage used for scoring.", "example": 0.7272 }, "avgEntryDifficulty": { "type": "number", "description": "Representation-weighted 0-1 difficulty of entering included artists' `Discovered On` lists.", "example": 0.7841 }, "avgRankQuality": { "type": "number", "description": "Representation-weighted 0-1 quality of the playlist's ranks for included artists before artist-size adjustment.", "example": 0.8122 }, "avgPositionStrength": { "type": "number", "description": "Representation-weighted final 0-1 position strength after rank, entry difficulty, and artist size are combined.", "example": 0.7475 }, "artistCoveragePoints": { "type": "number", "description": "Artist-coverage contribution to `proofScore`; maximum 25 points in model version 3.", "example": 17.32 }, "trackCoveragePoints": { "type": "number", "description": "Track-coverage contribution to `proofScore`; maximum 30 points in model version 3.", "example": 21.82 }, "positionStrengthPoints": { "type": "number", "description": "Position-strength contribution to `proofScore`; maximum 45 points in model version 3.", "example": 33.64 } } }, "competitiveness": { "type": "object", "description": "Artist-scale inputs used to turn `proofScore` into the final score.", "properties": { "avgAbsoluteArtistScale": { "type": "number", "description": "Representation-weighted 0-1 artist-size score based on absolute monthly listeners.", "example": 0.7422 }, "avgRelativeScale": { "type": "number", "description": "Representation-weighted 0-1 artist-size score relative to playlist followers.", "example": 0.9333 }, "competitivenessScore": { "type": "number", "description": "Combined absolute and relative scale score used to derive the multiplier.", "example": 0.8951 }, "competitivenessFactor": { "type": "number", "description": "Multiplier applied to `proofScore`; duplicated here so the calculation can be audited inside the breakdown.", "example": 1.1003 } } } } }, "listenerStats": { "type": "object", "description": "Monthly-listener distributions for all artists and for the included/excluded groups.", "properties": { "all": { "$ref": "#/components/schemas/DiscoveredOnListenerBucket" }, "included": { "$ref": "#/components/schemas/DiscoveredOnListenerBucket" }, "excluded": { "$ref": "#/components/schemas/DiscoveredOnListenerBucket" } } }, "delta": { "type": "object", "description": "Differences between the current and retained legacy scoring models. These are model-comparison diagnostics, not changes over time.", "properties": { "score": { "type": "number", "description": "Current `score` minus `legacyScore`.", "example": 8.6 }, "proofVsLegacyBase": { "type": "number", "description": "Current `proofScore` minus the legacy raw inclusion-percentage base score.", "example": -0.9 }, "competitivenessLift": { "type": "number", "description": "Final current `score` minus `proofScore`; positive means competitiveness lifted the result.", "example": 6.6 } } }, "legacyVersion": { "type": "integer", "description": "Version of the retained legacy scoring model.", "example": 1 }, "legacyScore": { "type": "number", "description": "Final 0-100 score produced by the legacy model.", "example": 63.8 }, "legacyRating": { "type": "string", "description": "Plain-English rating produced from `legacyScore` using the same rating bands.", "example": "Good" }, "legacyBaseScore": { "type": "number", "description": "Legacy starting score: percentage of analyzed artists whose `Discovered On` included this playlist.", "example": 66.7 }, "legacyNormalizedWeight": { "type": "number", "description": "Average signed artist-listener adjustment used by the legacy model.", "example": -2.9 }, "legacyWeightedScore": { "type": "number", "description": "Legacy base score plus normalized weight before final 0-100 clamping.", "example": 63.8 }, "legacyTotalWeightRaw": { "type": "number", "description": "Sum of legacy signed per-artist weights before averaging across artists.", "example": -0.522 }, "legacyContributionSummary": { "type": "object", "description": "Separate sums of positive included-artist and negative excluded-artist legacy contributions.", "properties": { "includedWeight": { "type": "number", "description": "Sum of included artists' legacy signed weights.", "example": 784.5 }, "excludedWeight": { "type": "number", "description": "Sum of excluded artists' legacy signed weights; normally zero or negative.", "example": -836.7 } } } } } } }, "included": { "type": "array", "description": "Artists for whom Spotify listed this playlist in the artist's top 50 `Discovered On` playlists at analysis time. **artist.tools app:** these rows appear under the `Visible on N artist profiles` accordion.", "items": { "$ref": "#/components/schemas/DiscoveredOnArtist" } }, "excluded": { "type": "array", "description": "Artists successfully checked for whom this playlist was absent from the artist's top 50 `Discovered On` playlists at analysis time. An artist omitted from both arrays could not be analyzed because required Spotify data was unavailable. **artist.tools app:** these rows appear under the `Not visible on N artist profiles` accordion.", "items": { "$ref": "#/components/schemas/DiscoveredOnArtist" } } }, "required": [ "duration", "summary", "included", "excluded" ] } }, "required": [ "spotifyId", "analysis" ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "success", "error", "status" ] } }, "responses": { "PlaylistDiscoveredOnAnalysisResponse": { "description": "Latest cached or freshly generated Discovered On analysis for one playlist. Snapshots older than 30 days are refreshed automatically. When an `update=true` request is suppressed by the 24-hour refresh cooldown, the response includes root-level `details` explaining why cached data was returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "playlist_discovered_on_analysis" ], "description": "Response type for the playlist Discovered On analysis endpoint." }, "details": { "type": "string", "description": "Optional root-level response note. Present when `update=true` did not trigger a new analysis because the latest snapshot is less than 24 hours old.", "example": "Update skipped: this playlist already has a Discovered On analysis from the last 24 hours, so the cached snapshot was returned." }, "data": { "$ref": "#/components/schemas/PlaylistDiscoveredOnAnalysis" } }, "required": [ "type", "data" ] } ] }, "examples": { "cachedSnapshot": { "summary": "Existing persisted snapshot no more than 30 days old returned without rerunning Spotify analysis", "value": { "success": true, "status": 200, "type": "playlist_discovered_on_analysis", "data": { "spotifyId": "37i9dQZF1DWUBCiFp3lAyi", "createdAt": "2026-08-18T14:32:10.000Z", "analysis": { "duration": 18432, "summary": { "artists": { "topIncludedDemographics": [ { "city": "Los Angeles", "country": "United States", "region": "California", "listenerCount": 182400, "score": 13, "occurrenceCount": 5, "supportingArtistCount": 3 }, { "city": "London", "country": "United Kingdom", "region": "England", "listenerCount": 146200, "score": 9, "occurrenceCount": 4, "supportingArtistCount": 2 } ], "percentInDiscoveredOn": 67 }, "tracks": { "total": 24 }, "quality": { "score": 72.4, "weight": -2.9, "rating": "Amazing", "version": 3, "proofScore": 72.78, "competitivenessFactor": 0.9948, "competitivenessScore": 0.784, "metrics": { "totalArtists": 18, "includedArtists": 12, "excludedArtists": 6, "totalTracks": 24, "includedTracks": 17, "excludedTracks": 7, "percentArtistsIncluded": 66.67, "percentTracksIncluded": 70.83, "playlistFollowers": 1250000 }, "breakdown": { "proof": { "rawArtistCoverageRatio": 0.6667, "difficultyWeightedArtistCoverageRatio": 0.7412, "artistCoverageRatio": 0.6928, "rawTrackCoverageRatio": 0.7083, "difficultyWeightedTrackCoverageRatio": 0.7624, "trackCoverageRatio": 0.7272, "avgEntryDifficulty": 0.7841, "avgRankQuality": 0.8122, "avgPositionStrength": 0.7475, "artistCoveragePoints": 17.32, "trackCoveragePoints": 21.82, "positionStrengthPoints": 33.64 }, "competitiveness": { "avgAbsoluteArtistScale": 0.7422, "avgRelativeScale": 0.7945, "competitivenessScore": 0.784, "competitivenessFactor": 0.9948 } }, "listenerStats": { "all": { "count": 18, "avg": 3842100, "min": { "spotifyId": "0lowListenerArtistExample", "name": "New Artist", "monthlyListeners": 12500, "trackCount": 1, "discoveredOnPosition": null }, "max": { "spotifyId": "5INjqkS1o8h1imAzPqGZBb", "name": "Tame Impala", "monthlyListeners": 24700000, "trackCount": 2, "discoveredOnPosition": 4 } }, "included": { "count": 12, "avg": 5013150, "min": { "spotifyId": "1includedSmallArtist", "name": "Breaking Artist", "monthlyListeners": 84200, "trackCount": 1, "discoveredOnPosition": 2 }, "max": { "spotifyId": "5INjqkS1o8h1imAzPqGZBb", "name": "Tame Impala", "monthlyListeners": 24700000, "trackCount": 2, "discoveredOnPosition": 4 } }, "excluded": { "count": 6, "avg": 1500000, "min": { "spotifyId": "0lowListenerArtistExample", "name": "New Artist", "monthlyListeners": 12500, "trackCount": 1, "discoveredOnPosition": null }, "max": { "spotifyId": "2mVVjNmdjXZZDvhgQWiakk", "name": "Khruangbin", "monthlyListeners": 6300000, "trackCount": 1, "discoveredOnPosition": null } } }, "delta": { "score": 8.6, "proofVsLegacyBase": 6.08, "competitivenessLift": -0.38 }, "legacyVersion": 1, "legacyScore": 63.8, "legacyRating": "Good", "legacyBaseScore": 66.7, "legacyNormalizedWeight": -2.9, "legacyWeightedScore": 63.8, "legacyTotalWeightRaw": -0.522, "legacyContributionSummary": { "includedWeight": 784.5, "excludedWeight": -836.7 } } }, "included": [ { "spotifyId": "5INjqkS1o8h1imAzPqGZBb", "name": "Tame Impala", "coverArtUrl": "https://i.scdn.co/image/ab6761610000e5ebexample", "monthlyListeners": 24700000, "demographic": [ { "city": "Los Angeles", "country": "United States", "region": "California", "listenerCount": 68400 }, { "city": "London", "country": "United Kingdom", "region": "England", "listenerCount": 55200 } ], "discoveredOnPosition": 4, "positions": [ { "position": 12, "addedAt": "2026-07-29T14:22:10.000Z", "daysAgo": 20 }, { "position": 38, "addedAt": "2026-06-14T09:10:00.000Z", "daysAgo": 65 } ], "trackCount": 2, "trackShare": 0.0833, "weight": 91.4, "legacyNormalizedListenerWeight": 91.4, "legacySignedWeight": 91.4, "newRawRepWeight": 0.2887, "newScaleBlend": 0.9481, "newRepWeight": 0.2737, "newEntryDifficulty": 0.936, "newRankQuality": 0.9576, "newRawPos": 0.9576, "newSizeMult": 0.9392, "newAdjPos": 0.9132, "newAbsoluteArtistScale": 0.8962, "newRelativeScaleScore": 0.6618, "newCompetitivenessComposite": 0.7087 } ], "excluded": [ { "spotifyId": "2mVVjNmdjXZZDvhgQWiakk", "name": "Khruangbin", "coverArtUrl": "https://i.scdn.co/image/ab6761610000e5ebexample2", "monthlyListeners": 6300000, "demographic": [ { "city": "Sydney", "country": "Australia", "region": "New South Wales", "listenerCount": 21400 } ], "discoveredOnPosition": 0, "positions": [ { "position": 21, "addedAt": "2026-07-20T08:00:00.000Z", "daysAgo": 29 } ], "trackCount": 1, "trackShare": 0.0417, "weight": -11.2, "legacyNormalizedListenerWeight": 88.8, "legacySignedWeight": -11.2, "newRawRepWeight": 0.2041, "newScaleBlend": 0.875, "newRepWeight": 0.1786, "newEntryDifficulty": 0.82, "newRankQuality": 0, "newRawPos": 0, "newSizeMult": 0.829, "newAdjPos": 0, "newAbsoluteArtistScale": 0.75, "newRelativeScaleScore": 0.5878, "newCompetitivenessComposite": 0.6202 } ] } } } }, "updateSuppressed": { "summary": "update=true requested within the 24-hour cooldown, so cached data and a root-level explanation are returned", "value": { "success": true, "status": 200, "type": "playlist_discovered_on_analysis", "details": "Update skipped: this playlist already has a Discovered On analysis from the last 24 hours, so the cached snapshot was returned.", "data": { "spotifyId": "37i9dQZF1DWUBCiFp3lAyi", "createdAt": "2026-08-20T13:30:00.000Z", "analysis": { "duration": 17601, "summary": { "artists": { "topIncludedDemographics": [], "percentInDiscoveredOn": 0 }, "tracks": { "total": 0 }, "quality": { "score": 0, "rating": "Bad", "version": 3 } }, "included": [], "excluded": [] } } } }, "forcedRefresh": { "summary": "Fresh snapshot generated because no cache existed, the cache was older than 30 days, or update=true was supplied for a snapshot at least 24 hours old; this example playlist had no analyzable artists", "value": { "success": true, "status": 200, "type": "playlist_discovered_on_analysis", "data": { "spotifyId": "37i9dQZF1DWUBCiFp3lAyi", "updatedCount": 1, "analysis": { "duration": 17601, "summary": { "artists": { "topIncludedDemographics": [], "percentInDiscoveredOn": 0 }, "tracks": { "total": 0 }, "quality": { "score": 0, "rating": "Bad", "version": 3 } }, "included": [], "excluded": [] } } } } } } } }, "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" } } } } } } } ```