Parameters - WebRun Documentation

Session Parameters

Parameters used when creating a new session via POST /start/start-session.

profileId

Type: string
Required: No
Default: null
Description: ID of a browser profile to attach to the session. When set, the browser loads the profile’s saved cookies, local storage, extensions, and other data before starting the task. This maintains consistent browser state (e.g., login sessions) across multiple sessions.

Example:

{
  "profileId": "683a1f2e4b0c1d2e3f4a5b6c",
  "mode": "default",
  "initialTask": {
    "taskDetails": "Go to amazon.com and check my orders"
  }
}

Use profiles to skip login steps. Log in once with a profile attached, then reuse that profile for future sessions — the saved cookies keep you authenticated.

mode

Type: string
Required: No
Default: "default"
Description: Session mode. Currently only "default" is supported.

Example:

{
  "mode": "default"
}

initialTask

Type: object
Required: No
Description: Configuration for the initial task to run when the session starts. Contains all task-specific parameters.

Example with structured_json:

{
  "mode": "default",
  "initialTask": {
    "taskDetails": "Find the price of iPhone 15 Pro on Apple.com",
    "startingPoint": "https://apple.com",
    "maxDuration": 300000,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "productName": { "type": "string" },
        "price": { "type": "number" },
        "currency": { "type": "string" }
      }
    }
  }
}

Example with structured_csv:

{
  "mode": "default",
  "initialTask": {
    "taskDetails": "Get the top 10 cryptocurrency prices",
    "maxDuration": 300000,
    "outputType": "structured_csv",
    "outputSchema": ["name", "price", "market_cap"]
  }
}

All task-specific parameters like taskDetails, startingPoint, outputType, and outputSchema are now nested inside the initialTask object.

Initial Task Parameters

Parameters used inside the initialTask object when creating a session, or in the message body when sending a new task via POST /start/send-message.

taskDetails

Type: string
Required: No
Default: ""
Description: Task description for the AI agent to execute.

Example:

{
  "initialTask": {
    "taskDetails": "Go to amazon.com and search for wireless keyboards"
  }
}

startingPoint

Type: string
Required: No
Default: null
Description: URL where the browser should navigate before starting the task. Speeds up task execution by starting at the relevant page.

Example:

{
  "initialTask": {
    "taskDetails": "Search for laptops",
    "startingPoint": "https://amazon.com"
  }
}

Setting a startingPoint eliminates the need to navigate from a blank page, reducing task execution time and cost.

maxDuration

Type: number (milliseconds)
Required: No
Default: 300000 (5 minutes)
Maximum: 300000 (5 minutes)
Description: Maximum time a task can run before automatic termination.

Example:

{
  "maxDuration": 180000  // 3 minutes
}

Tasks automatically terminate after maxDuration. Set this value based on your expected task completion time.

maxInputTokens

Type: number
Required: No
Default: 100000
Description: Maximum number of input tokens the AI can process. Limits context size to control costs.

Example:

{
  "maxInputTokens": 50000
}

maxOutputTokens

Type: number
Required: No
Default: 100000
Description: Maximum number of output tokens the AI can generate. Limits response size to control costs.

Example:

{
  "maxOutputTokens": 50000
}

avoidDomains

Type: string[] (array of strings)
Required: No
Default: []
Description: List of domains the agent should avoid navigating to. Useful for preventing unwanted redirects or blocking third-party sites.

Example:

{
  "avoidDomains": ["facebook.com", "twitter.com", "ads.example.com"]
}

terminateOnCompletion

Type: boolean
Required: No
Default: false
Description: Whether to automatically terminate the session after the current task completes. Set to true to prevent idle session charges.

Example:

{
  "terminateOnCompletion": true
}

💰 Cost Optimization: Set terminateOnCompletion: true on your last task to automatically close the session and prevent idle charges.

outputType

Type: string
Required: No
Default: "text"
Values: "text", "structured_json", "structured_csv"
Description: Specifies the output format.

Value	Description	Schema Format
`text`	Markdown formatted text (default)	Not required
`structured_json`	Validated JSON output	JSON Schema object
`structured_csv`	CSV formatted data	Array of column names

Examples:

// Text output (default)
{
  "outputType": "text"
}

// JSON output with schema
{
  "outputType": "structured_json",
  "outputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" }
    }
  }
}

// CSV output with column names
{
  "outputType": "structured_csv",
  "outputSchema": ["name", "price", "quantity"]
}

When using outputType: "structured_json" or "structured_csv", you must also provide an outputSchema to define the expected response structure.

outputSchema

Type: object (JSON Schema) or array (column names)
Required: No (required when outputType is "structured_json" or "structured_csv")
Description: Defines the expected response structure. The format depends on the outputType:
- For structured_json: A JSON Schema object
- For structured_csv: An array of column name strings

Example for structured_json:

{
  "outputType": "structured_json",
  "outputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" },
      "features": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["title", "price"],
    "additionalProperties": false
  }
}

Supported JSON Schema Types:

string - Text values
number - Numeric values (integers and decimals)
boolean - True/false values
object - Nested objects with defined properties
array - Arrays with defined item structure

Example for structured_csv:

{
  "outputType": "structured_csv",
  "outputSchema": ["name", "price", "quantity", "category"]
}

The CSV output will include a header row with the specified column names, followed by data rows.

For JSON schemas, use "additionalProperties": false to ensure the output contains only the fields you specify.

secrets

Type: array
Required: No
Default: []
Description: Array of secret entries to provide credentials for websites the agent visits. Secrets are matched by domain pattern so the agent uses the right credentials for each site.

Secret Entry Structure:

Field	Type	Required	Description
`match`	`string`	Yes	Domain pattern to match (e.g. `*.salesforce.com`) or `all` to match every site
`fields`	`object`	Yes	Key-value pairs of credential fields (e.g. `email`, `password`, `apiKey`)

Example:

{
  "secrets": [
    {
      "match": "*.salesforce.com",
      "fields": {
        "email": "[email protected]",
        "password": "secretpass"
      }
    },
    {
      "match": "all",
      "fields": {
        "email": "[email protected]",
        "password": "defaultpass"
      }
    }
  ]
}

Secrets are never stored in a database or persisted anywhere. They are only attached to the active session and immediately discarded once the session is destroyed. Secrets are never included in task output or webhook payloads.

See Secrets guide for matching rules, custom fields, and best practices.

files

Type: string[] (array of file ID strings)
Required: No
Default: []
Description: Array of file IDs (returned from POST /files/upload) to attach to a task. The agent can use these files during browser automation — for example, uploading a document to a website form. This is a task-level parameter — place it alongside taskDetails.

Example with /start/run-task:

{
  "taskDetails": "Upload this document to the submission form",
  "startingPoint": "https://example.com/upload",
  "files": ["abc123...", "def456..."]
}

Example with /start/start-session:

{
  "mode": "default",
  "initialTask": {
    "taskDetails": "Upload the attached file to the portal",
    "startingPoint": "https://example.com/portal",
    "files": ["abc123..."]
  }
}

See File Uploads guide for the full upload workflow.

webhook

Type: object
Required: No
Description: Webhook configuration for receiving task completion notifications.

Webhook Object Structure:

Field	Type	Required	Description
`name`	`string`	Yes	Identifier for this webhook
`url`	`string`	Yes	Endpoint URL to receive the webhook
`auth`	`string`	No	Authorization header value
`submittedData`	`string`	Yes	Data to include in the payload

submittedData Options:

"ai_response" - The response from the AI (text, structured_json, or structured_csv) — only the results/output from the LLM
"full_response" - Full body response that includes the usage info
"just_ping" - Just a ping notification, no data payload

Example:

{
  "webhook": {
    "name": "Product Webhook",
    "url": "https://api.yoursite.com/webhooks/products",
    "auth": "Bearer your-secret-token",
    "submittedData": "ai_response"
  }
}

Complete Example with Structured Output and Webhook:

{
  "mode": "default",
  "initialTask": {
    "taskDetails": "Extract product information from the page",
    "startingPoint": "https://example.com/product",
    "maxDuration": 300000,
    "outputType": "structured_json",
    "outputSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { "type": "number" },
        "inStock": { "type": "boolean" }
      },
      "required": ["title", "price"],
      "additionalProperties": false
    },
    "webhook": {
      "name": "Product Webhook",
      "url": "https://api.mysite.com/products",
      "auth": "Bearer token123",
      "submittedData": "ai_response"
    }
  }
}

Task Parameters

Parameters used when starting a new task via POST /start/send-message with actionType: "newTask". All Initial Task Parameters are available, plus:

actionType

Type: string
Required: Yes
Values: "newTask", "state", "interaction", "guardrail"
Description: Type of action to perform on the session.

Example:

{
  "actionType": "newTask"
}

newState

Type: string
Required: Yes (for actionType: "newTask" and actionType: "state")
Values:
- For tasks: "start"
- For state control: "pause", "resume", "stop", "terminate"
Description: State change to apply.

Examples:

// Starting a new task
{
  "actionType": "newTask",
  "newState": "start"
}

// Pausing execution
{
  "actionType": "state",
  "newState": "pause"
}

// Resuming execution
{
  "actionType": "state",
  "newState": "resume"
}

Message Parameters

Parameters used in the message field of POST /start/send-message.

For State Control (actionType: “state”)

Required Parameters:

actionType: "state"
newState: "pause" | "resume" | "stop" | "terminate"

Example:

{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "state",
    "newState": "pause"
  }
}

For Manual Interaction (actionType: “interaction”)

Required Parameters:

actionType: "interaction"
action: Object containing interaction details

Action Object Structure:

takeOverControl / releaseControl

{
  "type": "takeOverControl"
}
// or
{
  "type": "releaseControl"
}

CLICK / DOUBLE_CLICK

{
  "type": "CLICK",  // or "DOUBLE_CLICK"
  "x": 500,
  "y": 300
}

Parameters:

x (number): Horizontal coordinate (0-1024)
y (number): Vertical coordinate (155-600, accounting for browser chrome)

Coordinate System: The browser viewport is 1024×600 pixels. The top 155 pixels are browser chrome (not clickable). Clickable area is 1024×445 pixels starting at Y=155.

TYPE

{
  "type": "TYPE",
  "text": "Hello world",
  "humanLike": true
}

Parameters:

text (string, required): Text to type
humanLike (boolean, optional): Simulate human typing speed

KEY_PRESS

{
  "type": "KEY_PRESS",
  "key": "Enter"
}

Parameters:

key (string, required): Key to press

Common Keys:

Enter
Escape
Tab
Backspace
ArrowUp, ArrowDown, ArrowLeft, ArrowRight

For Guardrail Response (actionType: “guardrail”)

Required Parameters:

actionType: "guardrail"
taskDetails: Human-provided information
newState: "resume"

Example:

{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "guardrail",
    "taskDetails": "Username: [email protected], Password: pass123",
    "newState": "resume"
  }
}

Response Fields

Fields returned in API responses.

Session Response Fields

Returned from POST /start/start-session:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`sessionId`	string	Unique session identifier
`socketURL`	string	WebSocket connection URL
`streaming`	object	Video streaming configuration
`streaming.webRTCURL`	string	WebRTC WHEP endpoint URL
`streaming.webViewURL`	string	HTTP video stream URL
`streaming.dimensions`	object	Video dimensions `{width: 1024, height: 600}`
`initialPrompt`	string	The initial task that was provided
`expiresIn`	number	Session expiration time in milliseconds
`balance`	number	Current account balance in USD
`message`	string	Additional information

Task Response Fields

Returned from POST /start/send-message with actionType: "newTask" and POST /start/run-task: When task completes within 50 seconds:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`sessionId`	string	Session identifier
`taskId`	string	Task identifier
`status`	string	Task status: `"complete"`
`result`	object	Task result details
`result.type`	string	Result type: `"task_completed"`
`result.data`	object	Result data
`result.data.message`	string	Task completion message
`result.data.prompt_tokens`	number	Input tokens used
`result.data.completion_tokens`	number	Output tokens generated
`result.data.total_tokens`	number	Total tokens used
`result.data.completion_time`	number	Task execution time in seconds

When task is still running after 50 seconds:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`sessionId`	string	Session identifier
`taskId`	string	Task identifier for polling
`status`	string	Task status: `"pending"`
`pending`	boolean	`true` when task is still running
`pollUrl`	string	URL to poll for task result
`message`	string	Instruction to poll for result

Poll Response Fields

Returned from GET /task/:sessionId/:taskId: While running:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`status`	string	Task status: `"active"`
`pending`	boolean	`true` when task is still running
`usage`	object	Current usage statistics
`usage.inputTokens`	number	Input tokens used so far
`usage.outputTokens`	number	Output tokens generated so far
`usage.computeTime`	number	Compute time in seconds
`usage.cost`	number	Cost in USD so far

When completed:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`type`	string	Result type: `"task_completed"`
`data`	object	Task result data
`data.message`	string	Task completion message
`data.prompt_tokens`	number	Total input tokens used
`data.completion_tokens`	number	Total output tokens generated
`data.total_tokens`	number	Total tokens used
`data.completion_time`	number	Task execution time in seconds
`usage`	object	Final usage statistics
`usage.inputTokens`	number	Total input tokens
`usage.outputTokens`	number	Total output tokens
`usage.computeTime`	number	Total compute time in seconds
`usage.cost`	number	Total cost in USD
`completedAt`	string	ISO 8601 timestamp of completion

When guardrail triggered:

Field	Type	Description
`success`	boolean	Whether the request succeeded
`type`	string	Result type: `"guardrail_trigger"`
`data`	object	Guardrail details
`data.type`	string	Guardrail type (e.g., `"human_input_needed"`)
`data.value`	string	Guardrail message explaining what’s needed

When failed:

Field	Type	Description
`success`	boolean	`false`
`status`	string	`"failed"`
`error`	string	Error message
`code`	string	Error code (e.g., `"NAVIGATION_TIMEOUT"`)
`usage`	object	Usage statistics up to failure

Usage Object Structure

The usage object provides token and cost information:

{
  inputTokens: number;      // Number of input tokens used
  outputTokens: number;     // Number of output tokens generated
  computeTime: number;      // Compute time in seconds
  cost: number;             // Cost in USD
}

Example:

{
  "usage": {
    "inputTokens": 12450,
    "outputTokens": 3200,
    "computeTime": 5,
    "cost": 0.0124
  }
}

OpenAI-Compatible Parameters

Parameters for POST /v1/chat/completions.

model

Type: string
Required: Yes
Value: "enigma-browser-1"
Description: Model to use. Currently only enigma-browser-1 is available.

messages

Type: array of message objects
Required: Yes
Description: Array of conversation messages

Message Object Structure:

{
  role: "system" | "user" | "assistant";
  content: string;
}

Example:

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful browser automation assistant."
    },
    {
      "role": "user",
      "content": "Go to example.com and extract all headings"
    }
  ]
}

stream

Type: boolean
Required: No
Default: false
Description: Enable streaming responses via Server-Sent Events (SSE).

max_tokens

Type: number
Required: No
Default: 2000
Description: Maximum number of tokens in the response.

temperature

Type: number
Required: No
Description: Not used (included for OpenAI compatibility only). Task execution is deterministic.

Type Definitions

ActionType

type ActionType = "newTask" | "state" | "interaction" | "guardrail";

StateType

type StateType = "start" | "pause" | "resume" | "stop" | "terminate";

InteractionType

type InteractionType =
  | "takeOverControl"
  | "releaseControl"
  | "CLICK"
  | "DOUBLE_CLICK"
  | "TYPE"
  | "KEY_PRESS";

OutputType

type OutputType = "text" | "structured_json" | "structured_csv";

OutputSchema

For structured_json, use a JSON Schema object:

interface JsonOutputSchema {
  type: "object" | "array" | "string" | "number" | "boolean";
  properties?: Record<string, JsonOutputSchema>;
  items?: JsonOutputSchema;
  required?: string[];
  additionalProperties?: boolean;
}

For structured_csv, use an array of column names:

type CsvOutputSchema = string[];

Combined type:

type OutputSchema = JsonOutputSchema | CsvOutputSchema;

WebhookConfig

interface WebhookConfig {
  name: string;
  url: string;
  auth?: string;
  submittedData: "ai_response" | "full_response" | "just_ping";
}

SecretEntry

interface SecretEntry {
  match: string;       // Domain pattern (e.g. "*.salesforce.com") or "all"
  fields: Record<string, string>; // Key-value credential fields
}

###TaskConfig

interface TaskConfig {
  taskDetails?: string;
  startingPoint?: string | null;
  maxDuration?: number;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  avoidDomains?: string[];
  terminateOnCompletion?: boolean;
  outputType?: OutputType;
  outputSchema?: OutputSchema;
  webhook?: WebhookConfig;
  secrets?: SecretEntry[];
  files?: string[];
}

SessionConfig

interface SessionConfig {
  profileId?: string;
  mode?: string;
  initialTask?: TaskConfig;
}

TaskMessage

interface TaskMessage {
  actionType: "newTask";
  newState: "start";
  taskDetails: string;
  startingPoint?: string | null;
  maxDuration?: number;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  avoidDomains?: string[];
  terminateOnCompletion?: boolean;
  outputType?: OutputType;
  outputSchema?: OutputSchema;
  webhook?: WebhookConfig;
  secrets?: SecretEntry[];
  files?: string[];
}

StateMessage

interface StateMessage {
  actionType: "state";
  newState: "pause" | "resume" | "stop" | "terminate";
}

InteractionMessage

interface InteractionMessage {
  actionType: "interaction";
  action:
    | { type: "takeOverControl" }
    | { type: "releaseControl" }
    | { type: "CLICK" | "DOUBLE_CLICK"; x: number; y: number }
    | { type: "TYPE"; text: string; humanLike?: boolean }
    | { type: "KEY_PRESS"; key: string };
}

GuardrailMessage

interface GuardrailMessage {
  actionType: "guardrail";
  taskDetails: string;
  newState: "resume";
}

Parameter Validation

Constraints

Parameter	Min	Max	Notes
`maxDuration`	1000	300000	Milliseconds (max task duration)
`maxInputTokens`	0	100000	Default: 100000
`maxOutputTokens`	0	100000	Default: 100000
`max_tokens`	0	unlimited	OpenAI-compatible endpoint
Click `x` coordinate	0	1024	Browser width
Click `y` coordinate	155	600	Accounting for browser chrome

Getting Started

Concepts

Usage Guides

Integrations

Profiles

API Reference

Capabilities

Troubleshooting

​Session Parameters

​profileId

​mode

​initialTask

​Initial Task Parameters

​taskDetails

​startingPoint

​maxDuration

​maxInputTokens

​maxOutputTokens

​avoidDomains

​terminateOnCompletion

​outputType

​outputSchema

​secrets

​files

​webhook

​Task Parameters

​actionType

​newState

​Message Parameters

​For State Control (actionType: “state”)

​For Manual Interaction (actionType: “interaction”)

​takeOverControl / releaseControl

​CLICK / DOUBLE_CLICK

​TYPE

​KEY_PRESS

​For Guardrail Response (actionType: “guardrail”)

​Response Fields

​Session Response Fields

​Task Response Fields

​Poll Response Fields

​Usage Object Structure

​OpenAI-Compatible Parameters

​model

​messages

​stream

​max_tokens

​temperature

​Type Definitions

​ActionType

​StateType

​InteractionType

​OutputType

​OutputSchema

​WebhookConfig

​SecretEntry

​SessionConfig

​TaskMessage

​StateMessage

​InteractionMessage

​GuardrailMessage

​Parameter Validation

​Constraints

Endpoints

Response Formats

Session Parameters

profileId

mode

initialTask

Initial Task Parameters

taskDetails

startingPoint

maxDuration

maxInputTokens

maxOutputTokens

avoidDomains

terminateOnCompletion

outputType

outputSchema

secrets

files

webhook

Task Parameters

actionType

newState

Message Parameters

For State Control (actionType: “state”)

For Manual Interaction (actionType: “interaction”)

takeOverControl / releaseControl

CLICK / DOUBLE_CLICK

TYPE

KEY_PRESS

For Guardrail Response (actionType: “guardrail”)

Response Fields

Session Response Fields

Task Response Fields

Poll Response Fields

Usage Object Structure

OpenAI-Compatible Parameters

model

messages

stream

max_tokens

temperature

Type Definitions

ActionType

StateType

InteractionType

OutputType

OutputSchema

WebhookConfig

SecretEntry

SessionConfig

TaskMessage

StateMessage

InteractionMessage

GuardrailMessage

Parameter Validation

Constraints