Workflows Client
The Workflows client lets you explore workflow definitions, fetch metadata, and validate input payloads before executing a run. Use it to inspect schemas and prevent invalid submissions.
Setup
from cloudcruise import CloudCruise, CloudCruiseParams
client = CloudCruise(
CloudCruiseParams(
api_key="your-api-key",
encryption_key="your-encryption-key",
)
)
Listing All Workflows
Retrieve all workflows accessible by your API key:
workflows = client.workflows.get_all_workflows()
for workflow in workflows:
print(f"ID: {workflow.get('id')}")
print(f"Name: {workflow.get('name')}")
print(f"Description: {workflow.get('description')}")
print("---")
Workflow Object
| Field | Type | Description |
|---|
id | str | Unique workflow identifier |
name | str | Workflow name |
description | str | Workflow description |
created_at | str | Creation timestamp |
updated_at | str | Last update timestamp |
workspace_id | str | Associated workspace ID |
created_by | str | Creator user ID |
enable_popup_handling | bool | Whether popup handling is enabled |
enable_xpath_recovery | bool | Whether XPath recovery is enabled |
enable_error_code_generation | bool | Whether error code generation is enabled |
metadata = client.workflows.get_workflow_metadata("workflow-123")
input_schema = metadata.get("input_schema", {})
properties = input_schema.get("properties", {})
required = input_schema.get("required", [])
print("Input Schema Properties:")
for name, schema in properties.items():
is_required = "required" if name in required else "optional"
print(f" {name} ({is_required}): {schema}")
| Field | Type | Description |
|---|
input_schema | dict | JSON Schema defining required input variables |
input_schema follows JSON Schema format:
{
"type": "object",
"properties": {
"url": {"type": "string"},
"max_attempts": {"type": "integer"},
"USER": {"type": "string"},
},
"required": ["url", "USER"],
"additionalProperties": False
}
from cloudcruise.workflows.types import InputValidationError
payload = {
"url": "https://example.com",
"USER": "user-123",
}
try:
client.workflows.validate_workflow_input("workflow-123", payload)
print("✓ Payload is valid")
except InputValidationError as exc:
print(f"✗ Validation failed: {exc}")
print(f" Missing required: {exc.missingRequired}")
print(f" Invalid types: {exc.invalidTypes}")
print(f" Unknown keys: {exc.unknownKeys}")
When you call client.runs.start(), the SDK automatically validates the input against the workflow’s schema. Manual validation is useful when you want to check inputs before making the API call.
Validation Checks
The validator checks:
| Check | Description |
|---|
| Required fields | All fields listed in required must be present |
| Type matching | Values must match their declared type (string, number, boolean, etc.) |
| Additional properties | If additionalProperties: false, unknown keys are rejected |
InputValidationError is raised with details:
| Property | Type | Description |
|---|
missingRequired | List[str] | Fields that are required but missing |
invalidTypes | List[InvalidTypeDetail] | Fields with incorrect value types |
unknownKeys | List[str] | Fields not defined in schema (when extras disallowed) |
Combining with Runs
Use workflow metadata to build dynamic UIs or validate inputs before execution:
from cloudcruise import StartRunRequest
from cloudcruise.workflows.types import InputValidationError
workflow_id = "workflow-123"
# Get metadata to understand required inputs
metadata = client.workflows.get_workflow_metadata(workflow_id)
schema = metadata.get("input_schema", {})
required_fields = schema.get("required", [])
print(f"Required inputs: {required_fields}")
# Build a form with required_fields...
# Build your payload
payload = {
"url": "https://example.com",
"USER": "user-123",
}
# Validate before running
try:
client.workflows.validate_workflow_input(workflow_id, payload)
except InputValidationError as exc:
print(f"Fix these issues: {exc}")
raise
# Start the run
run = client.runs.start(
StartRunRequest(
workflow_id=workflow_id,
run_input_variables=payload,
)
)
print(f"Started run: {run.sessionId}")
