--- updatedAt: 2026-05-29T15:12:00.000Z agentTools: projectIndex: https://artisttools.readme.io/llms.txt --- # Get curator activity Returns a paginated timeline of track additions and removals across all playlists owned by a curator. Useful for monitoring a curator's playlist management patterns, identifying when botted curators add or remove tracks, or building an activity feed of a curator's behavior over time. # 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": { "/curators/{id}/activity": { "get": { "tags": [ "Curators" ], "summary": "Get curator activity", "description": "Returns a paginated timeline of track additions and removals across all playlists owned by a curator. Useful for monitoring a curator's playlist management patterns, identifying when botted curators add or remove tracks, or building an activity feed of a curator's behavior over time.", "parameters": [ { "$ref": "#/components/parameters/CuratorId" }, { "$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/ActivityArtistIds" }, { "$ref": "#/components/parameters/ActivityTrackIds" } ], "responses": { "200": { "$ref": "#/components/responses/CuratorActivityResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "parameters": { "CuratorId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "317z36irnyblvr3nm5ti5bjnufga" }, "description": "Spotify User ID of a curator" }, "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)" }, "ActivityArtistIds": { "name": "artistIds", "in": "query", "schema": { "type": "string", "example": "2PXRihjmDw1GiLfqkFLUWH,09L3cUdx0hq6qn5bKuJJ4I" }, "description": "Comma-separated list of Spotify Artist 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" } } }, "PlaylistActivityChangeEvent": { "type": "object", "description": "A single track add/remove event for a playlist", "properties": { "meta": { "$ref": "#/components/schemas/TrackChangeEventMeta" }, "event": { "$ref": "#/components/schemas/TrackChangeEventDetail" }, "happenedAt": { "type": "string", "format": "date-time", "description": "When the event occurred" }, "track": { "type": "object", "nullable": true, "description": "Summary of the track involved", "properties": { "spotifyId": { "type": "string" }, "name": { "type": "string" }, "coverArtUrl": { "type": "string" }, "artistNames": { "type": "array", "items": { "type": "string" } }, "artistSpotifyIds": { "type": "array", "items": { "type": "string" } }, "streams": { "type": "integer", "nullable": true }, "popularity": { "type": "integer", "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" } } } }, "CuratorActivityResponse": { "description": "Paginated timeline of track additions and removals across all playlists owned by a curator", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "curator_activity" ] }, "data": { "allOf": [ { "$ref": "#/components/schemas/ActivityPagination" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Map of Spotify Playlist ID to playlist object and its change events. Each key is a Spotify Playlist ID.", "additionalProperties": { "type": "object", "properties": { "playlist": { "type": "object", "description": "Playlist metadata" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistActivityChangeEvent" } } } }, "example": { "37i9dQZF1DWUBCiFp3lAyi": { "playlist": "Full artist.tools Playlist object (see Playlist schema)", "changes": [ { "meta": { "dsp": "spotify", "dspTrackId": "456xBIOmLRoLzCvCzZrWge", "dspPlaylistId": "37i9dQZF1DWUBCiFp3lAyi", "dspArtistIds": [ "09L3cUdx0hq6qn5bKuJJ4I" ] }, "event": { "type": "ADDED", "botted": true, "ownerSpotifyId": "31ksq6scdaefpnbfqjyyax62beke", "position": 1 }, "happenedAt": "2025-06-10T03:45:00.000Z", "track": { "spotifyId": "456xBIOmLRoLzCvCzZrWge", "name": "Starboy", "coverArtUrl": "https://i.scdn.co/image/ab67616d00001e02a048...", "artistNames": [ "The Weeknd", "Daft Punk" ], "artistSpotifyIds": [ "1Xyo4u8uXC1ZmMpatF05PJ", "4tZwfgrHOc3mvqYlEYSvVi" ], "streams": 2800000000, "popularity": 82 } } ] } } } } } ] } } } ] } } } }, "BadRequest": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } ```