Response Model

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://api.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://api.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://api.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", "wr_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 Type	Typical Duration	Response Mode
Simple search	10-20s	Inline
Form filling	20-40s	Inline
Multi-step navigation	40-80s	Polling
Complex workflow	80-180s	Polling

~90% of tasks complete within 50 seconds and return inline.

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Synchronous vs Asynchronous

Why This Design?

How It Works

Inline Response (< 50 seconds)

Pending Response (> 50 seconds)

Polling for Results

Polling Endpoint

Poll Until Completion

Polling Best Practices

1. Poll Interval

2. Maximum Attempts

3. Handle All Terminal States

4. Track Incremental Cost

Complete Polling Implementation

Unified Request Handler

WebSocket Alternative

Response Time Distribution

​Synchronous vs Asynchronous

​Why This Design?

​How It Works

​Inline Response (< 50 seconds)

​Pending Response (> 50 seconds)

​Polling for Results

​Polling Endpoint

​Poll Until Completion

​Polling Best Practices

​1. Poll Interval

​2. Maximum Attempts

​3. Handle All Terminal States

​4. Track Incremental Cost

​Complete Polling Implementation

​Unified Request Handler

​WebSocket Alternative

​Response Time Distribution

API Endpoints

WebSocket Events

Synchronous vs Asynchronous

Why This Design?

How It Works

Inline Response (< 50 seconds)

Pending Response (> 50 seconds)

Polling for Results

Polling Endpoint

Poll Until Completion

Polling Best Practices

1. Poll Interval

2. Maximum Attempts

3. Handle All Terminal States

4. Track Incremental Cost

Complete Polling Implementation

Unified Request Handler

WebSocket Alternative

Response Time Distribution