> ## Documentation index
> Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt
> Use it to discover all available pages before exploring further.

# Export Footage for an Investigation

> End to end: find the alert or moment, request a clip with spliceV3, wait for it to render, download the MP4 from the media host, or share it with a password-protected link. Python and cURL.

This guide exports the video around an incident as an MP4 file you can store with a case, or share with a link. It takes four calls: find the moment, request a clip, wait for it to render, and download it.

**You need** an [API key](https://developer.rhombus.com/authentication/api-keys) whose role can view the camera and its saved video. An OAuth app can follow the same steps with `Authorization: Bearer <access token>` in place of the API key headers; requesting and sharing a clip are write operations, so its grant needs the `read` and `write` scopes. Examples use the US host; EU organizations use `api2.eu.rhombussystems.com` and `media.eu.rhombussystems.com`.

## 1. Find the moment

If you already know the camera and the time, skip to step 2. To start from an alert, list the camera's recent alerts with [`getPolicyAlerts`](https://developer.rhombus.com/api-reference/event-webservice/get-recent-policy-alerts-for-organization):

```bash cURL
curl -X POST "https://api2.rhombussystems.com/api/event/getPolicyAlerts" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deviceFilter": ["CAMERA_UUID"], "afterTimestampMs": 1767225600000, "maxResults": 20}'
```

Each alert has a `uuid`, a `timestampMs` (when it started), a `durationSec` and, for camera alerts, the `deviceUuid`. Note the alert's `uuid` in your case record.

## 2. Request a clip

Ask for the footage with [`spliceV3`](https://developer.rhombus.com/api-reference/video-webservice/splice-v3): the camera, the start time in epoch milliseconds, and the length in seconds. Start a little before the event and run a little past it:

```python Python
import os
import time
import requests

API = "https://api2.rhombussystems.com/api"
HEADERS = {"x-auth-scheme": "api-token", "x-auth-apikey": os.environ["RHOMBUS_API_KEY"]}

def call(path, body):
    response = requests.post(f"{API}/{path}", headers=HEADERS, json=body)
    response.raise_for_status()
    data = response.json()
    if data.get("error"):
        raise RuntimeError(data.get("errorMsg"))
    return data

alert_ms = 1767230000000  # the alert's timestampMs
clip = call("video/spliceV3", {
    "deviceUuids": ["CAMERA_UUID"],
    "startTimeMillis": alert_ms - 30_000,  # 30 seconds before
    "durationSec": 120,
    "title": "Case 2026-0142: loading dock",
    "description": "Alert AAAAAAAAAAAAAAAAAAAAAA",
})
clip_uuid = clip["clipUuid"]
```

The clip renders in the background, so the call returns at once with its `clipUuid`. Clip creation has a [per-camera limit](https://developer.rhombus.com/rate-limits#per-camera-limits-on-clips-and-frames): if the call returns `429`, wait the number of seconds in `Retry-After` before trying that camera again.

## 3. Wait for it to render

Poll [`getClipWithProgress`](https://developer.rhombus.com/api-reference/event-webservice/get-a-specified-saved-clip-with-current-progress) every few seconds until `status` is `COMPLETE`. `INITIATING`, `UPLOADING` and `RENDERING` mean it's still in progress, and `percentComplete` shows how far along the current step is; any other status means it won't complete:

```python Python
IN_PROGRESS = {"INITIATING", "UPLOADING", "RENDERING"}
deadline = time.time() + 30 * 60
while True:
    saved = call("event/getClipWithProgress", {"clipUuid": clip_uuid})["clip"]
    if saved["status"] == "COMPLETE":
        break
    if saved["status"] not in IN_PROGRESS or time.time() > deadline:
        raise RuntimeError(f"clip {clip_uuid} is {saved['status']}")
    time.sleep(5)

region = saved["clipLocation"]["region"]
```

How long rendering takes depends on the clip's length and on whether the camera has already uploaded that footage.

## 4. Download the MP4

Download the finished clip from the media host, using the region from step 3 and the same API key headers:

```python Python
media = f"https://media.rhombussystems.com/media/metadata/{region}/{clip_uuid}.mp4"
with requests.get(media, headers=HEADERS, stream=True) as response:
    response.raise_for_status()
    with open(f"{clip_uuid}.mp4", "wb") as out:
        for chunk in response.iter_content(chunk_size=1 << 20):
            out.write(chunk)
```

```bash cURL
curl "https://media.rhombussystems.com/media/metadata/REGION/CLIP_UUID.mp4" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -o clip.mp4
```

The media host takes the same credentials as the REST API: the API key headers, or `Authorization: Bearer <access token>` for an OAuth token with the `read` scope. To let a browser download the clip, give it a [federated token](https://developer.rhombus.com/authentication/federated-tokens) as query parameters (`?x-auth-scheme=federated-token&x-auth-ft=<token>`); a token minted with `deviceUUid` can fetch the clip only if every camera in it is that device. [Media and streams](https://developer.rhombus.com/authentication/media#saved-clip-downloads) covers the media host, including streaming a clip inline instead of downloading it.

## Share instead of download

To give someone outside your organization access without sending a file, create a share page with [`createSharedClipGroupV3`](https://developer.rhombus.com/api-reference/event-webservice/share-multiple-clips-in-a-single-page). It takes the clip UUIDs, an optional password and an expiry, and returns a `shareUrl`:

```json
{
  "uuids": ["CLIP_UUID"],
  "title": "Case 2026-0142",
  "plaintextPassword": "a-long-random-passphrase",
  "expirationTimeSecs": 1769904000
}
```

`expirationTimeSecs` is the Unix time (in seconds) when the link stops working, not a duration. Anyone with the link and the password can watch until then.

## Keep a record

For each export, store the alert `uuid`, the `clipUuid`, the camera, the time range you requested, who requested it and when. Actions taken with an API key appear in your organization's audit log under the key's name; see [Permissions and key rotation](https://developer.rhombus.com/authentication/permissions#audit-trail).