Get an episode

Returns a single episode by its unique identifier.

GET /v1/podcasts/episodes/{id}

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/episodes/{id}"

200

{
  "duration_seconds": 123,
  "explicit": true,
  "has_transcript": true,
  "id": "<string>",
  "title": "<string>",
  "transcript_status": "transcribed",
  "ads": [
    {
      "duration_seconds": 123,
      "end_seconds": 123,
      "id": "<string>",
      "read_type": "<string>",
      "sponsor_name": "<string>",
      "start_seconds": 123,
      "company_id": "<string>",
      "offer_description": "<string>",
      "placement_type": "<string>",
      "product": "<string>",
      "sponsor_id": "<string>",
      "sponsor_url": "<string>",
      "url": "<string>"
    }
  ],
  "audio_url": "<string>",
  "clip_count": 123,
  "clips": [
    {
      "duration_seconds": 123,
      "end_seconds": 123,
      "engagement_score": 123,
      "id": "<string>",
      "start_seconds": 123,
      "title": "<string>",
      "audio_url": "<string>",
      "description": "<string>",
      "episode": {
        "id": "<string>",
        "title": "<string>",
        "podcast": {
          "id": "<string>",
          "title": "<string>",
          "best_rank": {
            "captured_at": "2023-11-07T05:31:56Z",
            "chart_type": "top_podcasts",
            "rank": 123,
            "source": "apple",
            "category_slug": "<string>",
            "country": "<string>"
          },
          "image_url": "<string>",
          "popularity": 123,
          "publisher": {
            "id": "<string>",
            "name": "<string>",
            "slug": "<string>"
          },
          "slug": "<string>"
        },
        "published_at": "2023-11-07T05:31:56Z",
        "slug": "<string>",
        "web_url": "<string>"
      },
      "intro_statement": "<string>",
      "quote": "<string>",
      "segment": {
        "id": "<string>",
        "title": "<string>",
        "type": "<string>"
      },
      "speaker": {
        "name": "<string>",
        "entity": {
          "id": "<string>",
          "name": "<string>",
          "slug": "<string>",
          "company": {
            "id": "<string>",
            "domain": "<string>",
            "ticker": "<string>"
          },
          "description": "<string>",
          "image_url": "<string>",
          "person": {
            "id": "<string>",
            "company": "<string>",
            "image_url": "<string>",
            "title": "<string>"
          },
          "type": {
            "name": "<string>",
            "slug": "<string>"
          },
          "wikipedia_url": "<string>"
        },
        "person": {
          "id": "<string>",
          "name": "<string>",
          "description": "<string>",
          "image_url": "<string>",
          "slug": "<string>"
        },
        "role": "<string>"
      },
      "type": "SPICY",
      "url": "<string>"
    }
  ],
  "description": "<string>",
  "entities": [
    {
      "entity": {
        "id": "<string>",
        "name": "<string>",
        "slug": "<string>",
        "company": {
          "id": "<string>",
          "domain": "<string>",
          "ticker": "<string>"
        },
        "description": "<string>",
        "image_url": "<string>",
        "person": {
          "id": "<string>",
          "company": "<string>",
          "image_url": "<string>",
          "title": "<string>"
        },
        "type": {
          "name": "<string>",
          "slug": "<string>"
        },
        "wikipedia_url": "<string>"
      },
      "occurrences": 123,
      "salience": 123,
      "mention_lines": [
        123
      ]
    }
  ],
  "entity_count": 123,
  "episode_number": 123,
  "image_url": "<string>",
  "language": "<string>",
  "podcast": {
    "id": "<string>",
    "title": "<string>",
    "best_rank": {
      "captured_at": "2023-11-07T05:31:56Z",
      "chart_type": "top_podcasts",
      "rank": 123,
      "source": "apple",
      "category_slug": "<string>",
      "country": "<string>"
    },
    "image_url": "<string>",
    "popularity": 123,
    "publisher": {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>"
    },
    "slug": "<string>"
  },
  "published_at": "2023-11-07T05:31:56Z",
  "segment_count": 123,
  "segments": [
    {
      "duration_seconds": 123,
      "end_seconds": 123,
      "id": "<string>",
      "number": 123,
      "start_seconds": 123,
      "title": "<string>",
      "type": "<string>",
      "audio_url": "<string>",
      "description": "<string>",
      "end_line": 123,
      "episode": {
        "id": "<string>",
        "title": "<string>",
        "podcast": {
          "id": "<string>",
          "title": "<string>",
          "best_rank": {
            "captured_at": "2023-11-07T05:31:56Z",
            "chart_type": "top_podcasts",
            "rank": 123,
            "source": "apple",
            "category_slug": "<string>",
            "country": "<string>"
          },
          "image_url": "<string>",
          "popularity": 123,
          "publisher": {
            "id": "<string>",
            "name": "<string>",
            "slug": "<string>"
          },
          "slug": "<string>"
        },
        "published_at": "2023-11-07T05:31:56Z",
        "slug": "<string>",
        "web_url": "<string>"
      },
      "read_type": "<string>",
      "start_line": 123,
      "summary": "<string>",
      "url": "<string>"
    }
  ],
  "slug": "<string>",
  "speakers": [
    {
      "name": "<string>",
      "description": "<string>",
      "descriptor": "<string>",
      "entity": {
        "id": "<string>",
        "name": "<string>",
        "slug": "<string>",
        "company": {
          "id": "<string>",
          "domain": "<string>",
          "ticker": "<string>"
        },
        "description": "<string>",
        "image_url": "<string>",
        "person": {
          "id": "<string>",
          "company": "<string>",
          "image_url": "<string>",
          "title": "<string>"
        },
        "type": {
          "name": "<string>",
          "slug": "<string>"
        },
        "wikipedia_url": "<string>"
      },
      "expertise": {
        "standing": "established",
        "fields": [
          {
            "code": "<string>",
            "slug": "<string>",
            "standard": "soc_2018",
            "title": "<string>",
            "group": "minor",
            "level": 123,
            "parent_code": "<string>"
          }
        ],
        "occupations": [
          {
            "code": "<string>",
            "slug": "<string>",
            "standard": "soc_2018",
            "title": "<string>",
            "established": true,
            "group": "minor",
            "level": 123,
            "parent_code": "<string>",
            "practicing": true
          }
        ],
        "seniority": "professional"
      },
      "person": {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "image_url": "<string>",
        "slug": "<string>"
      },
      "role": "<string>",
      "speaking_duration_seconds": 123
    }
  ],
  "topics": [
    {
      "id": "<string>",
      "name": "<string>",
      "slug": "<string>",
      "ancestry": "<string>",
      "ancestry_path": "<string>",
      "episode_count": 123
    }
  ],
  "transcript": {
    "duration_seconds": 123,
    "episode_id": "<string>",
    "lines": [
      {
        "end_seconds": 123,
        "number": 123,
        "speaker": "<string>",
        "start_seconds": 123,
        "text": "<string>",
        "role": "<string>"
      }
    ],
    "excerpt": true,
    "language": "<string>",
    "segment_end_seconds": 123,
    "segment_id": "<string>",
    "segment_start_seconds": 123
  },
  "url": "<string>",
  "videos": [
    {
      "url": "<string>",
      "duration_seconds": 123,
      "height": 123,
      "mime_type": "<string>",
      "platform": "youtube",
      "width": 123
    }
  ]
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Path Parameters

id · string · required

Episode slug or ID

Response

200

application/json

OK

duration_seconds · number<double> · required

Episode duration in seconds

explicit · boolean · required

Whether the episode contains explicit content

has_transcript · boolean · required

Whether a transcript is available

id · string · required

Unique identifier

title · string · required

Episode title

transcript_status · enum<string> · required

Where the episode stands on the way to a transcript. transcribed: the transcript is available. processing: we are transcribing it, or retrying after a failure. queued: a back-catalogue episode whose transcript has been requested and is waiting to be transcribed. requestable: a discovered back-catalogue episode we have not transcribed. unavailable: it can never be transcribed, for example because its audio no longer exists.

Available options: transcribed, processing, queued, requestable, unavailable

ads · object[] | null

Advertising spots detected in the episode, in playback order. Only present when include=ads (or include=all) is requested at the fully_ingested milestone, and in episode archive records.

Show child attributes

audio_url · string

Particle's CDN copy of the episode audio. Every timestamp in our responses (transcript lines, segments, clips, mentions) is measured against this copy. Use it when no one will listen, such as for analysis or processing, so those downloads aren't counted as listens, and to play or cut audio from a specific point. To play the whole episode to a listener, use url.

clip_count · integer<int64>

Number of AI-extracted clips

clips · object[] | null

AI-extracted clips. Only present when include=clips (or include=all) is requested at the fully_ingested milestone.

Show child attributes

description · string

Episode description

entities · object[] | null

Knowledge graph entities discussed in the episode, most salient first, with the transcript lines that mention each. Only present when include=entities (or include=all) is requested at the fully_ingested milestone, and in episode archive records.

Show child attributes

entity_count · integer<int64>

Number of mentioned entities

episode_number · integer<int64>

Episode number in the series

image_url · string

Episode artwork URL

language · string

ISO 639-1 language code

podcast · object

Parent podcast

Show child attributes

published_at · string<date-time>

Publication date

segment_count · integer<int64>

Number of AI-identified segments

segments · object[] | null

AI-identified segments. Only present when include=segments (or include=all) is requested at a milestone of segmented or later.

Show child attributes

slug · string

Human-readable slug identifier

speakers · object[] | null

Speakers in this episode

Show child attributes

topics · object[] | null

Topic classifications

Show child attributes

transcript · object

Dialogue transcript. Only present when include=transcript (or include=all) is requested at a milestone of transcribed or later.

Show child attributes

url · string

The episode's audio file as the podcast's RSS feed publishes it. Feeds often route it through a measurement or ad-insertion service such as Podtrac, which counts each download and can insert different ads each time. Use it to play the whole episode to a listener, so the publisher's downloads and ad impressions are counted. Because the inserted ads vary, its timing need not match our timestamps: to play or cut from a specific point, use audio_url.

videos · object[] | null

Video URLs discovered for this episode (native enclosures, Podcasting 2.0 alternate enclosures, Media RSS, and platform links / show-note URLs from YouTube, Vimeo, Twitch, Rumble). Populated on the GET /podcasts/episodes/{id} endpoint.

Show child attributes