curl --request POST \
--url https://api.cloudcruise.com/run \
--header 'Content-Type: application/json' \
--header 'cc-key: <api-key>' \
--data '
{
"workflow_id": "<string>",
"run_input_variables": {},
"dry_run": {
"enabled": true,
"add_to_output": {}
},
"notifications": {
"enabled": true
},
"webhook": {
"metadata": {}
},
"priority_level": "LOW",
"encrypted_keys": [
"<string>"
],
"force_refresh": false,
"capture_console_logs": false,
"send_connection_string": false,
"client_id": "<string>",
"debug": false,
"additional_context": {},
"workflow_version": "<string>",
"workflow_version_number": 123,
"workflow_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.cloudcruise.com/run"
payload = {
"workflow_id": "<string>",
"run_input_variables": {},
"dry_run": {
"enabled": True,
"add_to_output": {}
},
"notifications": { "enabled": True },
"webhook": { "metadata": {} },
"priority_level": "LOW",
"encrypted_keys": ["<string>"],
"force_refresh": False,
"capture_console_logs": False,
"send_connection_string": False,
"client_id": "<string>",
"debug": False,
"additional_context": {},
"workflow_version": "<string>",
"workflow_version_number": 123,
"workflow_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"cc-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'cc-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
workflow_id: '<string>',
run_input_variables: {},
dry_run: {enabled: true, add_to_output: {}},
notifications: {enabled: true},
webhook: {metadata: {}},
priority_level: 'LOW',
encrypted_keys: ['<string>'],
force_refresh: false,
capture_console_logs: false,
send_connection_string: false,
client_id: '<string>',
debug: false,
additional_context: {},
workflow_version: '<string>',
workflow_version_number: 123,
workflow_branch_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://api.cloudcruise.com/run', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudcruise.com/run",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'workflow_id' => '<string>',
'run_input_variables' => [
],
'dry_run' => [
'enabled' => true,
'add_to_output' => [
]
],
'notifications' => [
'enabled' => true
],
'webhook' => [
'metadata' => [
]
],
'priority_level' => 'LOW',
'encrypted_keys' => [
'<string>'
],
'force_refresh' => false,
'capture_console_logs' => false,
'send_connection_string' => false,
'client_id' => '<string>',
'debug' => false,
'additional_context' => [
],
'workflow_version' => '<string>',
'workflow_version_number' => 123,
'workflow_branch_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"cc-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudcruise.com/run"
payload := strings.NewReader("{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cc-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudcruise.com/run")
.header("cc-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudcruise.com/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cc-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>"
}Start a run
Initiates a new browser agent run. This endpoint allows you to:
- Start a run with input variables
- Execute runs on behalf of authenticated users
- Configure webhook notifications for run events
- Perform dry runs to prevent writes in the target software
curl --request POST \
--url https://api.cloudcruise.com/run \
--header 'Content-Type: application/json' \
--header 'cc-key: <api-key>' \
--data '
{
"workflow_id": "<string>",
"run_input_variables": {},
"dry_run": {
"enabled": true,
"add_to_output": {}
},
"notifications": {
"enabled": true
},
"webhook": {
"metadata": {}
},
"priority_level": "LOW",
"encrypted_keys": [
"<string>"
],
"force_refresh": false,
"capture_console_logs": false,
"send_connection_string": false,
"client_id": "<string>",
"debug": false,
"additional_context": {},
"workflow_version": "<string>",
"workflow_version_number": 123,
"workflow_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.cloudcruise.com/run"
payload = {
"workflow_id": "<string>",
"run_input_variables": {},
"dry_run": {
"enabled": True,
"add_to_output": {}
},
"notifications": { "enabled": True },
"webhook": { "metadata": {} },
"priority_level": "LOW",
"encrypted_keys": ["<string>"],
"force_refresh": False,
"capture_console_logs": False,
"send_connection_string": False,
"client_id": "<string>",
"debug": False,
"additional_context": {},
"workflow_version": "<string>",
"workflow_version_number": 123,
"workflow_branch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"cc-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'cc-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
workflow_id: '<string>',
run_input_variables: {},
dry_run: {enabled: true, add_to_output: {}},
notifications: {enabled: true},
webhook: {metadata: {}},
priority_level: 'LOW',
encrypted_keys: ['<string>'],
force_refresh: false,
capture_console_logs: false,
send_connection_string: false,
client_id: '<string>',
debug: false,
additional_context: {},
workflow_version: '<string>',
workflow_version_number: 123,
workflow_branch_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://api.cloudcruise.com/run', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudcruise.com/run",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'workflow_id' => '<string>',
'run_input_variables' => [
],
'dry_run' => [
'enabled' => true,
'add_to_output' => [
]
],
'notifications' => [
'enabled' => true
],
'webhook' => [
'metadata' => [
]
],
'priority_level' => 'LOW',
'encrypted_keys' => [
'<string>'
],
'force_refresh' => false,
'capture_console_logs' => false,
'send_connection_string' => false,
'client_id' => '<string>',
'debug' => false,
'additional_context' => [
],
'workflow_version' => '<string>',
'workflow_version_number' => 123,
'workflow_branch_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"cc-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudcruise.com/run"
payload := strings.NewReader("{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cc-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudcruise.com/run")
.header("cc-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudcruise.com/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cc-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"workflow_id\": \"<string>\",\n \"run_input_variables\": {},\n \"dry_run\": {\n \"enabled\": true,\n \"add_to_output\": {}\n },\n \"notifications\": {\n \"enabled\": true\n },\n \"webhook\": {\n \"metadata\": {}\n },\n \"priority_level\": \"LOW\",\n \"encrypted_keys\": [\n \"<string>\"\n ],\n \"force_refresh\": false,\n \"capture_console_logs\": false,\n \"send_connection_string\": false,\n \"client_id\": \"<string>\",\n \"debug\": false,\n \"additional_context\": {},\n \"workflow_version\": \"<string>\",\n \"workflow_version_number\": 123,\n \"workflow_branch_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"session_id": "<string>"
}Authorizations
API key-based authentication. Provide your CloudCruise API key in the cc-key header.
Body
Configuration for starting a new workflow execution.
Vault Entry References
When workflows require authentication, vault entries are referenced through input variables using their permissioned_user_id:
Single Credential
{
"workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc",
"run_input_variables": {
"USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"other_input": "value"
}
}
Pooled Credentials (Load Balancing)
{
"workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc",
"run_input_variables": {
"USER": [
"a1b2c3d4-5678-90ab-cdef-1234567890ab",
"b2c3d4e5-6789-01bc-def2-234567890abc",
"c3d4e5f6-789a-12cd-ef34-34567890abcd"
],
"other_input": "value"
}
}
Pooled Credential Benefits:
- Automatic load balancing across multiple accounts
- Round-robin selection for optimal distribution
- Fault tolerance if one credential becomes unavailable
- Respects individual credential concurrency limits
- Helps prevent rate limiting on target websites
The alias names (e.g., "USER") are defined in your workflow's vault_schema configuration.
Unique identifier for the workflow to execute
Variables required by the workflow for execution. This includes both regular workflow inputs and vault entry references.
Vault Entry References: When your workflow requires authentication, reference vault entries using their permissioned_user_id:
- Single credential:
"USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab" - Pooled credentials:
"USER": ["a1b2c3d4-5678-90ab-cdef-1234567890ab", "b2c3d4e5-6789-01bc-def2-234567890abc", "c3d4e5f6-789a-12cd-ef34-34567890abcd"] - All credentials for the domain:
"USER": []
Pooled Credentials: Provide multiple user IDs as an array to enable automatic load balancing and rotation:
- CloudCruise uses round-robin selection to distribute runs across available credentials
- Helps prevent rate limiting and provides fault tolerance
- Respects each credential's concurrency limits and session settings
Domain-Wide Pool: Pass an empty array to pool every vault entry in your workspace for the alias's domain (as set in the workflow's vault_schema), without listing ids. The alias key must still be present. If no entries exist for the domain, the request fails with a 400 error.
The alias names (e.g., "USER") are defined in your workflow's vault_schema configuration.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Webhook configuration for receiving execution event notifications. Supports:
- Custom metadata inclusion
- Event type filtering
- Configurable validity periods (in seconds)
- Webhook Metadata
- Run-Specific Webhook Settings
Show child attributes
Show child attributes
Execution priority of the run. Priority applies across workflows: when runs compete for the same resources, e.g. a vault entry at its concurrency limit, HIGH runs get them first, then MEDIUM, then LOW. A run waiting for an unavailable resource does not hold back lower-priority runs whose resources are available, and running runs are never interrupted.
Credential pools do not need to match. If workflow A's HIGH runs use the pool [1, 2, 3] and workflow B's LOW runs use [3, 4], B can always use vault entry 4, but gets vault entry 3 only once A has no runs waiting.
If higher-priority runs keep arriving, lower-priority runs competing with them can wait indefinitely.
If omitted, runs default to LOW.
LOW, MEDIUM, HIGH Optional list of run_input_variables keys that are encrypted with your workspace AES key.
Force-refresh workflow and encryption key caches before starting the run.
Capture browser console logs during execution.
Include live-view connection details in run execution events when available.
Optional client identifier used by SDKs to bind SSE event streams to this run.
When enabled, captures an HTML page snapshot for every node executed in the workflow and records the run's network traffic. Snapshots are retrieved with the debug snapshots endpoint, traffic with the run network endpoint. Network traffic is recorded on workers with network capture.
Debug mode is useful for troubleshooting workflow failures, inspecting the DOM state at each step, and verifying that the browser agent is navigating correctly.
Optional JSON data that provides additional context to help the maintenance agent handle unexpected scenarios, particularly useful for form filling workflows. When a website unexpectedly requests additional information not covered by the input_variables, this field can be used to provide the extra data needed to complete the form. For example, if a form suddenly asks for a secondary phone number or additional verification details, this context can be used to supply that information. The maintenance agent will use this context to resolve such edge cases and ensure successful form completion.
Pin the run to a tagged release by an exact semver version or a range, e.g. "1.2.3", "^1.2.3", "~1.2.3", "1.x", or ">=1.2.3 <2.0.0". The highest tagged release satisfying the range is used. This is the recommended way to pin a run to a specific version — every saved workflow version is tagged with a release automatically. At most one of workflow_version, workflow_version_number, or workflow_branch_id may be given. See Workflow Versioning for what each version bump means and which pin to choose.
Legacy — prefer workflow_version for new integrations. Pins the run to the highest tagged release with this major version, i.e. N behaves like workflow_version "N.x.x". Workflows versioned before semantic versions were introduced had their version number N become N.0.0, so pins to those versions keep resolving to the same version until a newer N.x.x is saved. If not provided, the default branch's latest version is used. At most one of workflow_version, workflow_version_number, or workflow_branch_id may be given.
Pin the run to a branch's current head version. If not provided, the workflow's default branch is used. At most one of workflow_version, workflow_version_number, or workflow_branch_id may be given.
Response
Browser agent run initiated
Unique identifier for the workflow execution session
Was this page helpful?