Skip to main content

​
Synchronous vs Asynchronous

Enigma 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?

​
The Problem with Pure Sync

Typical HTTP timeouts (30-60 seconds) are too short for complex browser tasks. Forcing all requests to be synchronous would cause frequent timeouts.

​
The Problem with Pure Async

Always requiring polling adds complexity and latency for simple tasks that complete in seconds.

​
The Enigma Solution

Wait up to 50 seconds for task completion. If it finishes in time, return the result immediately. Otherwise, return a poll URL. Result: 90% of tasks get instant responses, 10% use polling only when needed.

​
How It Works

POST /start/run-task
     ↓
Enigma 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
{
  "taskDetails": "Search Google for Anthropic"
}
Response: 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "complete",
  "result": {
    "type": "task_completed",
    "data": {
      "message": "Successfully searched for Anthropic on Google",
      "completion_time": 23.5,
      "prompt_tokens": 12450,
      "completion_tokens": 3200,
      "total_tokens": 15650
    },
    "usage": {
      "cost": 0.0124
    }
  }
}
Key indicator: status: "complete"

​
Pending Response (> 50 seconds)

For tasks that take longer than 50 seconds, you receive a pollUrl immediately: Request: 
POST /start/run-task
{
  "taskDetails": "Complete a complex multi-step workflow"
}
Response (after 50 seconds): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pollUrl": "https://connect.enigma.click/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,
  "status": "active",
  "pending": true,
  "usage": {
    "inputTokens": 8000,
    "outputTokens": 2100,
    "computeTime": 3,
    "cost": 0.0067
  }
}
Completed: 
{
  "success": true,
  "type": "task_completed",
  "data": {
    "message": "Task finished successfully",
    "prompt_tokens": 15420,
    "completion_tokens": 4200,
    "total_tokens": 19620,
    "completion_time": 87.3
  },
  "usage": {
    "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.enigma.click/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(taskDetails, apiKey) {
  // Initial request
  const response = await fetch("https://connect.enigma.click/start/run-task", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({ taskDetails })
  });

  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.

API Endpoints

Full endpoint reference

WebSocket Events

Real-time alternative to polling

Response Formats

All response types documented

Quickstart

See polling in action