Skip to content
Open Podcast API

Get all episodes

Endpoint
GET /v1/episodes

This endpoint enables clients to return all episode information relating to the authenticated user. It returns pagination information and an array of episodes.

While supported, this endpoint is expected to be used rarely in practice. More often, episodes are retrieved per queue (TBD) or per subscription (TBD).

Response fields

Metadata

FieldTypeRequired?Description
totalNumberYesThe total number of objects returned by the call
pageNumberYesThe number of the page returned in the call
per_pageNumberYesThe number of results returned per page
nextStringNoThe URL for the next page of results
previousStringNoThe URL for the previous page of results

Episode fields

GroupFieldTypeRequired?Description
Identifierpodcast_guidString <UUID>YesThe globally unique ID of the parent podcast
Identifiersync_idString <UUID>YesThe synchronisation ID of the episode, globally unique at the server and its clients
Identifierepisode_guidString <UUID>YesThe globally unique ID of the episode, as present in the RSS feed (guid tag)
IdentifiertitleStringYesThe title of the episode, as present in the RSS feed (title tag)
Identifierpublish_dateDatetimeYesThe date of publishing of the episode, as present in the RSS feed (pubDate tag). Presented in ISO 8601 format
Identifierenclosure_urlStringYesThe media file of the episode, as present in the RSS feed (enclosure tag)
Identifierepisode_urlStringYesThe (webpage) URL of the episode, as present in the RSS feed (linktag)
Dataplayback_positionInteger??YES/NO??The most recent playback position in seconds
Dataplayed_statusBooleanNoWhether the episode has been (marked as such)
Datanew_status Optional BooleanNoWhether the user (manually) interacted with the episode.
Example: In AntennaPod this is used to indicate whether an episode is in the Inbox
Datadownload_status Optional BooleanNoWhether the episode is downloaded on the client. For further details, see below.
Datafavorite_status Optional BooleanNoWhether the episode has been favorited by the user

The server can ignore the other identifier fields, if it found an episode based on the podcast_guid and the sync_id.

Remember that each of the data fields MUST have both a ‘value’ and a ‘timestamp’.

Parameters

The client MAY add the following parameters to their call:

FieldTypeInRequired?Description
sinceDateTimeQueryNoThe date from which the server should return objects. The server only returns entries whose timestamp data for any of the fields are greater than this parameter. Expected in ISO 8601 format
pageNumberQueryNoThe page of results to be returned by the server. Defaults to 1 if not present
per_pageNumberQueryNoThe number of results to return in each call. Defaults to 50 if not present

Server-side behavior

No particular behavior expected.

Client behavior

The client SHOULD update its local episode data to match the information returned in the response.

Example request

Terminal window
$ curl -X 'GET' \
'/v1/episodes?since=2024-04-23T18%3A25%3A34.511Z&page=1&per_page=5' \
-H 'accept: application/json'

Example 200 response

{
   "total": 2,
   "page": 1,
   "per_page": 5,
   "episodes": [
      {
         "podcast_guid": "31740ac6-e39d-49cd-9179-634bcecf4143",
         "sync_id": "cff3ea32-4215-4f98-bc23-5358d1f35b55",
         "episode_guid": "https://example.com/podcast/episode-5-the-history-of-RSS",
         "title": "The history of RSS",
         "publish_date": "2022-04-24T17:53:21.573Z",
         "enclosure_url": "https://example.com/podcast/episode-5-the-history-of-RSS.mp3",
         "episode_url": "https://example.com/podcast/episode-5-the-history-of-RSS",
         "playback_position": {
            "value": 0,
            "timestamp": "2024-11-02T13:19"
         },
         "played_status": {
            "value": true,
            "timestamp": "2024-11-02T13:19"
         },
         "new_status": {
            "value": false,
            "timestamp": "2024-10-30T17:31"
         },
         "download_status": {
            "value": false,
            "timestamp": "2024-11-02T13:19"
         },
         "favorite_status": {
            "value": false,
            "timestamp": "2024-11-02T13:19"
         }
      },
      {
         "podcast_guid": "9d6786c9-ed48-470d-acbe-e593547f4b5b",
         "sync_id": "5773f457-e71b-417d-8ea8-f07c38a03a3e",
         "episode_guid": "01999e25-08cd-4f29-a61e-6ca459b40d27",
         "title": "Walk with the weatherman",
         "publish_date": "2022-04-27T19:35:20.000Z",
         "enclosure_url": "https://op3.dev/e/https://podcasts.example2.net/audio/@digitalcitizen/49-walk-with-the-weatherman.mp3",
         "episode_url": "https://podcasts.example2.net/@digitalcitizen/episodes/49-walk-with-the-weatherman",
         "playback_position": {
            "value": 2100,
            "timestamp": "2024-11-01T17:38"
         },
         "played_status": {
            "value": false,
            "timestamp": "2024-04-28T09:20"
         },
         "new_status": {
            "value": false,
            "timestamp": "2024-11-01T17:02"
         },
         "download_status": {
            "value": true,
            "timestamp": "2024-11-01T17:02"
         },
         "favorite_status": {
            "value": false,
            "timestamp": "2024-04-28T09:20"
         }
      }
   ]
}