Skip to main content

Session Parameters

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

environmentId

  • Type: string
  • Required: No
  • Default: null
  • Description: ID of an environment to attach to the session. When set, the browser loads the environment’s saved cookies, local storage, extensions, and other browser data before starting the task. Files stored in the environment are also available to the session. This maintains consistent browser state (e.g., login sessions) and persistent file access across multiple sessions.
Example:
{
  "environmentId": "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.

policyId

  • Type: string
  • Required: No
  • Default: null
  • Description: ID of an automation policy to enforce during the session. When set, every agent action is evaluated against the policy’s rules before execution. Actions can be allowed, blocked, or paused for human approval depending on the matching rule. Policies cover domain restrictions, keyword filters, action types, URL patterns, and sensitive data detection.
Example:
{
  "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
  "policyId": "pol_xyz789",
  "mode": "default",
  "initialTask": {
    "taskDetails": "Extract the latest invoice from the vendor portal",
    "startingPoint": "https://vendor.example.com"
  }
}
policyId is a top-level session parameter, alongside environmentId and proxy. A session can have a policy, an environment, both, or neither. See Automation Policies for details.

proxy

  • Type: object | null
  • Required: No
  • Default: null
  • Description: Proxy configuration for the session. Routes all browser traffic through the specified proxy server. The proxy is applied at the device level, ensuring no IP leakage. Adds 2-3 seconds of cold-start latency per session.
Two proxy sources are available:
SourceDescriptionCost
WebRunWebRun assigns a residential proxy from its pool$4 per GB
customBring your own HTTP or SOCKS proxyNo additional charge
WebRun Proxy Fields:
FieldTypeRequiredDescription
sourcestringYes"WebRun"
countrystringYesISO 3166-1 alpha-2 country code (e.g. "US", "GB", "DE") or "random"
levelstringNoProxy level: "system" or "chrome". When omitted, routed to the best available connection that matches the country. system applies the proxy at the system level (no IP leakage, slower cold start). chrome applies the proxy to Chrome directly (faster cold start, may leak IP in edge cases like WebRTC).
Custom Proxy Fields:
FieldTypeRequiredDescription
sourcestringYes"custom"
typestringYes"http" or "socks"
hoststringYesProxy server hostname or IP
portstringYesProxy server port
usernamestringNoAuthentication username
passwordstringNoAuthentication password
levelstringNoProxy level: "system" or "chrome". When omitted, routed to the best available connection. See WebRun proxy fields for details.
Examples:
// WebRun-managed proxy (default level)
{
  "proxy": {
    "source": "WebRun",
    "country": "US"
  }
}

// WebRun-managed proxy with system level
{
  "proxy": {
    "source": "WebRun",
    "country": "US",
    "level": "system"
  }
}

// Custom HTTP proxy
{
  "proxy": {
    "source": "custom",
    "type": "http",
    "host": "proxy.example.com",
    "port": "8080",
    "username": "user",
    "password": "pass"
  }
}

// Custom SOCKS proxy
{
  "proxy": {
    "source": "custom",
    "type": "socks",
    "host": "proxy.example.com",
    "port": "1080",
    "username": "user",
    "password": "pass"
  }
}

// No proxy (default)
{
  "proxy": null
}
The proxy field is a top-level session parameter, alongside environmentId. It is not nested inside initialTask. The proxy applies to the entire session — all tasks within the session use the same proxy.
See Proxies guide for use cases and best practices.

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
}

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.
ValueDescriptionSchema Format
textMarkdown formatted text (default)Not required
structured_jsonValidated JSON outputJSON Schema object
structured_csvCSV formatted dataArray 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:
FieldTypeRequiredDescription
matchstringYesDomain pattern to match (e.g. *.salesforce.com) or all to match every site
fieldsobjectYesKey-value pairs of credential fields (e.g. email, password, apiKey)
Example:
{
  "secrets": [
    {
      "match": "*.salesforce.com",
      "fields": {
        "email": "user@company.com",
        "password": "secretpass"
      }
    },
    {
      "match": "all",
      "fields": {
        "email": "user@company.com",
        "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:
FieldTypeRequiredDescription
namestringYesIdentifier for this webhook
urlstringYesEndpoint URL to receive the webhook
authstringNoAuthorization header value
submittedDatastringYesData 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: user@example.com, Password: pass123",
    "newState": "resume"
  }
}

Response Fields

Fields returned in API responses.

Session Response Fields

Returned from POST /start/start-session:
FieldTypeDescription
successbooleanWhether the request succeeded
sessionIdstringUnique session identifier
socketURLstringWebSocket connection URL
streamingobjectVideo streaming configuration
streaming.webRTCURLstringWebRTC WHEP endpoint URL
streaming.webViewURLstringHTTP video stream URL
streaming.dimensionsobjectVideo dimensions {width: 1024, height: 600}
initialPromptstringThe initial task that was provided
expiresInnumberSession expiration time in milliseconds
balancenumberCurrent account balance in USD
messagestringAdditional information

Task Response Fields

Returned from POST /start/send-message with actionType: "newTask" and POST /start/run-task: When task completes within 50 seconds:
FieldTypeDescription
successbooleanWhether the request succeeded
sessionIdstringSession identifier
taskIdstringTask identifier
statusstringTask status: "complete"
resultobjectTask result details
result.typestringResult type: "task_completed"
result.dataobjectResult data
result.data.messagestringTask completion message
result.data.prompt_tokensnumberInput tokens used
result.data.completion_tokensnumberOutput tokens generated
result.data.total_tokensnumberTotal tokens used
result.data.completion_timenumberTask execution time in seconds
When task is still running after 50 seconds:
FieldTypeDescription
successbooleanWhether the request succeeded
sessionIdstringSession identifier
taskIdstringTask identifier for polling
statusstringTask status: "pending"
pendingbooleantrue when task is still running
pollUrlstringURL to poll for task result
messagestringInstruction to poll for result

Poll Response Fields

Returned from GET /task/:sessionId/:taskId: While running:
FieldTypeDescription
successbooleanWhether the request succeeded
statusstringTask status: "active"
pendingbooleantrue when task is still running
usageobjectCurrent usage statistics
usage.inputTokensnumberInput tokens used so far
usage.outputTokensnumberOutput tokens generated so far
usage.computeTimenumberCompute time in seconds
usage.costnumberCost in USD so far
When completed:
FieldTypeDescription
successbooleanWhether the request succeeded
typestringResult type: "task_completed"
dataobjectTask result data
data.messagestringTask completion message
data.prompt_tokensnumberTotal input tokens used
data.completion_tokensnumberTotal output tokens generated
data.total_tokensnumberTotal tokens used
data.completion_timenumberTask execution time in seconds
usageobjectFinal usage statistics
usage.inputTokensnumberTotal input tokens
usage.outputTokensnumberTotal output tokens
usage.computeTimenumberTotal compute time in seconds
usage.costnumberTotal cost in USD
completedAtstringISO 8601 timestamp of completion
When guardrail triggered:
FieldTypeDescription
successbooleanWhether the request succeeded
typestringResult type: "guardrail_trigger"
dataobjectGuardrail details
data.typestringGuardrail type (e.g., "human_input_needed")
data.valuestringGuardrail message explaining what’s needed
When failed:
FieldTypeDescription
successbooleanfalse
statusstring"failed"
errorstringError message
codestringError code (e.g., "NAVIGATION_TIMEOUT")
usageobjectUsage 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;
  terminateOnCompletion?: boolean;
  outputType?: OutputType;
  outputSchema?: OutputSchema;
  webhook?: WebhookConfig;
  secrets?: SecretEntry[];
  files?: string[];
}

ProxyConfig

// WebRun-managed proxy
interface WebRunProxy {
  source: "WebRun";
  country: string;  // ISO 3166-1 alpha-2 code or "random"
  level?: "system" | "chrome";  // Default: best available connection
}

// Custom proxy (HTTP or SOCKS)
interface CustomProxy {
  source: "custom";
  type: "http" | "socks";
  host: string;
  port: string;
  username?: string;
  password?: string;
  level?: "system" | "chrome";  // Default: best available connection
}

type ProxyConfig = WebRunProxy | CustomProxy;

SessionConfig

interface SessionConfig {
  environmentId?: string;
  policyId?: string;
  proxy?: ProxyConfig | null;
  mode?: string;
  initialTask?: TaskConfig;
}

TaskMessage

interface TaskMessage {
  actionType: "newTask";
  newState: "start";
  taskDetails: string;
  startingPoint?: string | null;
  maxDuration?: number;
  maxInputTokens?: number;
  maxOutputTokens?: number;
  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

ParameterMinMaxNotes
maxDuration1000300000Milliseconds (max task duration)
maxInputTokens0100000Default: 100000
maxOutputTokens0100000Default: 100000
max_tokens0unlimitedOpenAI-compatible endpoint
Click x coordinate01024Browser width
Click y coordinate155600Accounting for browser chrome