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

# Segments & clips

> AI-identified structural sections of every episode and engagement-scored highlight clips.

Two related but distinct breakdowns of every episode:

* **Segments** are *structural* — sections classified by purpose (intro, ad, topic discussion, interview, transition). On episodes that report `start_line`/`end_line` they cover every line of the transcript ([caveat for older episodes](#segments-partition-the-transcript-not-the-clock)), and they answer "what's happening, when?"
* **Clips** are *highlight-driven* — short standalone moments scored for engagement and tagged with a type (`INSIGHTFUL`, `FUNNY`, `CONTROVERSIAL`, `AHA_MOMENT`, …). Typically a handful per episode. They answer "what's worth sharing?"

<Note>For MCP agents, a known episode's clips are bundled into [`particle_podcast_get_episode`](/mcp/tools/podcasts/podcast-get-episode) with `include: ["clips"]` (and segments with `include: ["segments"]`). Clips that overlap a dialogue match arrive inline on [`particle_podcast_search_transcripts`](/mcp/tools/podcasts/podcast-search-transcripts).</Note>

## Segments

### Segment types

| Type               | What it captures                                      |
| ------------------ | ----------------------------------------------------- |
| `INTRO`            | Opening of the episode                                |
| `OUTRO`            | Closing                                               |
| `TOPIC_DISCUSSION` | In-depth discussion of a specific subject             |
| `INTERVIEW`        | Question-and-answer with a guest                      |
| `PERSONAL_BANTER`  | Off-topic or personal conversation                    |
| `TRANSITION`       | Bridge between segments                               |
| `AD`               | Advertisement, sponsorship, or cross-promotional read |

### Segments for an episode

In chronological order, this is the structural outline of the episode.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/segments" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```
</CodeGroup>

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    { "number": 1, "type": "AD",               "title": "Sponsor: The Build Podcast",                        "start_seconds": 0.56,    "end_seconds": 28.94    },
    { "number": 4, "type": "INTRO",            "title": "Show Open and Banter",                              "start_seconds": 102.94,  "end_seconds": 242.4    },
    { "number": 5, "type": "TOPIC_DISCUSSION", "title": "WH Correspondents Dinner Shooting and Media Coverage", "start_seconds": 242.46,  "end_seconds": 1233.69 },
    { "number": 9, "type": "TOPIC_DISCUSSION", "title": "Musk v. Altman Trial and AI Industry Moves",         "start_seconds": 1435.49, "end_seconds": 2228.04 },
    { "number": 21, "type": "OUTRO",           "title": "Show Close and Credits",                             "start_seconds": 4448.06, "end_seconds": 4502.34 }
    // 21 segments returned; abbreviated for readability
  ],
  "has_more": false,
  "cursor": null
}
```

### Segments partition the transcript, not the clock

Segments are contiguous in **transcript lines**, not in wall-clock seconds. On
any episode that reports `start_line`/`end_line`, every spoken line belongs to
exactly one segment, and a segment's `end_line + 1` is the next segment's
`start_line`, running from line 1 through the last line of the transcript. Older
episodes are covered by the caveat below.

The timestamps behave differently, and this trips people up. `start_seconds` is
when a segment's first spoken line begins; `end_seconds` is when its last spoken
line ends. So one segment's `end_seconds` is normally a little *before* the next
segment's `start_seconds` — you can see it in the response above, where `#4` ends
at `242.4` and `#5` starts at `242.46`. That interval is silence: the pause
between two utterances. It is usually well under a second, but when a show ends
and a trailing ad is stitched in much later it can be minutes long.

**Nothing is missing from those intervals**, on any episode that reports
`start_line`/`end_line`. They contain no transcribed speech at all: if they did,
the lines would belong to a segment.

<Warning>
  Two separate cutoffs matter here, and they are not the same date.

  `start_line`/`end_line` are recorded only for episodes segmented from September
  2026 onward, when we began persisting them. Everything older omits them,
  regardless of how good its coverage is.

  Separately, episodes segmented before **24 July 2026** came from a version of
  the segmenter that could genuinely leave transcript lines in no segment, and
  about 11% of them did. On those, a gap between two segments **may** contain real
  speech. A repair of that cohort is in progress.

  So a missing `start_line` does not imply a gap — most episodes without line
  ranges were segmented after the coverage fix and are complete. It means only
  that you cannot verify the partition from the segments response alone. Where it
  matters, check the episode transcript for lines falling in the gap.
</Warning>

To slice a transcript by segment, use the line numbers rather than arithmetic on
the floats. `start_line`/`end_line` are exact, and they match the `number` field
on each line of `GET /v1/podcasts/episodes/{id}/transcript`:

```python theme={"dark"}
lines = transcript["lines"]                       # 1-indexed `number` per line
for segment in segments:
    text = lines[segment["start_line"] - 1 : segment["end_line"]]
```

<Note>`start_line` and `end_line` are omitted on episodes segmented before line
ranges were recorded. Fall back to `start_seconds`/`end_seconds` when they are
absent, keeping the caveat above in mind: on those episodes the segments are not
guaranteed to cover every line.</Note>

### Segment transcripts and audio

Each segment has its own [transcript endpoint](/podcasts/transcripts#segment-and-clip-transcripts) and an audio URL with the extracted MP3. To filter by type server-side (for example, to skip ads), use the cross-catalog endpoint with an episode filter: `GET /v1/podcasts/segments?episode_id={id}&type=AD`.

### Cross-episode segment lookup

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/segments?type=INTERVIEW&limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

At least one of `episode_id`, `podcast_id`, or `type` is required — the endpoint does not return a global feed. Combine filters to narrow further (e.g., `?podcast_id=all-in&type=INTERVIEW`).

## Clips

Clips are the highlight moments — the parts of an episode worth pulling out for sharing, embedding, or social posts. Each is AI-extracted, scored for engagement, and tagged with a type.

### Clip types

| Category            | Types                                                                     |
| ------------------- | ------------------------------------------------------------------------- |
| Takes & opinions    | `SPICY`, `CONTROVERSIAL`, `DEBATE_DISAGREEMENT`                           |
| Emotion             | `FUNNY`, `EMOTIONAL`, `SHOCKING`                                          |
| Insight & knowledge | `INSIGHTFUL`, `INFORMATIVE`, `EDUCATIONAL`, `PHILOSOPHICAL`, `AHA_MOMENT` |
| Highlights          | `NOTABLE_LINE`, `BEST_STORY`                                              |

### Clips for an episode

Returned ranked by engagement score (highest first):

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/clips?limit=2" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "id": "7ULKq1QRmEKqICZJKa6orv",
      "type": "INSIGHTFUL",
      "title": "Targets, fame, and gun access",
      "intro_statement": "First, what truly drives these attacks?",
      "engagement_score": 84,
      "start_seconds": 356.3,
      "end_seconds": 414.96,
      "duration_seconds": 58.66,
      "audio_url": "https://cdn.particle.pro/podcast/episode/…/clip/audio/….mp3",
      "speaker": {
        "name": "Scott Galloway",
        "role": "HOST",
        "entity_slug": "scott-galloway"
      },
      "segment": {
        "id": "68yiT3ivEGRsDjMgWjO9rT",
        "type": "TOPIC_DISCUSSION",
        "title": "WH Correspondents Dinner Shooting and Media Coverage"
      }
    }
    // …
  ]
}
```

Each clip carries:

* `audio_url` — direct MP3 of the clip; embed it without slicing yourself
* `intro_statement` — ready-to-use share copy
* `engagement_score` — integer 0–100. Higher is more shareable; values above 70 are typical for a strong clip.
* `speaker` — who's speaking, with a knowledge-graph link
* `segment` — which structural section the clip came from

### Clips by speaker

`GET /v1/podcasts/clips` filters across the whole catalog by `podcast_id`, `episode_id`, `type`, `min_engagement`, and `speaker`. The `speaker` filter takes a person slug (e.g. `sam-altman`), a knowledge-graph entity slug for the same person, or an ID, and returns only clips whose primary speaker is that person — so "an insightful Sam Altman clip" is one call:

```bash theme={"dark"}
curl --get "https://api.particle.pro/v1/podcasts/clips" \
  --data-urlencode "speaker=sam-altman" \
  --data-urlencode "type=INSIGHTFUL" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

A `speaker` or `podcast_id` reference that resolves to nothing returns an empty listing rather than silently widening back to the full catalog.

### Discovering clips by what's discussed

Highlight clips are returned alongside their parent segment by `GET /v1/podcasts/episodes/search`. Whenever a clip's time range overlaps the matching segment, it appears in the result's `clips` array.

<CodeGroup>
  ```bash curl theme={"dark"}
  # Search the dialogue by meaning; clips on a matching segment come along.
  curl --get "https://api.particle.pro/v1/podcasts/episodes/search" \
    --data-urlencode "semantic_search=panel debating whether superintelligent AI will be controllable" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```bash curl theme={"dark"}
  # Every line about a person inside a single podcast — use /mentions for
  # entity-mention search; /search rejects requests without semantic_search
  # or keyword_search.
  curl --get "https://api.particle.pro/v1/podcasts/mentions" \
    --data-urlencode "entity_id=sam-altman" \
    --data-urlencode "podcast_id=pivot" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```
</CodeGroup>

See the [episode search docs](/podcasts/episode-search) for ranked dialogue search, and the [mentions docs](/podcasts/mentions) for entity-mention search.

<Note>
  `GET /v1/podcasts/clips` (above) is for *browsing* highlight clips ranked by engagement. For *text-based* discovery — by topic or keyword — use [`/v1/podcasts/episodes/search`](/podcasts/episode-search) (clips on matching segments come along). For entity-mention discovery, use [`/v1/podcasts/mentions`](/podcasts/mentions).
</Note>

## Embeds

Public clip embed endpoints (no API key required) return shareable JSON suitable for iframe-style players:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/embed/clips/7ULKq1QRmEKqICZJKa6orv"
```

The embed payload includes the clip title, intro statement, audio URL, podcast artwork, and duration — everything you need for a thumbnail player.

## Related

* [Transcripts](/podcasts/transcripts) — fetch dialogue scoped to a segment or clip
* [Episodes](/podcasts/episodes) — list and filter episodes
* [Concepts](/concepts) — pagination, slugs, pricing weight