Response Formats - WebRun Documentation

Overview

WebRun provides two ways to receive responses:

Method	How It Works	Best For
REST	Results returned inline if task completes within 50s, otherwise poll	Stateless, serverless, simple integrations
WebSocket	Real-time events pushed as they occur	Real-time UIs, live monitoring

REST API Response Formats

Inline Results (< 50 seconds)

Both /run-task and /send-message wait up to 50 seconds for task completion. If the task finishes in time, you get the result immediately. Structure:

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Successfully completed the search",
    "files": [
      {
        "source": "https://example.com/report.zip",
        "downloadUrl": "https://blobs.webrun.ai/files/report.zip",
        "filename": "report.zip",
        "timestamp": 1771138379108
      }
    ],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://example.com/api/data",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  }
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`sessionId`	string	Session identifier
`taskId`	string	Task identifier
`type`	string	Result type: `"task_completed"`
`data`	object	Task result data
`data.message`	string	Task completion message
`data.files`	array	Files downloaded during task execution (optional)
`data.files[].source`	string	Original URL the file was downloaded from
`data.files[].downloadUrl`	string	WebRun-hosted URL to download the file
`data.files[].filename`	string	Name of the downloaded file
`data.files[].timestamp`	number	Unix timestamp (ms) when the file was downloaded
`data.network`	array	Network requests captured during task execution (optional)
`data.network[].id`	string	Unique identifier for the network entry
`data.network[].taskId`	string	Task that generated the network activity
`data.network[].urls`	array	URLs requested in this network entry
`data.network[].urls[].url`	string	Full URL of the network request
`data.network[].urls[].timestamp`	number	Unix timestamp (ms) of the request
`usage`	object	Usage and billing information
`usage.prompt_tokens`	number	Input tokens used
`usage.completion_tokens`	number	Output tokens generated
`usage.total_tokens`	number	Total tokens used
`usage.completion_time`	number	Execution time in seconds
`usage.cost`	number	Cost in USD

Pending Results (> 50 seconds)

For longer tasks, the response returns immediately with a poll URL. Structure:

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pending": true,
  "pollUrl": "https://api.webrun.ai/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`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

Polling Responses

Poll GET /task/:sessionId/:taskId until pending: false or a final type is returned.

Still Running

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "running",
  "usage": {
    "prompt_tokens": 8000,
    "completion_tokens": 2100,
    "total_tokens": 10100,
    "completion_time": 12.3,
    "cost": 0.0067
  }
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`sessionId`	string	Session identifier
`taskId`	string	Task identifier
`status`	string	`"running"` - task is executing
`usage`	object	Current usage statistics (updates in real-time)

Task Completed

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Task finished successfully",
    "files": [
      {
        "source": "https://example.com/report.zip",
        "downloadUrl": "https://blobs.webrun.ai/files/report.zip",
        "filename": "report.zip",
        "timestamp": 1771138379108
      }
    ],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://example.com/api/data",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  },
  "completedAt": "2024-01-15T10:30:00Z"
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`sessionId`	string	Session identifier
`taskId`	string	Task identifier
`type`	string	`"task_completed"`
`data`	object	Task result data
`data.message`	string	Completion message
`data.files`	array	Files downloaded during task execution (optional)
`data.files[].source`	string	Original URL the file was downloaded from
`data.files[].downloadUrl`	string	WebRun-hosted URL to download the file
`data.files[].filename`	string	Name of the downloaded file
`data.files[].timestamp`	number	Unix timestamp (ms) when the file was downloaded
`data.network`	array	Network requests captured during task execution (optional)
`data.network[].id`	string	Unique identifier for the network entry
`data.network[].taskId`	string	Task that generated the network activity
`data.network[].urls`	array	URLs requested in this network entry
`data.network[].urls[].url`	string	Full URL of the network request
`data.network[].urls[].timestamp`	number	Unix timestamp (ms) of the request
`usage`	object	Final usage statistics
`usage.prompt_tokens`	number	Total input tokens
`usage.completion_tokens`	number	Total output tokens
`usage.total_tokens`	number	Total tokens
`usage.completion_time`	number	Execution time in seconds
`usage.cost`	number	Cost in USD
`completedAt`	string	ISO 8601 completion timestamp

Guardrail Triggered

{
  "success": true,
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials to proceed"
  }
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`type`	string	`"guardrail_trigger"`
`data`	object	Guardrail details
`data.type`	string	Guardrail type
`data.value`	string	Message explaining what’s needed

Next Steps: Respond with guardrail message via POST /start/send-message:

{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "guardrail",
    "prompt": "Username: user@example.com, Password: pass123",
    "newState": "resume"
  }
}

Task Failed

{
  "success": false,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "failed",
  "error": "Navigation timeout after 30 seconds",
  "code": "NAVIGATION_TIMEOUT",
  "usage": {
    "prompt_tokens": 5000,
    "completion_tokens": 1200,
    "total_tokens": 6200,
    "completion_time": 30.0,
    "cost": 0.0045
  }
}

Response Fields:

Field	Type	Description
`success`	boolean	`false`
`status`	string	`"failed"`
`error`	string	Error message
`code`	string	Error code
`usage`	object	Usage statistics up to failure

Session Creation Response

POST /start/start-session returns session details and streaming configuration.

{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "socketURL": "https://api.webrun.ai",
  "streaming": {
    "webRTCURL": "https://a1b2c3d4e5f6.webrun.ai/whep",
    "webViewURL": "https://a1b2c3d4e5f6.webrun.ai",
    "dimensions": {
      "width": 1024,
      "height": 600
    }
  },
  "initialPrompt": "Go to amazon.com",
  "expiresIn": 300000,
  "balance": 12.50,
  "message": "Connect to instance using sessionId in auth"
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`sessionId`	string	Unique session identifier
`socketURL`	string	WebSocket connection URL
`streaming`	object	Video streaming configuration
`streaming.webRTCURL`	string	WebRTC WHEP endpoint
`streaming.webViewURL`	string	HTTP video stream URL
`streaming.dimensions`	object	Video dimensions
`initialPrompt`	string	Initial task provided
`expiresIn`	number	Session expiration time (ms)
`balance`	number	Current account balance (USD)
`message`	string	Additional information

State Control Response

POST /start/send-message with actionType: "state", "interaction", or "guardrail" returns immediate confirmation.

{
  "success": true,
  "message": "Message sent successfully"
}

Response Fields:

Field	Type	Description
`success`	boolean	Request success indicator
`message`	string	Confirmation message

WebSocket Event Formats

Connect via Socket.IO and listen for message events:

socket.on("message", (data) => {
  console.log(data.type, data);
});

Event: agent

Live agent thoughts and reasoning during task execution.

{
  "type": "agent",
  "content": "I'll navigate to the search box and enter the query..."
}

Fields:

Field	Type	Description
`type`	string	`"agent"`
`content`	string	Agent reasoning text

Event: action

Browser action performed by the agent.

{
  "type": "action",
  "data": {
    "name": "click_element"
  }
}

Fields:

Field	Type	Description
`type`	string	`"action"`
`data`	object	Action details
`data.name`	string	Action name

Event: response_update

Status update during task execution.

{
  "type": "response_update",
  "data": {
    "message": "Starting task... Browsing the web now."
  }
}

Fields:

Field	Type	Description
`type`	string	`"response_update"`
`data`	object	Update details
`data.message`	string	Status message

Event: task_completed

Task finished successfully.

{
  "type": "task_completed",
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "data": {
    "message": "Task completed successfully",
    "files": [
      {
        "source": "https://example.com/report.zip",
        "downloadUrl": "https://blobs.webrun.ai/files/report.zip",
        "filename": "report.zip",
        "timestamp": 1771138379108
      }
    ],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://example.com/api/data",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 15420,
    "completion_tokens": 8230,
    "total_tokens": 23650,
    "completion_time": 45.3,
    "cost": 0.0234
  }
}

Fields:

Field	Type	Description
`type`	string	`"task_completed"`
`sessionId`	string	Session identifier
`taskId`	string	Task identifier
`data`	object	Completion details
`data.message`	string	Completion message
`data.files`	array	Files downloaded during task execution (optional)
`data.files[].source`	string	Original URL the file was downloaded from
`data.files[].downloadUrl`	string	WebRun-hosted URL to download the file
`data.files[].filename`	string	Name of the downloaded file
`data.files[].timestamp`	number	Unix timestamp (ms) when the file was downloaded
`data.network`	array	Network requests captured during task execution (optional)
`data.network[].id`	string	Unique identifier for the network entry
`data.network[].taskId`	string	Task that generated the network activity
`data.network[].urls`	array	URLs requested in this network entry
`data.network[].urls[].url`	string	Full URL of the network request
`data.network[].urls[].timestamp`	number	Unix timestamp (ms) of the request
`usage`	object	Usage statistics
`usage.prompt_tokens`	number	Input tokens used
`usage.completion_tokens`	number	Output tokens generated
`usage.total_tokens`	number	Total tokens used
`usage.completion_time`	number	Execution time (seconds)
`usage.cost`	number	Cost in USD

Event: guardrail_trigger

Agent needs human input to continue.

{
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials to proceed"
  }
}

Fields:

Field	Type	Description
`type`	string	`"guardrail_trigger"`
`data`	object	Guardrail details
`data.type`	string	Guardrail type
`data.value`	string	Message explaining what’s needed

Respond with:

socket.emit("message", {
  actionType: "guardrail",
  prompt: "Username: demo@example.com, Password: demo123",
  newState: "resume"
});

Event: error

Task failed with error.

{
  "type": "error",
  "error": "Navigation timeout after 30 seconds",
  "code": "NAVIGATION_TIMEOUT"
}

Fields:

Field	Type	Description
`type`	string	`"error"`
`error`	string	Error message
`code`	string	Error code

Connection Events

connect

Socket connected successfully.

socket.on("connect", () => {
  console.log("Connected to session");
});

disconnect

Socket disconnected.

socket.on("disconnect", () => {
  console.log("Disconnected from session");
});

error

Socket error occurred.

socket.on("error", (err) => {
  console.error("Socket error:", err);
});

end_session

Session terminated by server.

{
  "reason": "completed"
}

Possible Reasons:

"completed" - Task completed
"terminated" - Manually terminated
"expired" - Session expired due to inactivity
"terminateOnCompletion" - Auto-terminated after task
"instance_lost" - Instance connection lost

socket.on("end_session", (data) => {
  console.log("Session ended:", data.reason);
});

instance:disconnected

Instance connection lost. Session enters grace period for reconnection.

{
  "gracePeriod": 300000
}

socket.on("instance:disconnected", (data) => {
  console.log("Instance lost, waiting for reconnection...");
  console.log("Grace period:", data.gracePeriod, "ms");
});

instance:reconnected

Instance connection recovered.

socket.on("instance:reconnected", (data) => {
  console.log("Instance reconnected");
});

OpenAI-Compatible Response Formats

Non-Streaming Response

POST /v1/chat/completions with stream: false (default).

{
  "id": "chatcmpl-a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "webrun-browser-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I found 5 headings on example.com:\n1. Example Domain\n2. More Information\n3. Contact\n4. About\n5. Privacy Policy"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8450,
    "completion_tokens": 2100,
    "total_tokens": 10550
  },
  "webrun": {
    "sessionId": "a1b2c3d4e5f6",
    "taskId": "x9y8z7w6v5u4",
    "cost": 0.0089
  }
}

Response Fields:

Field	Type	Description
`id`	string	Completion identifier
`object`	string	`"chat.completion"`
`created`	number	Unix timestamp
`model`	string	Model name: `"webrun-browser-1"`
`choices`	array	Array of completion choices
`choices[0].index`	number	Choice index (always 0)
`choices[0].message`	object	Assistant message
`choices[0].message.role`	string	`"assistant"`
`choices[0].message.content`	string	Response text
`choices[0].finish_reason`	string	`"stop"`
`usage`	object	Token usage statistics
`usage.prompt_tokens`	number	Input tokens
`usage.completion_tokens`	number	Output tokens
`usage.total_tokens`	number	Total tokens
`webrun`	object	WebRun-specific metadata
`webrun.sessionId`	string	Session identifier
`webrun.taskId`	string	Task identifier
`webrun.cost`	number	Cost in USD

Streaming Response (SSE)

POST /v1/chat/completions with stream: true returns Server-Sent Events. Stream Format:

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"webrun-browser-1","choices":[{"index":0,"delta":{"role":"assistant","content":"I"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"webrun-browser-1","choices":[{"index":0,"delta":{"content":" found"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"webrun-browser-1","choices":[{"index":0,"delta":{"content":" 5"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"webrun-browser-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Chunk Structure:

Field	Type	Description
`id`	string	Completion identifier
`object`	string	`"chat.completion.chunk"`
`created`	number	Unix timestamp
`model`	string	`"webrun-browser-1"`
`choices`	array	Array of delta choices
`choices[0].index`	number	Choice index (always 0)
`choices[0].delta`	object	Content delta
`choices[0].delta.role`	string	`"assistant"` (first chunk only)
`choices[0].delta.content`	string	Text chunk
`choices[0].finish_reason`	string	`null` during stream, `"stop"` at end

Handling Streams:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.webrun.ai/v1',
  apiKey: 'YOUR_API_KEY'
});

const stream = await client.chat.completions.create({
  model: 'webrun-browser-1',
  messages: [{ role: 'user', content: 'Go to example.com' }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

Error Response Format

All errors follow this standard format:

{
  "success": false,
  "message": "Human-readable error message"
}

Common HTTP Status Codes:

Status	Meaning	Example Message
200	Success	-
400	Bad request	`"sessionId and message are required"`
401	Unauthorized	`"Invalid or revoked API key"`
402	Payment required	`"Insufficient balance."`
403	Forbidden	`"Account is deactivated"`
404	Not found	`"Session not found"`
429	Too many requests	`"Rate limit exceeded. Please try again later."`
500	Internal server error	`"Internal server error"`
503	Service unavailable	`"No available instances."`

See Rate Limits for handling 429 errors.

Usage Object Structure

The usage object appears in many responses and provides token and cost information:

interface Usage {
  prompt_tokens: number;      // Number of input tokens used
  completion_tokens: number;  // Number of output tokens generated
  total_tokens: number;       // Total tokens (prompt + completion)
  completion_time: number;    // Execution time in seconds
  cost: number;               // Cost in USD
}

Example:

{
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  }
}

Complete Event Reference Table

Event Type	REST	WebSocket	Description
`agent`	No	Yes	Live agent reasoning
`action`	No	Yes	Browser action performed
`response_update`	No	Yes	Status updates
`task_completed`	Yes (poll)	Yes	Task finished successfully
`guardrail_trigger`	Yes (poll)	Yes	Human input needed
`error`	Yes (poll)	Yes	Task failed
`end_session`	No	Yes	Session terminated
`instance:disconnected`	No	Yes	Instance connection lost
`instance:reconnected`	No	Yes	Instance recovered

Next Steps

Endpoints

Complete endpoint reference

Parameters

Parameter documentation

Events & Responses

Detailed event handling guide

WebSocket Integration

WebSocket integration guide

​Overview

​REST API Response Formats

​Inline Results (< 50 seconds)

​Pending Results (> 50 seconds)

​Polling Responses

​Still Running

​Task Completed

​Guardrail Triggered

​Task Failed

​Session Creation Response

​State Control Response

​WebSocket Event Formats

​Event: agent

​Event: action

​Event: response_update

​Event: task_completed

​Event: guardrail_trigger

​Event: error

​Connection Events

​connect

​disconnect

​error

​end_session

​instance:disconnected

​instance:reconnected

​OpenAI-Compatible Response Formats

​Non-Streaming Response

​Streaming Response (SSE)

​Error Response Format

​Usage Object Structure

​Complete Event Reference Table

​Next Steps

Endpoints

Parameters

Events & Responses

WebSocket Integration

Overview

REST API Response Formats

Inline Results (< 50 seconds)

Pending Results (> 50 seconds)

Polling Responses

Still Running

Task Completed

Guardrail Triggered

Task Failed

Session Creation Response

State Control Response

WebSocket Event Formats

Event: agent

Event: action

Event: response_update

Event: task_completed

Event: guardrail_trigger

Event: error

Connection Events

connect

disconnect

error

end_session

instance:disconnected

instance:reconnected

OpenAI-Compatible Response Formats

Non-Streaming Response

Streaming Response (SSE)

Error Response Format

Usage Object Structure

Complete Event Reference Table

Next Steps