History, Stats & Top Tracks
Recent status/listening history, aggregate statistics, and most-played tracks for a user.
History
GET /v1/users/:user_id/historyRecent status changes and listening history (track changes), most-recent first. Works even when the user is offline. Each list keeps up to the 100 most recent events.
Track-history entries now carry the full now_playing object — including
album_art_url, track_url, timestamps and duration_ms — so you can render
album art and progress straight from history. An extra ts field marks when the
event was recorded.
{
"success": true,
"data": {
"status_history": [{ "status": "online", "ts": 1700000000000 }],
"track_history": [
{
"source": "youtube_music",
"song": "NITE - SLOWED",
"artist": "ELVEN DIOR",
"album": "NITE",
"album_art_url": "https://media.discordapp.net/external/.../w544-h544-l90-rj",
"track_id": "QuXbIQ5DqxU",
"track_url": "https://music.youtube.com/watch?v=QuXbIQ5DqxU",
"timestamps": { "start": 1782409503000, "end": 1782409623000 },
"duration_ms": 120000,
"ts": 1700000000000
}
]
}
}Stats
GET /v1/users/:user_id/statsAggregate statistics for a user.
{
"success": true,
"data": {
"current_status": "online",
"last_seen": 1700000000000,
"tracks_today": 12,
"track_history_count": 47,
"is_monitored": true
}
}Prop
Type
Top Tracks
GET /v1/users/:user_id/top-tracks?limit=10A user's most-played tracks, ranked by play count (highest first). Each entry
carries the full now_playing details (incl. album_art_url) plus a
play_count. Works offline.
Every track change counts as one play. A track must have at least 2 plays to
appear in the list. limit defaults to 10 and is clamped to 1–50.
{
"success": true,
"data": {
"top_tracks": [
{
"source": "youtube_music",
"song": "NITE - SLOWED",
"artist": "ELVEN DIOR",
"album": "NITE",
"album_art_url": "https://media.discordapp.net/external/.../w544-h544-l90-rj",
"track_id": "QuXbIQ5DqxU",
"track_url": "https://music.youtube.com/watch?v=QuXbIQ5DqxU",
"timestamps": { "start": 1782409503000, "end": 1782409623000 },
"duration_ms": 120000,
"last_played": 1700000000000,
"play_count": 100
}
]
}
}Delete your data
Users can erase their own status history, listening history and most-played
data at any time with the ?forget confirm bot command.