Skip to main content
POST
/
run
Start a run
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": {}
  },
  "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_number": 123
}
'
{
  "session_id": "<string>"
}

Authorizations

​
cc-key
string
header
required

API key-based authentication. Provide your CloudCruise API key in the cc-key header.

Body

application/json

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.

​
workflow_id
string
required

Unique identifier for the workflow to execute

​
run_input_variables
Input Variables · object
required

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"]

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

The alias names (e.g., "USER") are defined in your workflow's vault_schema configuration.

​
dry_run
object
​
webhook
Webhook Metadata · object

Webhook configuration for receiving execution event notifications. Supports:

  • Custom metadata inclusion
  • Event type filtering
  • Configurable validity periods (in seconds)
​
priority_level
enum<string>
default:LOW

Defines the execution priority level for workflow runs. Within a resource group, the dispatcher drains queues in strict priority order: all HIGH runs are dispatched against available workers before any MEDIUM runs, and all MEDIUM before any LOW. This means lower-priority runs can be delayed indefinitely while higher-priority queues are non-empty and worker capacity is saturated. Round-robin across workspaces is applied within a single priority level only.

  • HIGH: Dispatched first. Use for time-sensitive runs that should preempt normal traffic.
  • MEDIUM: Dispatched after HIGH is drained. Suitable for typical workflows.
  • LOW (default): Dispatched only after HIGH and MEDIUM are drained for the resource group.

If omitted, runs default to LOW.

Available options:
LOW,
MEDIUM,
HIGH
​
encrypted_keys
string[]

Optional list of run_input_variables keys that are encrypted with your workspace AES key.

​
force_refresh
boolean
default:false

Force-refresh workflow and encryption key caches before starting the run.

​
capture_console_logs
boolean
default:false

Capture browser console logs during execution.

​
send_connection_string
boolean
default:false

Include live-view connection details in run execution events when available.

​
client_id
string

Optional client identifier used by SDKs to bind SSE event streams to this run.

​
debug
boolean
default:false

When enabled, captures an HTML page snapshot for every node executed in the workflow. These snapshots can be retrieved after the run completes using the debug snapshots endpoint.

Debug mode is useful for troubleshooting workflow failures, inspecting the DOM state at each step, and verifying that the browser agent is navigating correctly.

​
additional_context
Additional Context · object

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.

​
workflow_version_number
integer

Pin the run to a specific workflow version. If not provided, the latest version is used. Useful for ensuring consistent behavior when testing or gradually rolling out workflow changes.

Response

Browser agent run initiated

​
session_id
string

Unique identifier for the workflow execution session