Relay

Core API

Clip Extraction

Slice any completed recording into a re-encoded clip with a single API call. The clip is uploaded to your S3 bucket alongside the original recording.

Create a clip

POST/v1/recordings/:recording_id/clips

Queues a clip extraction job. The clip is processed asynchronously — subscribe to the clip.readywebhook to know when it's available.

Request body

labelstringrequired

A human-readable name for this clip, e.g. "product-highlight". Used in the S3 path.

start_secondsnumberrequired

Start offset from the beginning of the recording, in seconds. Supports decimals.

end_secondsnumberrequired

End offset from the beginning of the recording, in seconds. Must be greater than start_seconds.

curl — extract a 30-second clip
1
2
3
4
5
6
7
8
9
curl -X POST \
  https://api.relay.dev/v1/recordings/rec_01j9x2.../clips \
  -H "Authorization: Bearer relay_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "key-moment",
    "start_seconds": 120.0,
    "end_seconds": 150.0
  }'

Response

json
1
2
3
4
5
6
7
8
9
10
11
{
  "clip_id": "clip_01j9xz...",
  "recording_id": "rec_01j9x2...",
  "label": "key-moment",
  "start_seconds": 120.0,
  "end_seconds": 150.0,
  "status": "processing",
  "bucket_path": null,
  "created_at": "2025-04-05T11:00:00.000Z",
  "completed_at": null
}
Clip processing typically takes 10–60 seconds depending on the clip duration. Use the clip.ready webhook rather than polling.

Clip lifecycle

processing

Clip extraction job is queued or running.

complete

Clip re-encoded and uploaded to your S3 at bucket_path.

failed

Extraction failed. Check that the time range is valid.

The clip object

clip_idstring

Unique clip identifier.

recording_idstring

The source recording.

labelstring

Developer-assigned label.

start_secondsnumber

Start offset in seconds.

end_secondsnumber

End offset in seconds.

statusstring

Current lifecycle status.

bucket_pathstring | null

S3 key where the clip was written once complete.

created_atdatetime

When the clip job was created.

completed_atdatetime | null

When the clip was uploaded to S3.