--- updatedAt: 2026-05-29T15:12:00.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Get artist activity Returns a paginated timeline of playlist additions and removals for an artist's tracks. Useful for building an activity feed showing which playlists have picked up or dropped the artist over time, tracking the exact timing of botted playlist adds/removes, or mapping out how playlist placements lead into others. # 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": { "/artists/{id}/activity": { "get": { "tags": [ "Artists" ], "summary": "Get artist activity", "description": "Returns a paginated timeline of playlist additions and removals for an artist's tracks. Useful for building an activity feed showing which playlists have picked up or dropped the artist over time, tracking the exact timing of botted playlist adds/removes, or mapping out how playlist placements lead into others.", "parameters": [ { "$ref": "#/components/parameters/ArtistId" }, { "$ref": "#/components/parameters/ActivityPage" }, { "$ref": "#/components/parameters/ActivityPageSize" }, { "$ref": "#/components/parameters/ActivityStartDate" }, { "$ref": "#/components/parameters/ActivityEndDate" }, { "$ref": "#/components/parameters/ActivityEventType" }, { "$ref": "#/components/parameters/ActivityBotted" }, { "$ref": "#/components/parameters/ActivityTrackIds" }, { "$ref": "#/components/parameters/ActivityPlaylistIds" }, { "$ref": "#/components/parameters/ActivityOwnerIds" } ], "responses": { "200": { "$ref": "#/components/responses/ArtistActivityResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "ArtistId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "2PXRihjmDw1GiLfqkFLUWH" }, "description": "Artist ID" }, "ActivityPage": { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 100 }, "description": "Page number (1-indexed, max 100). If you need deeper results, narrow your date range with startDate/endDate." }, "ActivityPageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 25 }, "description": "Number of items per page (max 25)" }, "ActivityStartDate": { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00.000Z" }, "description": "Only return events that happened at or after this date (ISO 8601). Must be before endDate if both are provided." }, "ActivityEndDate": { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2025-06-01T00:00:00.000Z" }, "description": "Only return events that happened at or before this date (ISO 8601). Must be after startDate if both are provided." }, "ActivityEventType": { "name": "eventType", "in": "query", "schema": { "type": "string", "enum": [ "ADDED", "REMOVED" ] }, "description": "Filter by event type. If omitted, both additions and removals are returned." }, "ActivityBotted": { "name": "botted", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by whether the playlist involved was detected as botted. true = only botted, false = only non-botted, omit = all." }, "ActivityTrackIds": { "name": "trackIds", "in": "query", "schema": { "type": "string", "example": "3AjSfp5FDvwtMU9XBsbS8j,456xBIOmLRoLzCvCzZrWge" }, "description": "Comma-separated list of Spotify Track IDs to filter by (max 10)" }, "ActivityPlaylistIds": { "name": "playlistIds", "in": "query", "schema": { "type": "string", "example": "37i9dQZF1DWUBCiFp3lAyi,37i9dQZF1DX0XUsuxWHRQd" }, "description": "Comma-separated list of Spotify Playlist IDs to filter by (max 10)" }, "ActivityOwnerIds": { "name": "ownerIds", "in": "query", "schema": { "type": "string", "example": "spotify,topsify" }, "description": "Comma-separated list of playlist owner Spotify User IDs to filter by (max 10)" } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "status": { "type": "integer", "example": 200 } }, "required": [ "success", "status" ] }, "ActivityPagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number", "example": 1 }, "pageSize": { "type": "integer", "description": "Number of items per page", "example": 25 }, "hasNextPage": { "type": "boolean", "description": "Whether more pages are available after the current page" }, "hasPrevPage": { "type": "boolean", "description": "Whether pages exist before the current page" } } }, "TrackChangeEventMeta": { "type": "object", "properties": { "dsp": { "type": "string", "example": "spotify" }, "dspTrackId": { "type": "string", "description": "Spotify Track ID", "example": "3AjSfp5FDvwtMU9XBsbS8j" }, "dspPlaylistId": { "type": "string", "description": "Spotify Playlist ID", "example": "37i9dQZF1DWUBCiFp3lAyi" }, "dspArtistIds": { "type": "array", "items": { "type": "string" }, "description": "Spotify Artist IDs for the track" } } }, "TrackChangeEventDetail": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ADDED", "REMOVED" ], "description": "Whether the track was added to or removed from the playlist" }, "botted": { "type": "boolean", "description": "Whether the playlist was detected as botted at the time of the event" }, "ownerSpotifyId": { "type": "string", "description": "Spotify User ID of the playlist owner" }, "position": { "type": "integer", "nullable": true, "description": "Track position in the playlist at the time of the event" } } }, "TrackActivityChangeEvent": { "type": "object", "description": "A single playlist add/remove event for a track", "properties": { "meta": { "$ref": "#/components/schemas/TrackChangeEventMeta" }, "event": { "$ref": "#/components/schemas/TrackChangeEventDetail" }, "happenedAt": { "type": "string", "format": "date-time", "description": "When the event occurred" }, "playlist": { "type": "object", "nullable": true, "description": "Summary of the playlist involved", "properties": { "spotifyId": { "type": "string" }, "name": { "type": "string" }, "coverArtUrl": { "type": "string" }, "followers": { "type": "integer" }, "qualityScore": { "type": "number", "nullable": true } } } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "success", "error", "status" ] } }, "responses": { "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ArtistActivityResponse": { "description": "Paginated timeline of playlist additions and removals for an artist's tracks", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "artist_activity" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/ActivityPagination" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Map of Spotify Track ID to track object and its change events. Each key is a Spotify Track ID.", "additionalProperties": { "type": "object", "properties": { "track": { "type": "object", "description": "Track metadata" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/TrackActivityChangeEvent" } } } }, "example": { "3AjSfp5FDvwtMU9XBsbS8j": { "track": "Full artist.tools Track object (see Track schema)", "changes": [ { "meta": { "dsp": "spotify", "dspTrackId": "3AjSfp5FDvwtMU9XBsbS8j", "dspPlaylistId": "37i9dQZF1DWUBCiFp3lAyi", "dspArtistIds": [ "2PXRihjmDw1GiLfqkFLUWH" ] }, "event": { "type": "ADDED", "botted": false, "ownerSpotifyId": "spotify", "position": 12 }, "happenedAt": "2025-03-15T08:23:41.000Z", "playlist": { "spotifyId": "37i9dQZF1DWUBCiFp3lAyi", "name": "Chill Vibes", "coverArtUrl": "https://i.scdn.co/image/ab67706f000000025f...", "followers": 1250000, "qualityScore": 85 } } ] } } } } } ] } } } ] } } } }, "BadRequest": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } ```