Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonathan343/spotify-sdk/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The AsyncShowService provides operations for retrieving Spotify shows (podcasts), their episodes, and managing saved shows in the user’s library.
This service is available in both async (AsyncShowService) and sync (ShowService) variants.

​
Get Show

Retrieve detailed information about a specific show. 
async def get(self, id: str, market: str | None = None) -> Show
​
id
str
required
The Spotify ID for the show.
​
market
str | None
An ISO 3166-1 alpha-2 country code. If provided, only content available in that market will be returned.Example: "US", "GB", "CA"

​
Returns

​
Show
Show
Complete show object including metadata, publisher information, episodes preview, and availability.Key fields:
  • name - Show title
  • publisher - Show publisher/creator
  • description - Show description
  • episodes - Preview of recent episodes
  • total_episodes - Total number of episodes
  • languages - Available languages
  • images - Show cover images
  • explicit - Whether show contains explicit content

​
Example

from spotify_sdk import SpotifyClient

client = SpotifyClient(auth_token="your_token")

# Get show details
show = await client.shows.get("4rOoJ6Egrf8K2IrywzwOMk")

print(f"Show: {show.name}")
print(f"Publisher: {show.publisher}")
print(f"Total Episodes: {show.total_episodes}")
print(f"Description: {show.description}")

# Get show for specific market
show = await client.shows.get(
    "4rOoJ6Egrf8K2IrywzwOMk",
    market="US"
)

​
Get Show Episodes

Retrieve paginated list of episodes for a specific show. 
async def get_episodes(
    self,
    id: str,
    market: str | None = None,
    limit: int = 20,
    offset: int = 0,
) -> Page[SimplifiedEpisode]
​
id
str
required
The Spotify ID for the show.
​
market
str | None
An ISO 3166-1 alpha-2 country code for market availability filtering.
​
limit
int
Maximum number of episodes to return. Default: 20. Range: 1-50.
​
offset
int
Index of the first episode to return. Default: 0. Use with limit for pagination.

​
Returns

​
Page[SimplifiedEpisode]
Page[SimplifiedEpisode]
Paginated list of simplified episode objects.Episode fields include:
  • name - Episode title
  • description - Episode description
  • release_date - Release date
  • duration_ms - Duration in milliseconds
  • explicit - Explicit content flag
  • images - Episode images
  • languages - Available languages
  • audio_preview_url - Preview URL (if available)

​
Example

# Get first page of episodes
episodes = await client.shows.get_episodes(
    "4rOoJ6Egrf8K2IrywzwOMk",
    limit=20
)

for episode in episodes.items:
    duration_min = episode.duration_ms // 60000
    print(f"{episode.name} - {duration_min} minutes")
    print(f"Released: {episode.release_date}")

print(f"\nTotal episodes: {episodes.total}")

​
Get Saved Shows

Retrieve shows saved in the current user’s library. 
async def get_saved(
    self,
    limit: int = 20,
    offset: int = 0
) -> Page[SavedShow]
​
limit
int
Maximum number of shows to return. Default: 20. Range: 1-50.
​
offset
int
Index of the first show to return. Default: 0. Use for pagination.

​
Returns

​
Page[SavedShow]
Page[SavedShow]
Paginated list of saved show objects.SavedShow includes:
  • added_at - Timestamp when show was saved
  • show - Complete Show object with all metadata

​
Example

# Get user's saved shows
saved_shows = await client.shows.get_saved(limit=50)

for item in saved_shows.items:
    print(f"Added: {item.added_at}")
    print(f"Show: {item.show.name}")
    print(f"Publisher: {item.show.publisher}")
    print(f"Episodes: {item.show.total_episodes}")
    print("---")

print(f"\nTotal saved shows: {saved_shows.total}")

​
Complete Example

Here’s a comprehensive example showing how to work with shows: 
from spotify_sdk import SpotifyClient

async def explore_show(show_id: str):
    client = SpotifyClient(auth_token="your_token")
    
    # Get show details
    show = await client.shows.get(show_id, market="US")
    
    print(f"Show: {show.name}")
    print(f"Publisher: {show.publisher}")
    print(f"Total Episodes: {show.total_episodes}")
    print(f"Languages: {', '.join(show.languages)}")
    print(f"Explicit: {show.explicit}")
    print(f"\nDescription: {show.description}")
    
    # Get latest episodes
    print("\n=== Latest Episodes ===")
    episodes = await client.shows.get_episodes(
        show_id,
        market="US",
        limit=5
    )
    
    for i, episode in enumerate(episodes.items, 1):
        duration_min = episode.duration_ms // 60000
        print(f"\n{i}. {episode.name}")
        print(f"   Released: {episode.release_date}")
        print(f"   Duration: {duration_min} minutes")
        if episode.audio_preview_url:
            print(f"   Preview: {episode.audio_preview_url}")
    
    # Check user's saved shows
    saved = await client.shows.get_saved(limit=50)
    is_saved = any(item.show.id == show_id for item in saved.items)
    
    print(f"\nSaved in library: {is_saved}")

# Run the example
import asyncio
asyncio.run(explore_show("4rOoJ6Egrf8K2IrywzwOMk"))

​
Error Handling

try:
    # Attempt to get show with empty ID
    show = await client.shows.get("")  
except ValueError as e:
    print(f"Error: {e}")  # "id cannot be empty"

try:
    # Get episodes for invalid show ID
    episodes = await client.shows.get_episodes("invalid_id")
except Exception as e:
    # Handle API errors (404, etc.)
    print(f"API Error: {e}")
Use the market parameter when retrieving shows to ensure you only get content available in your target region.
Saved shows require user authentication with appropriate scopes (user-library-read for reading saved shows).

Build docs developers (and LLMs) love

Get started for freeTalk to us