> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Particle: List Podcast Episodes

> List a podcast's episodes from its slug. Returns the episode IDs needed by particle_list_episode_ads. Includes SDK V2 examples, schemas, and cost.

List a podcast's episodes from its slug. Returns the episode IDs needed by particle\_list\_episode\_ads.

> [!NOTE]
>
> Tool ID: `particle_list_podcast_episodes`

## Run this action

Use the TypeScript SDK for one call. Use `ctx.tools.execute(...)` inside a Play for durable calls, scheduled calls, or CSV processing.

```ts theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
import { Deepline } from 'deepline';

const deepline = await Deepline.connect();
const result = await deepline.tools.execute(
  'particle_list_podcast_episodes',
  {
    "id": "id_123"
  },
);

console.log(result.toolResponse.raw);
```

### CLI

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute particle_list_podcast_episodes --input '{
  "id": "id_123"
}' --json
```

## Example response

The SDK returns this shape at `result.toolResponse.raw`. The example values illustrate the response.

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "data": {
    "data": [
      {
        "duration_seconds": 123,
        "explicit": true,
        "has_transcript": true,
        "id": "id_123",
        "title": "VP of Engineering",
        "transcript_status": "transcribed"
      }
    ],
    "has_more": true
  }
}
```

Use `deepline describe particle_list_podcast_episodes --json` for the latest machine-readable contract.

## Input reference

Returns a paginated list of episodes for a specific podcast, identified by slug (e.g., 'all-in') or ID.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `payload.limit` | `integer` | No | `25` | Results per page Format: `int64`. Minimum: 1. Maximum: 100. |
| `payload.cursor` | `string` | No | — | Opaque pagination cursor from previous response |
| `payload.id` | `string` | Yes | — | Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID |
| `payload.q` | `string` | No | — | Filter to episodes whose title contains this text, case-insensitively. Matches the episode TITLE only — to search what is said inside episodes, use /v1/podcasts/episodes/search with podcast\_id. Maximum length: 200. |
| `payload.since` | `string` | No | — | Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z) |
| `payload.until` | `string` | No | — | Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z) |
| `payload.published_after` | `string` | No | — | Deprecated alias of since. |
| `payload.published_before` | `string` | No | — | Deprecated alias of until. |
| `payload.transcript_status` | `"any" \| "transcribed" \| "untranscribed" \| "requestable"` | No | — | Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript. Allowed: `any`, `transcribed`, See the live schema for the complete constraint. |

<details>
  <summary>Show raw input schema</summary>

  ### Input JSON Schema

  ```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
  {
    "type": "object",
    "description": "Returns a paginated list of episodes for a specific podcast, identified by slug (e.g., 'all-in') or ID.",
    "properties": {
      "limit": {
        "type": "integer",
        "description": "Results per page",
        "default": 25,
        "minimum": 1,
        "maximum": 100,
        "format": "int64"
      },
      "cursor": {
        "type": "string",
        "description": "Opaque pagination cursor from previous response"
      },
      "id": {
        "type": "string",
        "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID"
      },
      "q": {
        "type": "string",
        "description": "Filter to episodes whose title contains this text, case-insensitively. Matches the episode TITLE only — to search what is said inside episodes, use /v1/podcasts/episodes/search with podcast_id.",
        "maxLength": 200
      },
      "since": {
        "type": "string",
        "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)"
      },
      "until": {
        "type": "string",
        "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)"
      },
      "published_after": {
        "type": "string",
        "description": "Deprecated alias of since."
      },
      "published_before": {
        "type": "string",
        "description": "Deprecated alias of until."
      },
      "transcript_status": {
        "type": "string",
        "description": "Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript.",
        "enum": [
          "any",
          "transcribed",
          "untranscribed",
          "requestable"
        ]
      }
    },
    "required": [
      "id"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Output reference

Standard tool result payload.

| Name | Type | Required | Default | Details |
| - | - | - | - | - |
| `result.data` | `object` | Yes | — | Provider response payload. |
| `result.data.cursor` | `string` | No | — | Pass to next request for more results |
| `result.data.data` | `array` | Yes | — | List of results |
| `result.data.data[].ads` | `array \| null` | No | — | 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. |
| `result.data.data[].ads[].company_id` | `string` | No | — | The sponsor's company, when linked: the identifier GET /v1/companies/\{id} takes (its domain, slug or encoded ID). Fetch its current profile there. |
| `result.data.data[].ads[].duration_seconds` | `number` | Yes | — | Ad duration in seconds Format: `double`. |
| `result.data.data[].ads[].end_seconds` | `number` | Yes | — | Ad end offset within the episode, in seconds Format: `double`. |
| `result.data.data[].ads[].id` | `string` | Yes | — | Unique identifier |
| `result.data.data[].ads[].offer_description` | `string` | No | — | Promotional offer details |
| `result.data.data[].ads[].placement_type` | `string` | No | — | Where the ad appeared in the episode (PRE\_ROLL, MID\_ROLL, POST\_ROLL) |
| `result.data.data[].ads[].product` | `string` | No | — | Advertised product or service |
| `result.data.data[].ads[].read_type` | `string` | Yes | — | How the ad was delivered (HOST\_READ, PRE\_RECORDED, NETWORK\_PROMO) |
| `result.data.data[].ads[].sponsor_id` | `string` | No | — | Linked sponsor ID, when known |
| `result.data.data[].ads[].sponsor_name` | `string` | Yes | — | Name of the advertising sponsor |
| `result.data.data[].ads[].sponsor_url` | `string` | No | — | Sponsor website URL |
| `result.data.data[].ads[].start_seconds` | `number` | Yes | — | Ad start offset within the episode, in seconds Format: `double`. |
| `result.data.data[].ads[].url` | `string` | No | — | Moment link that plays the ad on Radar, at start\_seconds. |
| `result.data.data[].audio_url` | `string` | No | — | 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. |
| `result.data.data[].clip_count` | `integer` | No | — | Number of AI-extracted clips Format: `int64`. |
| `result.data.data[].clips` | `array \| null` | No | — | AI-extracted clips. Only present when include=clips (or include=all) is requested at the fully\_ingested milestone. |
| `result.data.data[].clips[].audio_url` | `string` | No | — | Direct audio URL for this clip |
| `result.data.data[].clips[].description` | `string` | No | — | AI-generated clip description |
| `result.data.data[].clips[].duration_seconds` | `number` | Yes | — | Clip duration Format: `double`. |
| `result.data.data[].clips[].end_seconds` | `number` | Yes | — | End time within the episode Format: `double`. |
| `result.data.data[].clips[].engagement_score` | `number` | Yes | — | AI-predicted engagement potential (integer, 0 to 100). Values above 70 are typical for a strong clip. Format: `double`. |
| `result.data.data[].clips[].episode` | `object` | No | — | — |
| `result.data.data[].clips[].episode.id` | `string` | Yes | — | Episode ID |
| `result.data.data[].clips[].episode.podcast` | `object` | No | — | — |
| `result.data.data[].clips[].episode.podcast.best_rank` | `object` | No | — | — |
| `result.data.data[].clips[].episode.podcast.best_rank.captured_at` | `string` | Yes | — | Format: `date-time`. |
| `result.data.data[].clips[].episode.podcast.best_rank.category_slug` | `string` | No | — | — |
| `result.data.data[].clips[].episode.podcast.best_rank.chart_type` | `"top_podcasts"` | Yes | — | Allowed: `top_podcasts`. |
| `result.data.data[].clips[].episode.podcast.best_rank.country` | `string` | No | — | — |
| `result.data.data[].clips[].episode.podcast.best_rank.rank` | `integer` | Yes | — | Format: `int64`. |
| `result.data.data[].clips[].episode.podcast.best_rank.source` | `"apple" \| "spotify"` | Yes | — | Allowed: `apple`, `spotify`. |
| `result.data.data[].clips[].episode.podcast.id` | `string` | Yes | — | Podcast ID |
| `result.data.data[].clips[].episode.podcast.image_url` | `string` | No | — | Cover image URL |
| `result.data.data[].clips[].episode.podcast.popularity` | `number` | No | — | Global popularity percentile in (0,1], a cume\_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. Format: `double`. |
| `result.data.data[].clips[].episode.podcast.publisher` | `object` | No | — | — |
| `result.data.data[].clips[].episode.podcast.publisher.id` | `string` | Yes | — | Publisher ID |
| `result.data.data[].clips[].episode.podcast.publisher.name` | `string` | Yes | — | Publisher name |
| `result.data.data[].clips[].episode.podcast.publisher.slug` | `string` | No | — | Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). |
| `result.data.data[].clips[].episode.podcast.slug` | `string` | No | — | Human-readable slug identifier |
| `result.data.data[].clips[].episode.podcast.title` | `string` | Yes | — | Podcast title |
| `result.data.data[].clips[].episode.published_at` | `string` | No | — | Publication date Format: `date-time`. |
| `result.data.data[].clips[].episode.slug` | `string` | No | — | Human-readable slug identifier |
| `result.data.data[].clips[].episode.title` | `string` | Yes | — | Episode title |
| `result.data.data[].clips[].episode.web_url` | `string` | No | — | The episode's page on Radar, where it plays beside its transcript: [https://radar.particle.pro/podcasts/\&#123;podcast\&#125;/episodes/\&#123;episode\&#125](https://radar.particle.pro/podcasts/\&#123;podcast\&#125;/episodes/\&#123;episode\&#125);, each segment the slug or, when there is none, the raw UUID. Append ?t=\{seconds} to start at a moment. The hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch See the live schema for the complete constraint. |
| `result.data.data[].clips[].id` | `string` | Yes | — | Unique identifier |
| `result.data.data[].clips[].intro_statement` | `string` | No | — | AI-generated hook text for social sharing |

The table shows the first 50 fields. Use the live contract below for every field.

> [!NOTE]
>
> This output schema is too large for an inline display. Read the complete live contract with `deepline describe particle_list_podcast_episodes --json`.

## Deepline cost

* Pricing model: `fixed` (per call).
* Estimated Deepline credits: `0` per pricing unit.
* Provider-native pricing may still exist outside Deepline credit billing.

## Related documentation

* [Particle provider guide](https://deepline.com/docs/providers/particle/guide.md)
* [SDK V2 quickstart](https://deepline.com/docs/sdk-v2/quickstart.md)
* [SDK reference](https://deepline.com/docs/sdk-v2/sdk-reference.md)
* [Run tools across a CSV](https://deepline.com/docs/sdk-v2/batch-csv.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.