Get User's Saved Episodes

Developing

GET

/me/episodes

category-library

Get a list of the episodes saved in the current Spotify user's library.

This API endpoint is in beta and could change without warning. Please share any feedback that you have, or issues that you discover, in our developer community forum.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.spotify.com/v1/me/episodes' \
--header 'Authorization;'

Response Example

200 - Example 1

{
    "href": "string",
    "items": [
        {
            "added_at": "2019-08-24T14:15:22Z",
            "episode": {
                "audio_preview_url": "string",
                "description": "string",
                "duration_ms": 0,
                "explicit": true,
                "external_urls": {
                    "spotify": "string"
                },
                "href": "string",
                "html_description": "string",
                "id": "string",
                "images": [
                    {
                        "height": 0,
                        "url": "string",
                        "width": 0
                    }
                ],
                "is_externally_hosted": true,
                "is_playable": true,
                "language": "string",
                "languages": [
                    "string"
                ],
                "name": "string",
                "release_date": "string",
                "release_date_precision": "string",
                "restrictions": {
                    "reason": "string"
                },
                "resume_point": {
                    "fully_played": true,
                    "resume_position_ms": 0
                },
                "show": {
                    "available_markets": [
                        "string"
                    ],
                    "copyrights": [
                        {
                            "text": "string",
                            "type": "string"
                        }
                    ],
                    "description": "string",
                    "explicit": true,
                    "external_urls": {
                        "spotify": "string"
                    },
                    "href": "string",
                    "html_description": "string",
                    "id": "string",
                    "images": [
                        {
                            "height": 0,
                            "url": "string",
                            "width": 0
                        }
                    ],
                    "is_externally_hosted": true,
                    "languages": [
                        "string"
                    ],
                    "media_type": "string",
                    "name": "string",
                    "publisher": "string",
                    "type": "string",
                    "uri": "string"
                },
                "type": "string",
                "uri": "string"
            }
        }
    ],
    "limit": 0,
    "next": "string",
    "offset": 0,
    "previous": "string",
    "total": 0
}

Request

Query Params

market

string

optional

An ISO 3166-1 alpha-2 country code. If a country code is specified, only episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.

limit

integer

optional

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

offset

integer

optional

The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.

Header Params

Authorization

string

required

A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The user-library-read scope must have been authorized by the user.

Responses

🟢200- On success, the HTTP status code in the response header is `200` OK and the response body contains an array of [saved episode objects](https://developer.spotify.com/documentation/web-api/reference/#object-savedepisodeobject) (wrapped in a [paging object

application/json

Body

href

string

optional

A link to the Web API endpoint returning the full result of the request

items

array[object (SavedEpisodeObject) {2}]

optional

The requested data.

added_at

string <date-time>

optional

The date and time the episode was saved. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.

episode

object (EpisodeObject)

optional

limit

integer <int32>

optional

The maximum number of items in the response (as set in the query or by default).

string

optional

URL to the next page of items. ( null if none)

offset

integer <int32>

optional

The offset of the items returned (as set in the query or by default)

string

optional

URL to the previous page of items. ( null if none)

total

integer <int32>

optional

The total number of items available to return.

🔴500500

Remove User's Saved Episodes

Save Episodes for User