Polling - Narada

Overview

Polling provides a pull-based mechanism for retrieving automation task results. After submitting a task via the Remote Dispatch API, you can periodically check for completion using the Get Task Status endpoint.

Simple Setup

No webhook endpoints or server infrastructure required to get started

Firewall Friendly

Works in restricted network environments without opening inbound ports

No Server Required

Perfect for scripts, CLI tools, and applications without a web server

Full Control

You decide when and how often to check for results

How Polling Works

When you submit an automation task, you receive a requestId that you can use to poll for the task status until it completes.

Submit Task

Send a request to the Remote Dispatch API and receive a requestId

Wait

Wait for an appropriate interval before checking status

Check Status

Call the Get Task Status endpoint with your requestId

Handle Response

If status is pending, go back to step 2. Otherwise, process the result.

Polling is ideal for simple integrations, scripts, and environments where setting up webhook endpoints isn’t feasible.

Basic Implementation

Here’s how to implement basic polling in different languages:

# Submit the task
REQUEST_ID=$(curl -s -X POST 'https://api.narada.ai/fast/v2/remote-dispatch' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "prompt": "/Operator search for software engineering jobs",
    "browserWindowId": "your-browser-window-id"
  }' | jq -r '.requestId')

echo "Task submitted: $REQUEST_ID"

# Poll for completion
while true; do
  RESPONSE=$(curl -s -X GET "https://api.narada.ai/fast/v2/remote-dispatch/responses/$REQUEST_ID" \
    -H 'x-api-key: YOUR_API_KEY')

  STATUS=$(echo $RESPONSE | jq -r '.status')

  if [ "$STATUS" != "pending" ]; then
    echo "Task completed with status: $STATUS"
    echo $RESPONSE | jq '.response'
    break
  fi

  echo "Task still pending, waiting 5 seconds..."
  sleep 5
done

async function submitAndPoll(prompt, browserWindowId) {
  // Submit the task
  const submitResponse = await fetch(
    "https://api.narada.ai/fast/v2/remote-dispatch",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.NARADA_API_KEY,
      },
      body: JSON.stringify({
        prompt,
        browserWindowId,
      }),
    }
  );

  const { requestId } = await submitResponse.json();
  console.log(`Task submitted: ${requestId}`);

  // Poll for completion
  while (true) {
    const statusResponse = await fetch(
      `https://api.narada.ai/fast/v2/remote-dispatch/responses/${requestId}`,
      {
        headers: {
          "x-api-key": process.env.NARADA_API_KEY,
        },
      }
    );

    const result = await statusResponse.json();

    if (result.status !== "pending") {
      console.log(`Task completed with status: ${result.status}`);
      return result;
    }

    console.log("Task still pending, waiting 5 seconds...");
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

// Usage
const result = await submitAndPoll(
  "/Operator search for software engineering jobs",
  "your-browser-window-id"
);
console.log(result.response?.text);

import requests
import time
import os

def submit_and_poll(prompt: str, browser_window_id: str) -> dict:
    api_key = os.getenv('NARADA_API_KEY')

    # Submit the task
    submit_response = requests.post(
        'https://api.narada.ai/fast/v2/remote-dispatch',
        headers={
            'Content-Type': 'application/json',
            'x-api-key': api_key
        },
        json={
            'prompt': prompt,
            'browserWindowId': browser_window_id
        }
    )

    request_id = submit_response.json()['requestId']
    print(f"Task submitted: {request_id}")

    # Poll for completion
    while True:
        status_response = requests.get(
            f'https://api.narada.ai/fast/v2/remote-dispatch/responses/{request_id}',
            headers={'x-api-key': api_key}
        )

        result = status_response.json()

        if result['status'] != 'pending':
            print(f"Task completed with status: {result['status']}")
            return result

        print("Task still pending, waiting 5 seconds...")
        time.sleep(5)

# Usage
result = submit_and_poll(
    '/Operator search for software engineering jobs',
    'your-browser-window-id'
)
print(result.get('response', {}).get('text'))

Polling with Timeout

Here’s a complete example with timeout handling:

import requests
import time
import os

def poll_for_result(request_id: str, timeout: int = 300, poll_interval: int = 5) -> dict:
    """Poll for task completion with timeout."""
    api_key = os.environ['NARADA_API_KEY']
    deadline = time.time() + timeout

    while True:
        remaining = deadline - time.time()
        if remaining <= 0:
            raise TimeoutError(f"Task did not complete within {timeout}s")

        # Check status
        response = requests.get(
            f'https://api.narada.ai/fast/v2/remote-dispatch/responses/{request_id}',
            headers={'x-api-key': api_key}
        )
        result = response.json()

        if result['status'] != 'pending':
            return result

        time.sleep(min(poll_interval, remaining))

# Usage
try:
    result = poll_for_result('req_abc123def456', timeout=120)

    if result['status'] == 'success':
        print(f"Success: {result['response']['text']}")
    elif result['status'] == 'error':
        print(f"Error: {result['response']['text']}")
    elif result['status'] == 'input-required':
        print(f"Input required: {result['response']['text']}")

except TimeoutError as e:
    print(f"Timeout: {e}")

Response Handling

The Get Task Status endpoint returns different statuses that you should handle appropriately:

Pending
Success
Error
Input Required

{
  "status": "pending",
  "response": null,
  "createdAt": "2024-12-19T00:00:00.000000+00:00",
  "completedAt": null
}

The task is still running. Continue polling after waiting.

{
  "status": "success",
  "response": {
    "text": "Found 1,234 software engineering job listings.",
    "structuredOutput": {
      "count": 1234,
      "query": "software engineering jobs"
    }
  },
  "createdAt": "2024-12-19T00:00:00.000000+00:00",
  "completedAt": "2024-12-19T00:00:45.000000+00:00"
}

The task completed successfully. Process the response data.

{
  "status": "error",
  "response": {
    "text": "Failed to complete the task due to network timeout."
  },
  "createdAt": "2024-12-19T00:00:00.000000+00:00",
  "completedAt": "2024-12-19T00:02:30.000000+00:00"
}

The task failed. Log the error and implement retry logic if appropriate.

{
  "status": "input-required",
  "response": {
    "text": "The task requires authentication. Please log in to continue."
  },
  "createdAt": "2024-12-19T00:00:00.000000+00:00",
  "completedAt": null
}

The task needs user input. Notify the user or handle programmatically.

Best Practices

Use Reasonable Intervals

Poll every 5-10 seconds to balance responsiveness with API efficiency

Set Timeouts

Always implement maximum timeouts to prevent infinite polling loops

Handle All Statuses

Implement handlers for success, error, input-required, and timeout scenarios

Log Progress

Log polling attempts for debugging and monitoring purposes

Handle Network Errors

Wrap API calls in try-except to handle transient network failures gracefully

Consider Webhooks

For production apps with many concurrent tasks, webhooks may be more efficient

Comparison: Polling vs Webhooks

Feature	Polling	Webhooks
Setup Complexity	Low	Medium
Infrastructure	None required	Web server needed
Real-time Updates	No (delayed by interval)	Yes
Resource Usage	Higher (active requests)	Lower
Firewall Friendly	Yes	Requires open ports
Scalability	Limited	Excellent
Best For	Scripts, simple apps	Production systems

Start with polling for development and simple use cases. Migrate to webhooks when you need real-time notifications or are handling high volumes of tasks.

Common Issues

Polling Too Frequently

Problem: Making too many requests and hitting rate limits.Solution: Use a reasonable polling interval of 5-10 seconds. This balances responsiveness with API efficiency.

POLL_INTERVAL = 5  # seconds - good balance for most use cases
time.sleep(POLL_INTERVAL)

No Timeout Implemented

Problem: Script runs forever if a task never completes.Solution: Always set a maximum timeout for your polling loop.

start = time.time()
while time.time() - start < MAX_TIMEOUT:
    # poll...
raise TimeoutError("Task did not complete in time")

Not Handling All Status Types

Problem: Code breaks when receiving unexpected status values.Solution: Handle all possible statuses: pending, success, error, and input-required.

if result['status'] == 'success':
    handle_success(result)
elif result['status'] == 'error':
    handle_error(result)
elif result['status'] == 'input-required':
    handle_input_required(result)

Missing Error Handling for API Calls

Problem: Network errors crash the polling loop.Solution: Wrap API calls in try-except and implement retry logic.

try:
    response = requests.get(url, headers=headers, timeout=10)
    response.raise_for_status()
except requests.RequestException as e:
    logger.warning(f"API request failed: {e}, retrying...")
    time.sleep(interval)
    continue

​Overview

Simple Setup

Firewall Friendly

No Server Required

Full Control

​How Polling Works

​Basic Implementation

​Polling with Timeout

​Response Handling

​Best Practices

Use Reasonable Intervals

Set Timeouts

Handle All Statuses

Log Progress

Handle Network Errors

Consider Webhooks

​Comparison: Polling vs Webhooks

​Common Issues

Overview

How Polling Works

Basic Implementation

Polling with Timeout

Response Handling

Best Practices

Comparison: Polling vs Webhooks

Common Issues