> ## 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.
# Retrieve run results
> Retrieves comprehensive results and execution details for a specific browser agent run. This endpoint provides:
- Current execution status and overall outcome
- Detailed output data based on your defined data model
- Run artifacts including screenshots, error logs, and authentication/input variable records
This endpoint is subject to [global rate limits](/concepts/rate-limits). For real-time updates without polling, consider using [webhooks](/concepts/webhooks) or our [SDKs](/sdk/js/overview) instead.
The response includes recovery information when errors were automatically resolved during the run:
* `was_recovered` — `true` if any errors were successfully recovered by the Maintenance Agent
* `recovered_error_ids` — array of `error_id` values that were recovered, correlating to the `errors` array
* `adoptable_error_ids` — recovered popup error IDs that are eligible for **Adopt fix with Builder Agent** in run details
Each error object also includes `llm_error_sub_type` (the specific sub‑classification) and `llm_error_description` (an AI‑generated explanation of the failure). See the [error classification matrix](/concepts/maintenance-agent#error-classification-matrix) for all possible category and sub‑type values.
## OpenAPI
````yaml run-api/run-api.yaml get /run/{session_id}
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/{session_id}:
get:
summary: Retrieve run results
description: >-
Retrieves comprehensive results and execution details for a specific
browser agent run. This endpoint provides:
- Current execution status and overall outcome
- Detailed output data based on your defined data model
- Run artifacts including screenshots, error logs, and
authentication/input variable records
operationId: get_run_results
parameters:
- name: session_id
in: path
required: true
schema:
type: string
title: Session ID
description: Unique identifier for the browser agent run session
responses:
'200':
description: Run results successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseGetSavedData'
'429':
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitError'
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
X-RateLimit-Limit:
description: Maximum requests allowed in the time window
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the rate limit resets
schema:
type: integer
components:
schemas:
ResponseGetSavedData:
properties:
session_id:
type: string
example: e5f6a7b8-9abc-4def-0123-56789abcdef0
title: Session ID
description: Unique identifier for the workflow execution session (UUIDv4)
status:
type: string
enum:
- execution.queued
- execution.start
- execution.failed
- execution.success
- execution.paused
- execution.stopped
- execution.requeued
example: execution.success
title: Execution Status
description: Current status of the workflow execution
workflow_id:
type: string
format: uuid
nullable: true
example: d4e5f6a7-89ab-45cd-ef01-456789012abc
title: Workflow ID
description: Identifier for the workflow that was executed
input_variables:
type: object
nullable: true
title: Input Variables
description: >-
Variables provided at workflow execution start. Contains both
workflow-specific inputs and vault entry references.
Vault entries are referenced by their permissioned_user_id, either
as single strings or arrays for credential pooling.
vault_entries:
type: object
nullable: true
title: Vault Entries
description: >-
Vault entry metadata for credentials used in this run. Keys are the
credential aliases defined in the workflow's vault_schema. Values
contain the user ID, alias, domain, and encrypted credentials.
additionalProperties:
type: object
properties:
USER_ID:
type: string
description: The permissioned_user_id of the vault entry
USER_ALIAS:
type: string
nullable: true
description: Human-readable alias for the vault entry
USER_NAME:
type: string
description: Encrypted username
PASSWORD:
type: string
description: Encrypted password
DOMAIN:
type: string
description: Target domain for the credential
encrypted_variables:
type: array
nullable: true
items:
type: string
title: Encrypted Variables
description: >-
List of input variable keys whose values are encrypted vault
credentials. Use this to identify which input_variables contain
sensitive data that should not be displayed in plaintext.
session_retries:
type: integer
nullable: true
title: Session Retries
description: >-
Number of times this run has been retried due to recoverable errors
(e.g., service unavailable). Null if the run has not been retried.
data:
type: object
description: >-
Output data from the workflow execution, structured according to
your defined data model
properties:
your_defined_datamodel:
type: string
example: example_value
video_urls:
type: array
items:
type: object
properties:
timestamp:
type: string
format: date-time
example: '2024-01-01T00:00:00.000000+00:00'
title: Timestamp
description: When the screen recording was captured
session_id:
type: string
format: uuid
example: e5f6a7b8-9abc-4def-0123-56789abcdef0
title: Session ID
description: Unique identifier for the workflow execution session
signed_screen_recording_url:
type: string
example: https://www.example.com/screen-recording.mp4
title: Screen Recording URL
description: Temporary URL for accessing the screen recording
signed_screen_recording_url_expires:
type: string
format: date-time
example: '2024-01-08T00:00:00.000000+00:00'
title: URL Expiration
description: When the screen recording URL will expire
file_urls:
type: array
items:
type: object
properties:
signed_file_url:
type: string
format: uri
example: https://www.example.com/file.csv
title: Signed File URL
description: >-
Temporary URL for accessing the file with authentication
token. Validity period is configurable per workspace (default
7 days, range 1 hour to 7 days). Configure in workspace
settings.
file_name:
type: string
example: file.csv
title: File Name
description: Original name of the uploaded file
timestamp:
type: string
format: date-time
example: '2025-06-04T20:45:11.669Z'
title: Upload Time
description: When the file was uploaded
signed_file_url_expires:
type: string
format: date-time
example: '2025-06-11T20:45:11.669Z'
title: URL Expiration
description: When the signed file URL will expire
metadata:
type: object
title: File Metadata
description: Additional metadata associated with the file
screenshot_urls:
anyOf:
- type: array
items:
type: object
properties:
signed_screenshot_url:
type: string
example: https://www.example.com/screenshot.png
title: Screenshot URL
description: Temporary URL for accessing the screenshot
node_display_name:
type: string
example: Button
title: Node Name
description: Name of the workflow node where the screenshot was taken
timestamp:
type: string
example: '2024-01-01T00:00:00.000000+00:00'
title: Capture Time
description: When the screenshot was captured
signed_screenshot_url_expires:
type: string
example: '2024-01-01T00:00:00.000000+00:00'
title: URL Expiration
description: When the screenshot URL will expire
error_screenshot:
type: boolean
example: false
title: Error Status
description: Whether this screenshot was taken during an error
errors:
anyOf:
- type: array
items:
type: object
properties:
message:
anyOf:
- type: string
- type: 'null'
example: Button not found
title: Error Message
description: Detailed description of what went wrong
error_id:
anyOf:
- type: string
- type: 'null'
example: 7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f
title: Error ID
description: Unique identifier for this error instance
full_url:
anyOf:
- type: string
- type: 'null'
example: https://www.example.com/current-page
title: Page URL
description: URL where the error occurred
llm_error_description:
anyOf:
- type: string
- type: 'null'
example: The login button selector did not match any element.
title: LLM Error Description
description: >-
AI-generated detailed explanation of why the error
happened.
created_at:
anyOf:
- type: string
- type: 'null'
example: '2024-01-01T00:00:00.000000+00:00'
title: Error Time
description: When the error occurred
error_code:
anyOf:
- type: string
- type: 'null'
example: ERR-0001
title: Error Code
description: System error code for known error types
action_type:
anyOf:
- type: string
- type: 'null'
example: CLICK
title: Action Type
description: Type of action that failed
action_display_name:
anyOf:
- type: string
- type: 'null'
example: Click on the confirm button
title: Action Name
description: Human-readable name of the failed action
original_error:
anyOf:
- type: string
- type: 'null'
example: 'Element not found: //button[@id=''login-submit'']'
title: Original Error
description: >-
Raw technical error message before any AI processing or
simplification
llm_error_category:
anyOf:
- type: string
- type: 'null'
example: AUTHENTICATION_ERROR
title: LLM Error Category
description: >-
AI-generated categorization of the error type. See the
Maintenance Agent documentation for all possible values.
llm_error_sub_type:
anyOf:
- type: string
- type: 'null'
example: INVALID_CREDENTIALS
title: LLM Error Sub-Type
description: >-
More specific sub-classification within the error
category. See the Maintenance Agent documentation for all
possible values per category.
node_id:
anyOf:
- type: string
- type: 'null'
example: 9f8e7d6c-5b4a-4321-9edc-ba9876543210
title: Node ID
description: ID of the workflow node where the error occurred.
input_recovery:
anyOf:
- type: object
- type: 'null'
title: Input Recovery
description: >-
Recovery metadata when incorrect input handling was
applied to this error.
password_update_recovery:
anyOf:
- type: object
- type: 'null'
title: Password Update Recovery
description: >-
Recovery metadata when automatic password rotation was
applied to this error.
- type: 'null'
title: Errors
description: List of errors encountered during workflow execution
was_recovered:
type: boolean
nullable: true
title: Was Recovered
description: >-
Whether any errors in this run were successfully recovered by the
Maintenance Agent. True if at least one error was auto-recovered.
recovered_error_ids:
type: array
nullable: true
items:
type: string
title: Recovered Error IDs
description: >-
Array of error_id values from the errors array that were
successfully auto-recovered by the Maintenance Agent.
adoptable_error_ids:
type: array
nullable: true
items:
type: string
title: Adoptable Error IDs
description: >-
Array of recovered popup error_id values that are eligible for Adopt
fix with Builder Agent in run details.
type: object
title: Workflow Results
description: >-
Comprehensive response containing workflow execution results and
artifacts
RateLimitError:
type: object
description: Error response when rate limit is exceeded
properties:
statusCode:
type: integer
example: 429
description: HTTP status code
message:
type: string
example: Too Many Requests
description: Error message
error:
type: string
example: Too Many Requests
description: Error type
limit:
type: integer
example: 500
description: Maximum requests allowed in the violated time window
remaining:
type: integer
example: 0
description: Requests remaining (always 0 in a 429 response)
retryAfterSeconds:
type: integer
example: 1
description: Seconds to wait before retrying
required:
- statusCode
- message
- error
- limit
- remaining
- retryAfterSeconds
securitySchemes:
AuthScheme:
type: apiKey
name: cc-key
in: header
description: >-
API key-based authentication. Provide your CloudCruise API key in the
cc-key header.
````