> ## 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* — contiguous sections classified by purpose (intro, ad, topic discussion, interview, transition). They cover 100% of the episode timeline and 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
}
```

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

### 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