<!-- source: https://docs.redpine.ai/docs/audio-clips -->
# Podcast audio clips

> Get a playable link to the recording behind a podcast result, with sentence timings.

A podcast result can come with the audio clip it was taken from. Ask for it with `includeAudio` and the result's `metadata.figures[]` entry for the clip carries a signed link you can play or download. Audio is never sent inline: you get a link, not bytes.

<Callout title="Audio is switched on per organization">
  Redpine has to enable audio for your organization. Until then a search with `includeAudio` still succeeds, and the clip comes back with no link and `reason: "not_entitled"`.
</Callout>

## Request audio

Set `includeAudio: true` on `POST /api/v1/search/query` or `POST /api/v1/search/unlock`. It is `false` by default, and it is separate from `includeFigures`, which never returns audio.

<CodeBlockTabs defaultValue="cURL" groupId="lang">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="cURL">
      cURL
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="cURL">
    ```bash  
    curl -X POST "https://api.redpine.ai/api/v1/search/query" \
      -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "collection": "my-collection",
        "query": "interview about sleep and memory",
        "includeAudio": true
      }'
    ```
  </CodeBlockTab>
</CodeBlockTabs>

On `unlock`, audio is free, like `includeFigures`.

## What comes back

The clip is a figure in `metadata.figures[]` with an `audio/*` media type. With `includeAudio` it gains:

| Field            | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `url`            | Link to the MP3. `null` when no link was issued                 |
| `url_expires_at` | When the link stops working, as an ISO-8601 UTC time            |
| `reason`         | Why `url` is `null`: `sandbox`, `not_entitled` or `unavailable` |
| `cues`           | Maps each sentence of the recording onto the result text        |

`reason` values:

* `sandbox`: sandbox keys never get audio links.
* `not_entitled`: audio is not enabled for your organization.
* `unavailable`: the clip could not be linked.

## Play a clip

`GET` the `url` for the MP3. See [Stream an audio clip](/docs/api-reference/search/getClip) in the API reference.

* The link carries its own token in `t`, so it needs no API key and can be the `src` of an `<audio>` element.
* The link expires after 7 days; `url_expires_at` says exactly when. Search again for a fresh one. For results unlocked through preview and unlock, `GET /api/v1/search/results/{queryId}?includeAudio=true` also returns fresh links; a direct `POST /api/v1/search/query` keeps no figures to refresh, so search again.
* Single `Range` requests are supported, so players can seek.
* Clips are free. Playing one is not billed.

A link that stops working returns a JSON `error` code on `401`, `402`, `403`, `404`, `416` or `503`; the full list is in the API reference.

## Over MCP

Pass `include_audio` to `search`, `preview` or `confirm`. Each clip comes back as one `resource_link` content block naming its result (clients on MCP protocol 2025-06-18 or later; older clients get the link as text), valid for 7 days, never audio data. The same clips are listed in `structuredContent` under `audio`, with `cues` as `[start_s, end_s, char_start, char_end]` per sentence. See [MCP](/docs/mcp).