> ## Documentation Index > Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Response Formats > Complete reference for all WebRun API response formats ## 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:** ```json theme={null} { "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:** ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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`: ```json theme={null} { "sessionId": "a1b2c3d4e5f6", "message": { "actionType": "guardrail", "prompt": "Username: user@example.com, Password: pass123", "newState": "resume" } } ``` *** #### Task Failed ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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: ```javascript theme={null} socket.on("message", (data) => { console.log(data.type, data); }); ``` ### Event: agent Live agent thoughts and reasoning during task execution. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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:** ```javascript theme={null} socket.emit("message", { actionType: "guardrail", prompt: "Username: demo@example.com, Password: demo123", newState: "resume" }); ``` *** ### Event: error Task failed with error. ```json theme={null} { "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. ```javascript theme={null} socket.on("connect", () => { console.log("Connected to session"); }); ``` *** #### disconnect Socket disconnected. ```javascript theme={null} socket.on("disconnect", () => { console.log("Disconnected from session"); }); ``` *** #### error Socket error occurred. ```javascript theme={null} socket.on("error", (err) => { console.error("Socket error:", err); }); ``` *** #### end\_session Session terminated by server. ```json theme={null} { "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 ```javascript theme={null} socket.on("end_session", (data) => { console.log("Session ended:", data.reason); }); ``` *** #### instance:disconnected Instance connection lost. Session enters grace period for reconnection. ```json theme={null} { "gracePeriod": 300000 } ``` ```javascript theme={null} socket.on("instance:disconnected", (data) => { console.log("Instance lost, waiting for reconnection..."); console.log("Grace period:", data.gracePeriod, "ms"); }); ``` *** #### instance:reconnected Instance connection recovered. ```javascript theme={null} socket.on("instance:reconnected", (data) => { console.log("Instance reconnected"); }); ``` *** ## OpenAI-Compatible Response Formats ### Non-Streaming Response `POST /v1/chat/completions` with `stream: false` (default). ```json theme={null} { "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:** ```javascript theme={null} 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: ```json theme={null} { "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](/api-reference/rate-limits) for handling 429 errors. *** ## Usage Object Structure The `usage` object appears in many responses and provides token and cost information: ```typescript theme={null} 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:** ```json theme={null} { "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 Complete endpoint reference Parameter documentation Detailed event handling guide WebSocket integration guide This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.