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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.