Skip to main content

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.

​
Synchronous vs Asynchronous

WebRun uses a hybrid response model that combines the simplicity of synchronous APIs with the reliability of asynchronous polling:
  • Tasks completing in < 50 seconds: Result returned inline (synchronous)
  • Tasks taking > 50 seconds: Poll URL returned for async polling
This design eliminates unnecessary polling for the 90% of tasks that complete quickly, while gracefully handling longer operations.

​
Why This Design?

Pure sync doesn’t work because HTTP timeouts (30-60s) are too short for complex browser tasks. Pure async doesn’t work because polling adds unnecessary complexity for simple tasks that finish in seconds. The hybrid approach waits up to 50 seconds. If the task finishes in time, the result comes back inline. If not, you get a poll URL. In practice, ~90% of tasks return inline.

​
How It Works

POST /start/run-task
     ↓
WebRun starts task
     ↓
Wait up to 50 seconds
     ↓
┌────────────────────────────────────┐
│  Did task complete in < 50s?       │
│                                    │
│  YES → Return result inline        │
│  NO  → Return pollUrl              │
└────────────────────────────────────┘

​
Inline Response (< 50 seconds)

When your task completes within 50 seconds, you get the full result in the initial response: Request: 
POST /start/run-task
{
  "prompt": "Search Google for Anthropic"
}
Response: 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Successfully searched for Anthropic on Google",
    "files": [],
    "network": [
      {
        "id": "tevo9",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://www.google.com/search?q=Anthropic",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  }
}
Key indicator: type: "task_completed"

​
Pending Response (> 50 seconds)

For tasks that take longer than 50 seconds, you receive a pollUrl immediately: Request: 
POST /start/run-task
{
  "prompt": "Complete a complex multi-step workflow"
}
Response (after 50 seconds): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pollUrl": "https://connect.webrun.ai/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}
Key indicator: status: "pending" You must then poll the pollUrl until the task completes.

​
Polling for Results

​
Polling Endpoint

GET /task/:sessionId/:taskId

​
Poll Until Completion

Poll every 2-3 seconds until you receive a final state: 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
  }
}
Completed: 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "type": "task_completed",
  "data": {
    "message": "Task finished successfully",
    "files": [],
    "network": [
      {
        "id": "abc12",
        "taskId": "x9y8z7w6v5u4",
        "urls": [
          {
            "url": "https://example.com/page",
            "timestamp": 1771138379087.646
          }
        ]
      }
    ]
  },
  "usage": {
    "prompt_tokens": 15420,
    "completion_tokens": 4200,
    "total_tokens": 19620,
    "completion_time": 87.3,
    "cost": 0.0187
  }
}
Guardrail Triggered: 
{
  "success": true,
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials"
  }
}
Failed: 
{
  "success": false,
  "status": "failed",
  "error": "Navigation timeout after 30 seconds",
  "code": "NAVIGATION_TIMEOUT"
}

​
Polling Best Practices

​
1. Poll Interval

Poll every 2-3 seconds. Faster polling wastes resources; slower polling adds unnecessary latency. 
const POLL_INTERVAL = 2000; // 2 seconds

​
2. Maximum Attempts

Set a reasonable timeout (e.g., 2 minutes = 60 attempts at 2-second intervals): 
const MAX_ATTEMPTS = 60;

​
3. Handle All Terminal States

Check for all possible completion states: 
if (data.type === "task_completed") return data;
if (data.type === "guardrail_trigger") return data;
if (data.status === "failed") throw new Error(data.error);
if (data.status === "terminated") throw new Error("Session terminated");

​
4. Track Incremental Cost

The polling endpoint includes current cost in the usage object, allowing you to monitor spending in real-time.

​
Complete Polling Implementation

async function pollForResult(sessionId, taskId, apiKey) {
  const maxAttempts = 60; // 2 minutes
  const interval = 2000; // 2 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `https://connect.webrun.ai/task/${sessionId}/${taskId}`,
      { headers: { "Authorization": `Bearer ${apiKey}` } }
    );

    if (!res.ok) {
      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
    }

    const data = await res.json();

    // Terminal states
    if (data.type === "task_completed") return data;
    if (data.type === "guardrail_trigger") return data;
    if (data.status === "failed") throw new Error(data.error || "Task failed");
    if (data.status === "terminated") throw new Error("Session terminated");

    // Still running
    if (data.pending || data.status === "active") {
      console.log(`Poll ${i + 1}/${maxAttempts}: Still running (cost so far: $${data.usage?.cost || 0})`);
      await new Promise(r => setTimeout(r, interval));
      continue;
    }

    // Unexpected state
    return data;
  }

  throw new Error("Polling timeout after 2 minutes");
}

​
Unified Request Handler

Handle both inline and pending responses with a single function: 
async function runTask(prompt, apiKey) {
  // Initial request
  const response = await fetch("https://connect.webrun.ai/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({ prompt })
  });

  const data = await response.json();

  // Inline result
  if (data.status === "complete") {
    return data.result;
  }

  // Pending - start polling
  if (data.status === "pending") {
    return await pollForResult(data.sessionId, data.taskId, apiKey);
  }

  throw new Error(data.message || "Task failed");
}

// Usage
const result = await runTask("Search Google for Anthropic", "enig_xxx");
console.log(result.data.message);

​
WebSocket Alternative

For real-time updates without polling, use WebSocket: 
socket.on("message", (data) => {
  if (data.type === "task_completed") {
    console.log("Done:", data.data.message);
  }
});
WebSocket removes the need for polling entirely by pushing updates as they occur. Learn more about WebSocket →

​
Response Time Distribution

Based on typical usage patterns:
Task TypeTypical DurationResponse Mode
Simple search10-20sInline
Form filling20-40sInline
Multi-step navigation40-80sPolling
Complex workflow80-180sPolling
~90% of tasks complete within 50 seconds and return inline.