Python browser SDK

pip install predev-api

This guide targets published 1.1.0. See SDK setup for configuration and general errors.

Submit and poll

import os
import time
from predev_api import PredevAPI

client = PredevAPI(api_key=os.environ["PREDEV_API_KEY"])
tasks = [{
    "url": "https://example.com",
    "instruction": "Extract the main page heading.",
    "output": {
        "type": "object",
        "properties": {"heading": {"type": "string"}},
        "required": ["heading"],
    },
    "mode": "extract",
    "maxSteps": 10,
    "maxDurationSeconds": 120,
}]
job = client.browser_agent(tasks, run_async=True)
print("Save this ID:", job["id"])
deadline = time.monotonic() + 600

while time.monotonic() < deadline:
    run = client.get_browser_agent(job["id"])
    if run["status"] in ("completed", "failed"):
        for task in run["results"]:
            if task and task.get("status") == "SUCCESS":
                print(task.get("data"))
            else:
                print("Task failed:", (task or {}).get("error", "No result"))
        break
    time.sleep(5)
else:
    raise TimeoutError("Polling deadline reached; retrieve the saved run later.")

The SDK passes task dictionaries through to REST, including the current per-task controls. run_async=True submits asynchronous server work; the Python method itself blocks until the submission response arrives.

Method options

Method	Options
`browser_agent(tasks, ...)`	`concurrency`, `stream=False`, `run_async=False`
`get_browser_agent(id, ...)`	`include_events=False`
`list_browser_agents(...)`	`limit`, `skip`, `status`
`browser_agent_status()`	None

Browser submission requests use a 300-second HTTP timeout, retrieval/list requests 60 seconds, and queue status 30 seconds. Use async submission for longer tasks. There is no exposed client-wide timeout or retry option.

Stream a new submission

Reuse client and tasks from the example above:

saw_done = False
for message in client.browser_agent(tasks, stream=True):
    if message["event"] == "task_event":
        print(message["data"]["taskIndex"], message["data"]["type"])
    elif message["event"] == "done":
        saw_done = True
        run = message["data"]
        print(run["status"], run["totalCreditsUsed"])
if not saw_done:
    raise RuntimeError("The stream ended before a final result arrived.")

This call creates a new run. Streamed error frames raise SDK exceptions. A clean iterator exit without done still requires recovery; the SDK does not make EOF a terminal success. To attach to a saved async ID, use existing-run SSE over direct HTTP.

History and evidence

queue = client.browser_agent_status()
print(queue["total"], queue["cap"])

page = client.list_browser_agents(limit=20, status="completed")
for summary in page["batches"]:
    print(summary["id"], summary["totalCreditsUsed"])

run = client.get_browser_agent(job["id"], include_events=True)

include_events=True adds available timelines and screenshots. Routine polling should omit it. Status and results explains pending stubs, null slots, uppercase task statuses, and lowercase batch statuses.

Billing and queue errors

from predev_api import InsufficientCreditsError, QueueFullError, PredevAPIError

try:
    job = client.browser_agent(tasks, run_async=True)
except InsufficientCreditsError as error:
    print(str(error), error.action_url)
except QueueFullError:
    print("Wait for tasks to finish before submitting more work.")
except PredevAPIError as error:
    print(str(error))

Use direct REST when a retry needs an idempotency key; the SDK has no idempotency or arbitrary-header option.

Get started

API reference

SDKs

Migrations

Python browser SDK

Submit and poll

Method options

Stream a new submission

History and evidence

Billing and queue errors

​Submit and poll

​Method options

​Stream a new submission

​History and evidence

​Billing and queue errors

Submit and poll

Method options

Stream a new submission

History and evidence

Billing and queue errors