Skip to main content

​
AsyncSpotifyClient

The AsyncSpotifyClient class is the main asynchronous client for interacting with the Spotify Web API. It provides async access to all Spotify API services through dedicated service attributes.

​
Constructor

AsyncSpotifyClient(
    access_token: str | None = None,
    *,
    client_id: str | None = None,
    client_secret: str | None = None,
    auth_provider: AsyncAuthProvider | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
)
Initialize a new async Spotify client instance.

​
Parameters

​
access_token
str | None
default:"None"
Spotify API access token. Use this if you already have a valid access token.
​
client_id
str | None
default:"None"
Spotify API client ID. Use with client_secret for client credentials flow.
​
client_secret
str | None
default:"None"
Spotify API client secret. Use with client_id for client credentials flow.
​
auth_provider
AsyncAuthProvider | None
default:"None"
Custom async auth provider for dynamic access token management. Provide this for advanced authentication scenarios.
​
timeout
float
default:"30.0"
Default request timeout in seconds. Controls how long to wait for API responses.
​
max_retries
int
default:"3"
Maximum number of retries for failed requests. The client will automatically retry failed requests up to this limit.
You must provide exactly one of the following:
  • access_token
  • Both client_id and client_secret
  • auth_provider
Providing multiple authentication methods will raise a ValueError.

​
Examples

from spotify_sdk import AsyncSpotifyClient

client = AsyncSpotifyClient(access_token="your_access_token")

​
Service Attributes

The AsyncSpotifyClient provides access to all Spotify API services through the following async service attributes:
​
albums
AsyncAlbumService
Async service for interacting with album endpoints. Get album details, tracks, and more.
​
artists
AsyncArtistService
Async service for interacting with artist endpoints. Get artist details, albums, top tracks, and related artists.
​
audiobooks
AsyncAudiobookService
Async service for interacting with audiobook endpoints. Get audiobook details and chapters.
​
chapters
AsyncChapterService
Async service for interacting with audiobook chapter endpoints. Get chapter details.
​
episodes
AsyncEpisodeService
Async service for interacting with podcast episode endpoints. Get episode details.
​
library
AsyncLibraryService
Async service for managing the user’s library. Save and retrieve albums, tracks, audiobooks, episodes, and shows.
​
playlists
AsyncPlaylistService
Async service for managing playlists. Create, update, and retrieve playlists and their items.
​
search
AsyncSearchService
Async service for searching Spotify content. Search for albums, artists, playlists, tracks, shows, episodes, and audiobooks.
​
shows
AsyncShowService
Async service for interacting with podcast show endpoints. Get show details and episodes.
​
tracks
AsyncTrackService
Async service for interacting with track endpoints. Get track details, audio features, and audio analysis.
​
users
AsyncUserService
Async service for interacting with user endpoints. Get user profiles and manage following.

​
Class Methods

​
from_client_credentials

@classmethod
AsyncSpotifyClient.from_client_credentials(
    *,
    client_id: str | None = None,
    client_secret: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
) -> AsyncSpotifyClient
Create an async client using the client credentials flow. This is a convenience method for creating a client with client credentials authentication.

​
Parameters

​
client_id
str | None
default:"None"
Spotify API client ID.
​
client_secret
str | None
default:"None"
Spotify API client secret.
​
timeout
float
default:"30.0"
Default request timeout in seconds.
​
max_retries
int
default:"3"
Maximum number of retries for failed requests.

​
Returns

A new AsyncSpotifyClient instance configured with client credentials authentication.

​
Example

from spotify_sdk import AsyncSpotifyClient

client = AsyncSpotifyClient.from_client_credentials(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

​
Instance Methods

​
close

async def close() -> None
Close the client and release resources. This async method should be awaited when you’re done using the client to properly clean up network connections and other resources.

​
Example

from spotify_sdk import AsyncSpotifyClient

client = AsyncSpotifyClient(access_token="your_access_token")
try:
    album = await client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
    print(album.name)
finally:
    await client.close()

​
Async Context Manager Support

The AsyncSpotifyClient supports the async context manager protocol, allowing you to use it with Python’s async with statement. The client will automatically close when the context exits.

​
Example

from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_access_token") as client:
    # Client is automatically closed when the block exits
    album = await client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
    tracks = await client.tracks.get(["track_id_1", "track_id_2"])
    results = await client.search.search("Bohemian Rhapsody", types=["track"])

​
Usage Examples

import asyncio
from spotify_sdk import AsyncSpotifyClient

async def main():
    async with AsyncSpotifyClient(access_token="your_access_token") as client:
        album = await client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
        print(f"Album: {album.name}")
        print(f"Artist: {album.artists[0].name}")
        print(f"Release Date: {album.release_date}")

asyncio.run(main())

​
Performance Benefits

The AsyncSpotifyClient is ideal for applications that need to make multiple concurrent API requests or integrate with async frameworks like FastAPI, aiohttp, or Starlette. Key benefits include:
  • Concurrent request execution with asyncio.gather()
  • Non-blocking I/O for better resource utilization
  • Seamless integration with async web frameworks
  • Improved throughput for batch operations

Build docs developers (and LLMs) love

Get started for freeTalk to us