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": {}
  },
  "additional_context": {}
}
'
{
  "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": "your-workflow-id",
  "run_input_variables": {
    "USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "other_input": "value"
  }
}

Pooled Credentials (Load Balancing)

{
  "workflow_id": "your-workflow-id",
  "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": "user-123-uuid"
  • Pooled credentials: "USER": ["user-123-uuid", "user-456-uuid", "user-789-uuid"]

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)
​
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.

Response

Browser agent run initiated

​
session_id
string

Unique identifier for the workflow execution session