--- updatedAt: 2026-05-29T15:18:26.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Get track ISRC occurences Returns all Spotify track occurrences resolved for an ISRC. # 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": { "/tracks/isrc/{isrc}/occurences": { "get": { "tags": [ "Tracks" ], "summary": "Get track ISRC occurences", "description": "Returns all Spotify track occurrences resolved for an ISRC.", "parameters": [ { "$ref": "#/components/parameters/TrackISRC" }, { "$ref": "#/components/parameters/Lean" }, { "$ref": "#/components/parameters/Update" }, { "$ref": "#/components/parameters/DatabaseOnly" }, { "$ref": "#/components/parameters/IncludeSnapshots" } ], "responses": { "200": { "$ref": "#/components/responses/TrackISRCOccurencesResponse" }, "400": { "$ref": "#/components/responses/BadRequest" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "TrackISRC": { "name": "isrc", "in": "path", "required": true, "schema": { "type": "string", "example": "USUG12000497" }, "description": "International Standard Recording Code. Accepts a 12-character ISRC such as `USUG12000497`; common separators and an `isrc:` prefix are normalized before lookup." }, "Lean": { "name": "lean", "in": "query", "schema": { "type": "boolean" }, "description": "Returns database-only data, unless the entity has not been ingested yet. Useful for speed." }, "Update": { "name": "update", "in": "query", "schema": { "type": "boolean" }, "description": "Force the service to refresh the data before returning. This will increase latency but provide the most up-to-date data." }, "DatabaseOnly": { "name": "databaseOnly", "in": "query", "schema": { "type": "boolean" }, "description": "Performs a database-only lookup, skipping external API calls. Useful for speed, or testing if we've ingested the data." }, "IncludeSnapshots": { "name": "includeSnapshots", "in": "query", "schema": { "type": "boolean" }, "description": "Include historical snapshots." } }, "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" ] }, "Track": { "type": "object", "description": "Track model", "properties": { "_id": { "type": "string", "description": "Internal database ID" }, "spotifyId": { "type": "string", "description": "Spotify ID of the track" }, "name": { "type": "string", "description": "Name of the track" }, "coverArtUrl": { "type": "string", "description": "URL of the track's cover art" }, "popularity": { "type": "integer", "description": "Popularity score of the track" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date the track was ingested by artist.tools" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date the track was last updated in our database, for any reason" }, "dataUpdatedAt": { "type": "string", "format": "date-time", "description": "Date the track's core metrics were last updated" }, "isRemoved": { "type": "boolean", "description": "Whether the track has been removed from Spotify" }, "entityType": { "type": "string", "enum": [ "track" ], "description": "Entity type identifier" }, "artistData": { "type": "array", "description": "Artist information for the track", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the artist" }, "spotifyId": { "type": "string", "description": "Spotify ID of the artist" } } } }, "audioPreviewUrl": { "type": "string", "nullable": true, "description": "URL of the track's audio preview, if available" }, "copyright": { "type": "string", "description": "Copyright information for the track" }, "explicit": { "type": "boolean", "description": "Whether the track is explicit" }, "isrc": { "type": "string", "description": "International Standard Recording Code of the track" }, "releasedAt": { "type": "string", "format": "date-time", "description": "Date the track was released" }, "playlistSummary": { "type": "object", "description": "Summary of the track's presence in playlists, based on data from artist.tools", "properties": { "total": { "type": "integer", "description": "Total number of playlists the track is in" }, "followerReach": { "type": "integer", "description": "Total number of followers of the playlists the track is in" }, "fraud": { "type": "integer", "description": "Number of playlists the track is in that are detected as botted" }, "fraudSpotifyIds": { "type": "array", "items": { "type": "string" }, "description": "Spotify IDs of the playlists the track is in that are detected as botted" } } }, "streams": { "type": "integer", "description": "Total number of streams of the track" }, "shazam": { "type": "object", "description": "Shazam enrichment, when available. Playlist track responses use stored enrichment; missing fields do not imply zero.", "properties": { "count": { "type": "number", "description": "Latest available Shazam recognition count." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Genres associated with the matched recording." }, "audioAnalysis": { "type": "object", "description": "Audio features from the matched recording, when available. Individual features may be absent.", "properties": { "melodicness": { "type": "number", "minimum": 0, "maximum": 1 }, "acousticness": { "type": "number", "minimum": 0, "maximum": 1 }, "valence": { "type": "number", "minimum": 0, "maximum": 1 }, "danceability": { "type": "number", "minimum": 0, "maximum": 1 }, "energy": { "type": "number", "minimum": 0, "maximum": 1 }, "bpm": { "type": "number", "description": "Tempo in beats per minute.", "exclusiveMinimum": true, "minimum": 0, "maximum": 400 } } } } }, "tiktok": { "type": "object", "description": "TikTok enrichment, when available. Missing count does not imply zero.", "properties": { "count": { "type": "number", "description": "Latest available TikTok video count for the matched sound." } } }, "snapshots": { "type": "array", "items": { "type": "object" }, "description": "Historical snapshots of the track" } } } }, "responses": { "TrackISRCOccurencesResponse": { "description": "Tracks resolved for an ISRC", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "track_isrc_occurences" ], "description": "Response type for ISRC occurrence lookups" }, "data": { "type": "array", "description": "All Spotify track objects resolved for the requested ISRC.", "items": { "$ref": "#/components/schemas/Track" } } }, "required": [ "type", "data" ] } ] }, "examples": { "resolvedOccurences": { "summary": "Resolved ISRC occurrences", "value": { "success": true, "status": 200, "type": "track_isrc_occurences", "data": [ { "spotifyId": "1irAliF0T8sLIOPJp6n7rU", "name": "Blinding Lights", "coverArtUrl": "https://i.scdn.co/image/ab67616d00001e028863bc11d2aa12b54f5aeb36", "popularity": 88, "entityType": "track", "artistData": [ { "name": "The Weeknd", "spotifyId": "1Xyo4u8uXC1ZmMpatF05PJ" } ], "isrc": "USUG12000497", "streams": 4200000000, "playlistSummary": { "total": 1250, "followerReach": 85000000, "fraud": 3 } } ] } }, "noOccurences": { "summary": "Valid ISRC with no resolved occurrences", "value": { "success": true, "status": 200, "type": "track_isrc_occurences", "data": [] } } } } } }, "BadRequest": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } ```