> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/upload-a-vision-event-video.md).

# Upload a Vision Event Video

Upload a video clip to your workspace and attach it to a Vision Event so reviewers can play it in the dashboard.

## About

A video clip shows what happened around the moment a [Vision Event](/deployment/monitoring-and-analytics/vision-events.md) was recorded, which a still image can miss. You can attach up to four clips to each event. Clips play in the event detail view of the dashboard (see [View Event Details](/deployment/monitoring-and-analytics/vision-events/query-events.md#view-event-details)).

Videos must be MP4 or MOV files up to 3 GB. They are uploaded to your Workspace, not to a Project. MP4 files that browsers can play are stored as they are. Other videos are converted to H.264 MP4, and a very long video can fail conversion.

[Edge Device Backup](/deployment/monitoring-and-analytics/vision-events/send-events.md#edge-device-backup) uploads clips recorded on the device for you. Use the steps on this page when you send events through the REST API.

## HTTP API

Attaching a video takes three steps:

1. Prepare the upload. You get a `videoId`, a `signedUrl`, and `requiredHeaders`.
2. Send the video file with a `PUT` request to `signedUrl`, with every header in `requiredHeaders`. The URL expires after 60 minutes.
3. [Create the event](/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#video-objects) with the `videoId` in `videos[].sourceId`.

You do not need to wait for Roboflow to process the video before you create the event. The clip plays in the dashboard as soon as processing finishes. If processing fails, the event is kept and the dashboard shows the video as failed. If the file is never sent, the video stays `pending` and the dashboard keeps showing it as processing.

Required scope: `vision-events:write` or `device:update` to prepare an upload, and `vision-events:read` or `device:read` to read status or get a playback URL.

### Prepare the Upload

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/videos/prepare-upload" method="post" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-dca3d4f164ead71d7f0d6953b9ac101065bf210f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Then send the file to `signedUrl`. Copy each header from `requiredHeaders` into the request:

```bash
curl -X PUT "SIGNED_URL" \
  -H "x-goog-content-length-range: 1,3221225472" \
  -H "x-goog-if-generation-match: 0" \
  --upload-file line-3-clip.mp4
```

Nothing else is needed after the `PUT`. Roboflow starts processing the video when the file arrives.

### Attach the Video to an Event

Put the `videoId` in the event's `videos` array when you [create a Vision Event](/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#video-objects) or [batch create events](/deployment/monitoring-and-analytics/vision-events/batch-create-vision-events.md):

```json
"videos": [
  { "sourceId": "Kq4vX8mNp2RtY6wZ1bCd", "label": "line-3 camera" }
]
```

Only videos prepared with this endpoint can be attached. A `videoId` from a dataset video upload, or from another workspace, is kept on the event but returns a warning and does not play.

### Check the Upload Status

`status` is `pending` from the moment you prepare the upload until Roboflow finishes processing the file, then `uploaded` or `failed`. A video whose file never arrives stays `pending`.

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/videos/{videoId}" method="get" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-dca3d4f164ead71d7f0d6953b9ac101065bf210f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Get a Playback URL

[Query results](/deployment/monitoring-and-analytics/vision-events/query-events.md#http-api) list each video's `sourceId` and `label` only. Call this endpoint to get a URL that plays or downloads one video. The URL works for 60 minutes and is `null` until `status` is `uploaded`. Anyone holding the URL can play the clip, so do not cache or share it.

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/videos/{videoId}/url" method="get" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-dca3d4f164ead71d7f0d6953b9ac101065bf210f%2Fopenapi.yaml?alt=media)
{% endopenapi %}