> ## 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.

# Quickstart

> Run your first browser automation task in under 5 minutes

## Get Your API Key

1. Sign up at [webrun.ai](https://webrun.ai)
2. Navigate to **Settings → API Keys**
3. Click **Create API Key** and save it

```
enig_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  Sessions cost money until terminated. Set `terminateOnCompletion: true` on your final task or explicitly terminate when done.
</Warning>

***

## Run Your First Task

The simplest approach: one API call that creates a session, runs your task, and auto-terminates.

```bash theme={null}
curl -X POST https://connect.webrun.ai/start/run-task \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "task": {
      "prompt": "Go to google.com and search for Anthropic"
    }
  }'
```

**If the task completes within 50 seconds**, you get the result immediately:

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3",
  "taskId": "x9y8z7",
  "type": "task_completed",
  "data": {
    "message": "Successfully searched for Anthropic on Google"
  },
  "usage": {
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5,
    "cost": 0.0124
  }
}
```

**If the task takes longer**, you'll get a polling URL:

```json theme={null}
{
  "success": true,
  "sessionId": "a1b2c3",
  "taskId": "x9y8z7",
  "status": "pending",
  "pollUrl": "https://connect.webrun.ai/task/a1b2c3/x9y8z7"
}
```

Poll the URL every 2-3 seconds until the task completes. Most tasks finish in 10-40 seconds, so faster polling wastes API quota while slower polling adds latency.

***

## Multi-Task Sessions

For multiple tasks in sequence, create a persistent session:

**1. Create the session**

```bash theme={null}
curl -X POST https://connect.webrun.ai/start/start-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "mode": "default",
    "task": {
      "prompt": "Go to amazon.com",
      "startingUrl": "https://amazon.com"
    }
  }'
```

**2. Send follow-up tasks**

```bash theme={null}
curl -X POST https://connect.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "SESSION_ID",
    "message": {
      "actionType": "newTask",
      "newState": "start",
      "prompt": "Search for wireless keyboards",
      "startingUrl": "https://amazon.com"
    }
  }'
```

**3. Terminate when finished**

```bash theme={null}
curl -X POST https://connect.webrun.ai/start/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sessionId": "SESSION_ID",
    "message": {
      "actionType": "state",
      "newState": "terminate"
    }
  }'
```

Alternatively, set `terminateOnCompletion: true` on your last task to auto-terminate the session.

[Multi-task workflows guide](/usage-guides/multi-task-workflows)

***

## Polling for Results

When a task returns `status: "pending"`, poll the URL until completion.

```javascript theme={null}
async function runTask(prompt, apiKey) {
  // Start the task
  const response = await fetch("https://connect.webrun.ai/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({ task: { prompt } })
  });

  const data = await response.json();

  // Return immediately if complete
  if (data.type === "task_completed") {
    return data;
  }

  // Poll if still running
  if (data.status === "pending") {
    return await pollForResult(data.sessionId, data.taskId, apiKey);
  }

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

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

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

    const data = await res.json();

    if (data.type === "task_completed") return data;
    if (data.type === "guardrail_trigger") return data;
    if (!data.success && data.type === "failed") {
      throw new Error(data.error);
    }

    await new Promise(r => setTimeout(r, interval));
  }

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

// Usage
const result = await runTask("Search Google for Anthropic", "enig_xxx");
console.log(result.data.message);
console.log(`Cost: $${result.usage.cost}`);
```

This handles both instant and long-running tasks automatically.

***

## Real-Time Updates with WebSocket

For live agent thoughts and action notifications, use WebSocket. This requires more setup but gives you sub-second visibility into task execution.

[WebSocket integration guide](/integrations/websocket)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Task Workflows" icon="list-check" href="/usage-guides/multi-task-workflows">
    Chain multiple tasks in a session
  </Card>

  <Card title="MCP Integration" icon="robot" href="/getting-started/mcp-quickstart">
    Set up Claude Desktop integration
  </Card>

  <Card title="Video Streaming" icon="video" href="/usage-guides/video-streaming">
    Watch sessions execute in real-time
  </Card>

  <Card title="Cost Optimization" icon="piggy-bank" href="/usage-guides/cost-optimization">
    Reduce costs and improve efficiency
  </Card>

  <Card title="File Uploads" icon="file-arrow-up" href="/environments/file-uploads">
    Upload files for the agent to use in sessions
  </Card>
</CardGroup>