Skip to main content

​
Overview

The EpisodeService (sync) and AsyncEpisodeService (async) provide methods for retrieving Spotify podcast episode information and managing saved episodes in the user’s library.
Both sync and async versions are available. Import EpisodeService for sync operations or AsyncEpisodeService for async operations.

​
Methods

​
get

Retrieve detailed information about a single podcast episode by its Spotify ID. 
async def get(id: str, market: str | None = None) -> Episode
​
id
str
required
The Spotify ID for the episode.
​
market
str | None
default:"None"
An ISO 3166-1 alpha-2 country code for availability. Episode availability may vary by region.
Returns: Episode - The complete episode object with metadata including show information, duration, and description. Raises: ValueError if id is empty. 
from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_token") as client:
    episode = await client.episodes.get("512ojhOuo1ktJprKbVcKyQ", market="US")
    
    print(f"Episode: {episode.name}")
    print(f"Show: {episode.show.name if episode.show else 'N/A'}")
    
    # Duration formatting
    duration_min = episode.duration_ms // 60000
    duration_sec = (episode.duration_ms % 60000) // 1000
    print(f"Duration: {duration_min}:{duration_sec:02d}")
    
    print(f"Release Date: {episode.release_date}")
    print(f"Language: {episode.language}")
    
    if episode.description:
        print(f"Description: {episode.description[:200]}...")
    
    # Audio preview (if available)
    if episode.audio_preview_url:
        print(f"Preview URL: {episode.audio_preview_url}")

​
get_saved

Retrieve podcast episodes saved in the current user’s library. 
async def get_saved(
    limit: int = 20,
    offset: int = 0,
    market: str | None = None
) -> Page[SavedEpisode]
​
limit
int
default:"20"
Maximum number of episodes to return. Valid range: 1-50.
​
offset
int
default:"0"
Index of the first episode to return (for pagination).
​
market
str | None
default:"None"
An ISO 3166-1 alpha-2 country code.
Returns: Page[SavedEpisode] - Paginated response containing saved episode objects with metadata.
Requires the user-library-read scope.
from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_token") as client:
    saved = await client.episodes.get_saved(limit=20, market="US")
    
    print(f"You have {saved.total} saved episodes")
    
    for saved_episode in saved.items:
        episode = saved_episode.episode
        print(f"\n{episode.name}")
        print(f"  Show: {episode.show.name if episode.show else 'N/A'}")
        print(f"  Added on: {saved_episode.added_at}")
        
        duration_min = episode.duration_ms // 60000
        duration_sec = (episode.duration_ms % 60000) // 1000
        print(f"  Duration: {duration_min}:{duration_sec:02d}")
    
    # Pagination
    if saved.next:
        print("\nMore episodes available...")
        next_page = await client.episodes.get_saved(limit=20, offset=20, market="US")
Use the added_at timestamp from SavedEpisode to sort or filter episodes by when they were saved.

​
Response Models

​
SavedEpisode

The SavedEpisode model wraps an episode with save metadata:
​
added_at
datetime
The timestamp when the episode was saved to the library.
​
episode
Episode
The full episode object.

​
Episode

The Episode model includes:
​
id
str
The Spotify ID for the episode.
​
name
str
The name of the episode.
​
description
str
A description of the episode (may contain HTML).
​
duration_ms
int
The episode length in milliseconds.
​
release_date
str
The date the episode was first released.
​
language
str
The language used in the episode (ISO 639 code).
​
show
SimplifiedShow | None
Information about the podcast show.
​
audio_preview_url
str | None
A URL to a 30-second preview (MP3 format) of the episode, if available.
  • Episode - Full episode object with complete metadata
  • SavedEpisode - Episode object with save timestamp
  • SimplifiedShow - Basic show information included with episodes
  • Page[T] - Paginated response wrapper

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us