Skip to content

Users

User operations live under client.users.

Methods

Method Returns Description
get_current_profile() CurrentUser Fetch the current user's profile
get_top_artists(time_range=None, limit=None, offset=None) Page[Artist] Fetch the current user's top artists
get_top_tracks(time_range=None, limit=None, offset=None) Page[Track] Fetch the current user's top tracks
get_followed_artists(after=None, limit=None) CursorPage[Artist] Fetch artists followed by the current user

Required scopes

Spotify requires user-scoped access tokens for these endpoints. Request the scopes that match the methods you call: user-read-private for get_current_profile(), user-top-read for top artists and tracks, and user-follow-read for get_followed_artists(). For follow management and saved-item checks, use client.library instead.

Examples

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your-access-token") as client:
    me = client.users.get_current_profile()
    top_tracks = client.users.get_top_tracks(
        time_range="short_term",
        limit=5,
    )
    followed = client.users.get_followed_artists(limit=5)

import asyncio
from spotify_sdk import AsyncSpotifyClient


async def main() -> None:
    async with AsyncSpotifyClient(access_token="your-access-token") as client:
        me = await client.users.get_current_profile()
        top_tracks = await client.users.get_top_tracks(
            time_range="short_term",
            limit=5,
        )
        followed = await client.users.get_followed_artists(limit=5)


asyncio.run(main())

API details

The sync client mirrors these methods, minus the await keywords.

Bases: AsyncBaseService

Operations for Spotify users.

get_current_profile() async

Get detailed profile information about the current user.

Returns:

Type Description
CurrentUser

The current user's profile details.

get_followed_artists(after=None, limit=None) async

Get the current user's followed artists.

Parameters:

Name Type Description Default
after str | None

The last artist ID retrieved from the previous request.

 None
limit int | None

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

 None

Returns:

Type Description
CursorPage[Artist]

A cursor-paginated list of followed artists.

get_top_artists(time_range=None, limit=None, offset=None) async

Get the current user's top artists.

Parameters:

Name Type Description Default
time_range TimeRange | None

Over what time frame the affinities are computed. Valid values are long_term, medium_term, and short_term.

 None
limit int | None

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

 None
offset int | None

The index of the first item to return. Default: 0.

 None

Returns:

Type Description
Page[Artist]

A paginated list of the current user's top artists.

Raises:

Type Description
ValueError

If time_range is invalid.

get_top_tracks(time_range=None, limit=None, offset=None) async

Get the current user's top tracks.

Parameters:

Name Type Description Default
time_range TimeRange | None

Over what time frame the affinities are computed. Valid values are long_term, medium_term, and short_term.

 None
limit int | None

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

 None
offset int | None

The index of the first item to return. Default: 0.

 None

Returns:

Type Description
Page[Track]

A paginated list of the current user's top tracks.

Raises:

Type Description
ValueError

If time_range is invalid.