Custom Browsing Scripts

Custom Scripts

Custom scripts use the script field instead of a natural-language task. They follow the standard browser-use API — the browser and session objects exposed to your script are browser-use objects.

Custom scripts require API key permission. Request access via chat in the dashboard . Without permission, the API returns 403:


{ "error": "custom browsing scripts are not enabled for this API key" }

Quick start

Minimal script body (not a full Python file):


await browser.navigate_to("https://example.com")
return {
    "ok": True,
    "url": "https://example.com",
}

Run via async endpoint:


curl -sS -X POST "https://llm.dat.ai/api/v1/browsing/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "await browser.navigate_to(\"https://example.com\")\nreturn {\"ok\": true, \"url\": \"https://example.com\"}",
    "fanout": 1,
    "timeout": 300000
  }'

Poll for the result:


curl -sS "https://llm.dat.ai/api/v1/browsing/status?task_id=web:YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

What you send

The script field is the body of an async function — use await directly. Do not wrap it in async def main() or call asyncio.run(...).

Available variables

Name	Description
`browser`	Main browser-use object for navigation and page actions
`session`	Lower-level browser-use session object
`asyncio`	Python asyncio module
`json`	Python json module
`os`	Python os module
`sys`	Python sys module

For navigation:


await browser.navigate_to("https://example.com")

Returning results

Return JSON-serializable data (dict, list, string, number, bool, or null). The value becomes the task payload when success is true.

Limits

Limit	Value
Maximum script size	24 KB
Maximum task timeout	10,800,000 ms (3 hours)
`fanout`	1 to 10
`session_key` length	128 characters
`uv_args` length	1024 characters

timeout is always in milliseconds (e.g. 5 minutes = 300000).

Use uv_args to install extra Python packages on the node for your script.

Example: extract page title


await browser.navigate_to("https://example.com")
 
title = await browser.get_current_page_title()
url = await browser.get_current_page_url()
 
return {
    "ok": True,
    "title": title,
    "url": url,
}

Example: run JavaScript


await browser.navigate_to("https://example.com")
 
page = await browser.get_current_page()
if page is None:
    return {
        "ok": False,
        "error": "No active page after navigation",
    }
 
data = await page.evaluate("""
() => ({
  title: document.title,
  h1: document.querySelector("h1")?.innerText || null
})
""")
 
return { "ok": True, "data": data }