> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/clip-suggestions.md).

# Clip Suggestions

Fetch AI-scored highlight windows for a recording.

AI-scored highlight windows for a recording — the raw material for [renders](/endpoints/renders.md). Some suggestions are carousel-kind: they propose an angle over the whole recording and carry no clip window (`start_ms`/`end_ms` are null).

{% hint style="info" %}
**Tier:** `platform`. Base URL `https://app.castmagic.io`.
{% endhint %}

## List clip suggestions

<mark style="color:blue;">`GET`</mark> `https://app.castmagic.io/v1/recordings/:id/clip-suggestions`

Pass `generate=true` to queue suggestion generation when none exist yet. Generation is asynchronous, so poll again after a minute or two.

#### Query Parameters

| Name     | Type    | Description                                          |
| -------- | ------- | ---------------------------------------------------- |
| generate | Boolean | `true` to queue generation when no suggestions exist |

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "recording_id": "e1...",
    "suggestions": [
        {
            "id": "cs1...",
            "title": "The pricing objection moment",
            "excerpt": "...here's the thing about pricing...",
            "kind": "clip",
            "start_ms": 154000,
            "end_ms": 178000,
            "created_at": "2026-08-21T22:10:00Z"
        }
    ],
    "count": 1,
    "generating": false
}
```

{% endtab %}

{% tab title="200: OK generation queued" %}

```json
{
    "recording_id": "e1...",
    "suggestions": [],
    "count": 0,
    "generating": true
}
```

{% endtab %}
{% endtabs %}