> 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/roboflow-cloud/cloud-streaming/run-a-workflow.md).

# Run a Workflow

Preview, deploy, update, and stop a Workflow on a Cloud Streaming source, with clear version and sink behavior.

Run a Workflow on a [connected source](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/connect-a-source.md) to turn live video into predictions, annotated video, and downstream actions. Choose a bounded preview when testing a draft, or a deployment when you want processing to continue without a viewer.

Use the [quickstart](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/quickstart.md) for a complete first run. Processing uses credits for both previews and deployments.

## Web App

### Preview a draft

Open your saved Workflow, click "Run", and select a connected stream or a temporary webcam or phone session. "Enable Sinks" starts on: turn it off when the test must not write to outside systems.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-d4d9281f1fbd8ab679e4a32957c3782414869078%2Fcloud-streaming-shot05-editor-preview.png?alt=media" alt="Workflow editor with a stream preview and JSON output."><figcaption><p>Run tests the Workflow in the editor and shows video and structured output.</p></figcaption></figure>

### Deploy a published Workflow

Open "Deployments", then "Cloud Streaming", select the source, and choose "Run a Workflow", or click "Deploy" in the Workflow editor and choose "Cloud Streaming". Fill any required "Workflow Inputs". Values you change are saved for that source when processing starts, and load again the next time you run a Workflow on it. Click "Reset to Workflow Default" to use the Workflow's default again. Pick an image output under "Visual Preview Output" to get annotated video; a JSON-only Workflow runs without one but produces no video. Review the estimate and click "Start Processing".

Automatic recovery turns on after 30 seconds of steady processing. If a deployment shows "Enable Automatic Recovery", click it.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a2c37f334171d61022f87f911199aec658af4e62%2Fcloud-streaming-shot05-use-workflow.png?alt=media" alt="Use Workflow dialog with Cloud Streaming selected and available sources."><figcaption><p>In the Agent, "Use" opens Cloud Streaming deployment options. Displayed pricing is illustrative.</p></figcaption></figure>

The estimate is an hourly rate, not a total. "Start Processing" runs alongside other deployments on the source.

### Promote a running preview

Select the running preview and click "Deploy Stream". If other deployments run on the camera, click "Replace" to stop them or "Keep All". The preview becomes a deployment with no restart. See [promotion](#promotion).

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a3261a56bb282891bf8d6955842b2a64f934cf55%2Fcloud-streaming-shot06-promote-preview.png?alt=media" alt="Deploy Stream confirmation explaining continued billing and preserved Workflow settings."><figcaption><p>Review continuous processing and billing before confirming deployment. Displayed pricing is illustrative.</p></figcaption></figure>

### Apply Workflow changes

Publishing a Workflow does not change a running deployment. Publish, then restart the deployment, or stop it and start a new run. See [restart behavior](#restarts) and [restart controls](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/manage-and-monitor.md#restart-processing).

### Stop or replace a run

Click "Stop", then "Stop processing" to confirm. Closing the player or leaving the page does not stop a deployment or its charges.

## Workflow lifecycle

A preview runs a draft for testing while you watch. A deployment runs a published Workflow continuously, with no viewer needed. Each action below decides which Workflow version runs and whether trackers and counters carry over.

<table data-search="false"><thead><tr><th>Action</th><th>Workflow version</th><th>State and sinks</th></tr></thead><tbody><tr><td>Preview</td><td>Your draft, as it was when the preview started</td><td>A separate short run. Sinks follow the "Enable Sinks" setting (on by default).</td></tr><tr><td>Deploy</td><td>The published version when the deployment starts</td><td>Trackers and counters start fresh. Uses the published sink settings.</td></tr><tr><td>Deploy Stream (promote a preview)</td><td>The exact running preview</td><td>Same run and state. Disabled sinks stay disabled. Nothing is published or restarted.</td></tr><tr><td>Restart</td><td>The latest published version</td><td>New run with the same inputs. Trackers and counters reset.</td></tr><tr><td>Restart in the first 30 seconds of a camera run</td><td>The version being tested</td><td>New run. Start a new run to test edits.</td></tr><tr><td>Retry on a larger GPU</td><td>The version that ran out of memory</td><td>New run on the larger GPU. Trackers and counters reset.</td></tr><tr><td>Automatic recovery</td><td>The deployment's version</td><td>New run. Trackers and counters reset. Recovery can wait or pause.</td></tr></tbody></table>

### Previews

A preview runs the draft without publishing it, beside any deployment on the source. It stops 2 minutes after the last viewer leaves (10 minutes if no one watches), or after one hour. Webcam and phone previews also end when the browser disconnects.

### Deployments

A deployment runs the version published when it starts. Later edits apply only after a restart.

### Promotion

Promotion turns a running preview into a deployment without restarting it. It keeps the running Workflow, inputs, GPU, state, and sink settings. It does not publish the draft or turn disabled sinks back on.

You can promote a preview only when all of these are true:

* You started it in the app and have the "Manage Source Video" permission.
* It runs a saved Workflow on a camera, not a webcam or phone session.
* It is running, with no stop, restart, or GPU change in progress.

### Restarts

A restart loads the latest published Workflow and starts a new execution with the same inputs and settings. Saving an unpublished draft is not enough. Trackers, counters, cooldown timers, and other in-memory state start fresh, and results have a gap while the old execution stops and the new one starts. Automatic recovery after that uses the newly pinned version.

Two cases keep the old snapshot instead:

* A restart in the first 30 seconds of a camera run keeps the version under test.
* A retry on a larger GPU after a GPU memory failure keeps the version that failed. App runs retry on their own; API jobs show a "Retry on" button.

### Stopping

Stopping a job, ending a temporary session, disabling a camera, and deleting a source are different actions. To end processing, stop the job. Closing a player, leaving the page, disconnecting a viewer, unplugging a camera, or stopping its publisher does not stop a deployment or its charges: an enabled deployment with recovery waits and resumes when video returns. Automatic cleanup of an old preview does not stop a promoted deployment. Deleting or removing a camera is not a way to update its Workflow.

"Deploy Stream" and the Agent ask whether to replace other deployments. "Start Processing" always runs alongside them.

## Roboflow Agent

Ask the Agent to select a source and preview your Workflow's draft. It can inspect the live result and help you iterate without changing the active deployment.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d699f47676beb99be6882b70d4daba5fe79b593%2Fcloud-streaming-shot06-agent-preview.png?alt=media" alt="Agent stream preview with detected people and Deploy Stream above the composer."><figcaption><p>Inspect the preview before choosing Deploy Stream.</p></figcaption></figure>

To keep a preview running, ask the Agent to deploy it, or click "Deploy Stream" above the chat box.

To start a different Workflow, ask to deploy it to the camera. To apply the Agent's edits to a deployment, ask to update it: the Agent publishes the draft and restarts processing.

Be specific when stopping: name the deployment you want stopped. Asking to disconnect the preview does not stop a deployment.

## HTTP API

Start jobs with an API key that has `video-inference-job:create`, `workflow:read`, and `model:infer`. Reads need `video-inference-job:read`. See [API authentication](https://docs.roboflow.com/reference/platform/rest-api/authenticate-with-the-rest-api).

The API has no restart, promotion, or price-acknowledgment operations: use the Web App for those.

### Inspect Workflow inputs and outputs

Check what your saved Workflow needs and returns before you start a job. Use an output with `isImage: true` as `imageOutput` to get annotated video.

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-sources/v1/workflow-interface" method="get" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

### Start a job

Send a new `Idempotency-Key` for each job, and reuse it only to retry the same request. API previews do not turn off Workflow sinks. API jobs use the `processorSize` you send, or Small. To size the job from the Workflow and move it to a larger GPU after a memory error, send `autoSize: true` without `processorSize`. Jobs also use the Workflow input values saved for the source in the Web App, unless you send other values.

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-sources/v1/{sourceId}/jobs" method="post" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

### Read jobs and wait for processing

A created job is not yet processing. Read it until it runs or ends, and check its error instead of starting another job.

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-jobs/v1" method="get" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-jobs/v1/{jobId}" method="get" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

When it runs, [consume video and results](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/consume-results.md#http-api). `processingPrice` is the current hourly rate, not your total spend. Live output is not saved.

### Hold a temporary preview

A webcam or phone preview stops 2 minutes after its owner stops renewing it. Renew it every 30 seconds. To keep video playing, use [watch](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/consume-results.md#watch-live-output).

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-jobs/v1/{jobId}/hold-preview" method="post" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

### Stop a job

Cancel the job, then read it until it ends. A canceled deployment does not recover.

{% openapi src="/files/HZKHykExD3Pp9vVK5PrS" path="/{workspace}/video-jobs/v1/{jobId}/cancel" method="post" %}
[cloud-streaming.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

For a temporary camera, also [stop its session](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming/connect-a-source.md#stop-a-temporary-session) when you want to end publishing rather than just one Workflow run.
