> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ## OpenAPI ````yaml run-api/run-api.yaml post /run openapi: 3.1.0 info: title: CloudCruise Run API version: 0.1.0 description: >- Endpoints for managing workflow executions, user interactions, and retrieving execution results. servers: - url: https://api.cloudcruise.com description: CloudCruise Platform Production API Server security: - AuthScheme: [] paths: /run: post: summary: Start a run description: |- 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 operationId: run_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionRegistrationPayload' responses: '202': description: Browser agent run initiated content: application/json: schema: type: object properties: session_id: type: string title: Session ID description: Unique identifier for the workflow execution session '400': description: >- Invalid run payload, workflow input validation failed, or required encryption/webhook configuration is missing '404': description: Workflow not found components: schemas: SessionRegistrationPayload: properties: workflow_id: type: string title: Workflow ID description: Unique identifier for the workflow to execute run_input_variables: type: object title: Input Variables description: >- 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: $ref: '#/components/schemas/DryRun' webhook: $ref: '#/components/schemas/PayloadWebhook' priority_level: $ref: '#/components/schemas/Priority' encrypted_keys: type: array items: type: string description: >- Optional list of run_input_variables keys that are encrypted with your workspace AES key. force_refresh: type: boolean default: false description: >- Force-refresh workflow and encryption key caches before starting the run. capture_console_logs: type: boolean default: false description: Capture browser console logs during execution. send_connection_string: type: boolean default: false description: >- Include live-view connection details in run execution events when available. client_id: type: string description: >- Optional client identifier used by SDKs to bind SSE event streams to this run. debug: type: boolean title: Debug Mode default: false description: >- 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: type: object title: Additional Context description: >- 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: type: integer title: Workflow Version Number description: >- 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. type: object required: - workflow_id - run_input_variables title: Workflow Start Configuration description: >- 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 ```json { "workflow_id": "d4e5f6a7-89ab-45cd-ef01-456789012abc", "run_input_variables": { "USER": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "other_input": "value" } } ``` ### Pooled Credentials (Load Balancing) ```json { "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. DryRun: type: object properties: enabled: type: boolean title: Dry Run Flag description: >- When true, executes the workflow in test mode without making permanent changes add_to_output: type: object title: Add to Output description: >- Additional data to add to the output of the workflow. This can be used to mock the output of the workflow that was omitted due to the steps skipped because of the dry run flag. PayloadWebhook: type: object description: >- Webhook configuration for receiving execution event notifications. Supports: - Custom metadata inclusion - Event type filtering - Configurable validity periods (in seconds) anyOf: - $ref: '#/components/schemas/Metadata' title: Webhook Metadata - $ref: '#/components/schemas/RunSpecificWebhook' title: Run-Specific Webhook Settings Priority: type: string enum: - LOW - MEDIUM - HIGH default: LOW title: Priority description: >- 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. Metadata: type: object title: Metadata properties: metadata: type: object description: >- Custom data to include in webhook event payloads. Supports any JSON-serializable data structure that should be included with every webhook notification for this workflow execution. additionalProperties: true RunSpecificWebhook: type: object title: Webhook Settings description: |- Detailed configuration for webhook event delivery. Specifies: - Destination URL for event delivery - Event types to receive notifications for - Authentication secret for payload verification - Time period for webhook validity properties: url: type: string title: Webhook URL description: HTTPS endpoint that will receive webhook event notifications event_types_subscribed: type: array title: Subscribed Event Types description: >- List of execution event types to receive notifications for. Available events: - execution.failed: Workflow execution failed - execution.paused: Workflow execution paused (for example, due to workspace-level pause controls) - execution.queued: Workflow execution queued and waiting for an available worker - execution.requeued: Workflow execution re-queued after a recoverable interruption - execution.start: Workflow execution started - execution.step: Workflow step completed - execution.stopped: Workflow execution stopped - execution.success: Workflow completed successfully - execution.password_updated: Workflow password recovery completed and the vault credential was updated - file.uploaded: File artifact generated - interaction.failed: User interaction failed - interaction.finished: User interaction completed - interaction.waiting: Workflow awaiting user input - execution.input_required: Workflow paused waiting for corrected input variables - screenshot.uploaded: Screenshot captured - video.uploaded: Video recording saved items: type: string enum: - execution.failed - execution.paused - execution.queued - execution.requeued - execution.start - execution.step - execution.stopped - execution.success - execution.password_updated - file.uploaded - interaction.failed - interaction.finished - interaction.waiting - execution.input_required - screenshot.uploaded - video.uploaded secret: type: string title: Webhook Secret description: |- Secret key used to generate the X-HMAC-Signature header. Use this to verify webhook payload authenticity. validity: type: integer title: Validity Period description: >- Number of seconds for webhook event validity. This is a security feature that sets the expires_at field in webhook events to prevent replay attacks. When webhook events are sent to your endpoint, the expires_at field is set to current time + validity seconds. This prevents malicious actors from intercepting and replaying old webhook events to your endpoint. nr_retries: type: integer title: Number of Retries description: >- Maximum number of retry attempts for webhook delivery. When webhook delivery fails, the system will retry up to this number of times with exponential backoff. If not specified, defaults to 3 retries. minimum: 0 maximum: 10 default: 3 required: - url - event_types_subscribed - secret - validity securitySchemes: AuthScheme: type: apiKey name: cc-key in: header description: >- API key-based authentication. Provide your CloudCruise API key in the cc-key header. ````