Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

browserwhale (Python)

Python client for the hosted Browserwhale API: give it a URL and a goal in plain language, and a web agent does the task in a real, disposable browser.

Install it with pip install --pre browserwhale (beta). Python 3.9 or later, no dependencies (it uses the standard library).

Run a task

from browserwhale import Whale

whale = Whale()  # BROWSERWHALE_API_KEY and BROWSERWHALE_BASE_URL

task = whale.run(
    url="https://example.com",
    goal="Find the page's main heading.",
    output_schema={"type": "object", "properties": {"heading": {"type": "string"}}},
)
print(task["output"])  # {'heading': 'Example Domain'}
for step in task["steps"]:
    print(step["n"], step["description"])  # 1 Opening the website

run() creates the task, waits until it finishes and returns the task when it is completed. Tasks are plain dicts typed with TypedDict (Task), with the API's snake_case field names.

To run a task in an open session (see the API docs, "Sessions"), pass session_id=; a later task in it may pass url=None to continue on the current page. This client does not open or close sessions yet; use the HTTP API for that.

Live progress

Pass on_progress to see each step as it happens:

task = whale.run(
    url="https://example.com",
    goal="Find the page's main heading.",
    on_progress=lambda step: print(f"Step {step['n']} · {step['description']}"),
)

For more control, whale.tasks.events(task_id) yields every step, each status change and finally done with the task. It reconnects on its own, resuming after the last step it saw:

for event in whale.tasks.events(task["id"]):
    if event["type"] == "step":
        print(event["step"]["description"])
    elif event["type"] == "done":
        print(event["task"]["status"])

Opt-in features

All off by default:

task = whale.run(
    url="https://shop.example",
    goal="Add the cheapest kettle to the cart.",
    notes="The catalogue is under Shop > Kitchen.",  # your own steps or hints
    skills="auto",  # or ["shopping"]
    vision="fallback",  # look at the screen for drawn content such as seat maps
    cache="read-write",  # reuse an earlier completed run of the same request
    site_context="read-write",  # remember how the site works between your tasks
)

cache and site_context keep data between the tasks of one API key (never shared with another key, even in the same team), and only servers that store task data accept them.

Tasks that do not complete

Any other final status raises TaskFailedError; its task keeps the partial results, the limitations with plain reasons, and the cause (site_blocked, unavailable, limit_reached, could_not_complete, cancelled, internal_error). run(timeout=...) (seconds, default 15 minutes) raises WaitTimeoutError when it stops waiting; the task may still be running. Interrupting run() (Ctrl+C) cancels the task.

Errors

Error When
AuthenticationError Missing or invalid API key (401).
InvalidRequestError The request failed validation (400, 413, 422); param names the field.
NotFoundError No such task for this key (404).
ConflictError An idempotency key reused with a different body (409).
RateLimitError Rate limit or concurrent-task cap reached (429). retry_after is in seconds; code is rate_limit_exceeded or concurrency_limit_exceeded.
InternalServerError A server error (5xx).
APIConnectionError No response: a network failure or request timeout.

All derive from WhaleError; the HTTP ones from ApiError (status, type, param, request_id). The client retries 429, 5xx and network failures (max_retries, default 2), honouring Retry-After. Every create carries an Idempotency-Key, reused across retries, so a retried create never starts a second task.

Usage and cost

whale.usage(month="2026-11") returns the key's tasks, model calls, tokens, browser time and cost for a calendar month (UTC; the current month by default). Tasks that never started or failed with internal_error cost nothing.

Lower-level control

whale.tasks.create(params), get(id, wait=30), list(limit=, cursor=), events(id) and cancel(id) map one-to-one to the REST endpoints.

Metadata

Release files for browserwhale 0.1.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for browserwhale 0.1.0b1
File Size Uploaded Provenance Actions
browserwhale-0.1.0b1.tar.gz 15.3 kB Without provenance Details for browserwhale-0.1.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for browserwhale 0.1.0b1
File Interpreter ABI Platform Actions
browserwhale-0.1.0b1-py3-none-any.whl Python 3 none any Details for browserwhale-0.1.0b1-py3-none-any.whl

Total release size: 33.4 kB

Release files / browserwhale-0.1.0b1.tar.gz

Download URL browserwhale-0.1.0b1.tar.gz
Size 15.3 kB
Tags Source
SHA-256 checksum
How to use checksums
8e47c9fa40f835808bf6c1871ee38c936ccb1e7d7c687a24cd1dab56b1dced53
BLAKE2b-256 checksum
How to use checksums
fb2b7331856f2cdcc54847e80f4701bb32ac33533ff8f8f713b8efaa300bece9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / browserwhale-0.1.0b1-py3-none-any.whl

Download URL browserwhale-0.1.0b1-py3-none-any.whl
Size 18.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d6e3d01224d633cba875a405c7cbdf9c2690ffca45691a8c4bc48e97c970c1d7
BLAKE2b-256 checksum
How to use checksums
6565eaece9104b18e2a64eaecba8c82ee1cad3717f57e2cd2771e409c9a90fd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for browserwhale 0.1.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page