Browser runs

client.browser_runs gives a cloud browser agent a task on the sites you allow and reads what it found. A run starts queued, moves to running, and ends succeeded, partial, failed, cancelled or timed_out. It browses only allowed_origins, in a sandbox of its own, and never submits payments, sends messages or makes other irreversible changes.

A run is billed once, when it ends: its Drex Max and LLM tokens and its browser seconds, never more than limits.max_cost_usd. Runs that never start, time out, or fail on Drex's side are not charged; a run cancelled while it runs is charged its browser seconds so far. Reading and listing runs is free. See Browser runs for prices, blocked sites, limits and retention.

A limit outside 1 to 50, a status that isn't one of BROWSER_RUN_STATUSES, an allowed_origins given as one string, or a run_id that is empty or holds /, ? or #, raises NaceError before anything is sent.

from nace_sdk import BrowserRunLimits, NaceClient

with NaceClient() as client:
    run = client.browser_runs.run(
        task="Find the price of the blue ceramic mug.",
        start_url="https://shop.example.com/",
        allowed_origins=["https://shop.example.com"],
        answer_schema={"type": "object", "properties": {"price": {"type": "string"}}, "required": ["price"]},
        limits=BrowserRunLimits(max_cost_usd=0.1, max_seconds=300),
    )
    print(run.status, run.answer, run.usage.cost_usd if run.usage else None)
    if run.outcome is not None:
        print(run.outcome.kind, run.outcome.reason)
    for artifact in client.browser_runs.artifacts(run.id).items:
        print(artifact.kind, artifact.url)

Start a runCopy Anchor Link

create and run take:

A create is refused with NaceUnprocessableEntityError when the body is invalid (invalid_request), names a site runs may not browse (origin_blocked: banking, payment, identity, large social and government sites, and hosts that aren't public), or the account has zero retention (zero_retention_unsupported). It raises NaceRateLimitError past 20 queued or running runs (rate_limited) or past the account's daily spending limit for runs (daily_spend_limit), and NaceInsufficientCreditError without spendable credit, or when a free account, or one with less than $5 of credit and no pay as you go, already has two unfinished runs and document jobs (insufficient_credit).

Wait for a runCopy Anchor Link

wait polls get every poll_interval seconds until status is succeeded, partial, failed, cancelled or timed_out, for up to timeout seconds in all, and returns the run. run does the same after its create, with wait_timeout. The default, 3000 seconds, outlasts any run: Drex times out a run queued for 15 minutes or browsing past max_seconds.

• A run that didn't succeed is returned, not raised: read status and outcome.
• Out of time: raises NaceBrowserRunTimeoutError, with error.run and error.timeout. The run keeps going; wait again or cancel it.
• run started the run, then a read failed (after its retries): raises NaceBrowserRunWaitError, with error.run_id and the original error as __cause__. The run keeps going and is billed when it ends: wait(error.run_id) or cancel it, since calling run again starts another. A failed create raises its own error. An ambiguous one, such as a connection error after the server accepted the request, may still have started the run: pass your own idempotency_key and call run again with the same key and arguments, which returns that run instead of starting a second billed one.

from nace_sdk import NaceBrowserRunTimeoutError

created = client.browser_runs.create(task=task, start_url=start_url, allowed_origins=origins)
try:
    run = client.browser_runs.wait(created.id, timeout=600)
except NaceBrowserRunTimeoutError as error:
    client.browser_runs.cancel(error.run.id)

Browser run typesCopy Anchor Link

BrowserRun, BrowserRunRef, BrowserRunArtifact and the nested types keep any other field Drex sends as an attribute and in model_extra.

An outcome's kind says why the run ended with its status:

• succeeded: completed, or not_found when what the task asked for isn't there.
• partial: blocked_login, blocked_captcha, risky_action_denied or limit_reached.
• failed: site_error, internal_error, or answer_invalid when the answer didn't match answer_schema.
• cancelled and timed_out: the same as the status.