Browser runs

A browser run is a cloud browser agent that does one task, in plain language, on the sites you allow, and answers in text or in JSON matching your answer_schema. A create answers at once with the queued run; read it until its status is final, or run and wait in one call. See Browser runs for what a run can and can't do.

Each run is billed once, when it ends: its Drex Max and LLM tokens plus its browser seconds, at the published prices, never more than limits.max_cost_usd. A run that never starts, times out, or fails on Drex's side isn't charged; one you cancel while it runs is charged its browser seconds so far. Reading, listing and artifacts are free.

browserRuns.create and browserRuns.run take a CreateBrowserRunParams:

browserRuns.list takes a BrowserRunListParams:

• Ids: a run id is brun_ and 32 hex characters. Another account's run answers 404 (NotFoundError, code not_found), like one that doesn't exist. An empty id, or one with /, ? or #, throws a NaceError before sending. While browser runs aren't available on a deployment, every browser route answers a plain 404.
• Refusals: a start URL or origin on a banking, payment, identity, large social or government site, or on a host that isn't public, answers 422 (UnprocessableEntityError, code origin_blocked). An account with zero retention can't create runs (422, code zero_retention_unsupported). More than 20 queued or running runs, or more than $20 of runs in 24 hours, answers 429 (RateLimitError, code rate_limited or daily_spend_limit). 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, it answers 402 (InsufficientCreditError, code insufficient_credit).
• Retention: a run's task, URLs, answer and steps are erased 48 hours after it ends; task then reads empty.

A BrowserRunRef has id, object ("browser_run"), status and created_at.

A BrowserRun has id, object, status, task, start_url, allowed_origins, risky_actions, limits, answer (the structured answer, or null), answer_text, outcome, final_url, steps (only from get; each a BrowserRunStep the agent reported), pending_approval (always null), usage, artifacts_url, metadata, created_at, started_at and finished_at.

A BrowserRunStatus is queued, then running, then one of succeeded, partial, failed, cancelled or timed_out.

A BrowserRunOutcome has kind, reason and evidence, a list of the pages the agent cites. A BrowserRunEvidence has url and text. A BrowserRunOutcomeKind is completed or not_found on a run that succeeded; blocked_login, blocked_captcha, risky_action_denied or limit_reached on a partial one; site_error, internal_error or answer_invalid on a failed one; and cancelled or timed_out.

A BrowserRunUsage has drex_input_tokens, llm_input_tokens, llm_output_tokens, browser_seconds and cost_usd: what the run was charged, null until it ended and 0 when it wasn't charged.

A BrowserRunList has items and next_cursor. A BrowserRunArtifactList has items. A BrowserRunArtifact has kind (such as "screenshot"), step, url and expires_at, when the https link stops working.

const started = await client.browserRuns.create({
  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: "number" }, currency: { type: "string" } },
    required: ["price", "currency"],
  },
  limits: { max_cost_usd: 0.1, max_seconds: 300 },
  metadata: { order: "42" },
});

const latest = await client.browserRuns.get(started.id);
console.log(latest.status, latest.answer, latest.usage?.cost_usd);

const { items } = await client.browserRuns.artifacts(started.id);
for (const artifact of items) console.log(artifact.kind, artifact.url);

for await (const past of client.browserRuns.iter({ status: "succeeded" })) {
  console.log(past.id, past.answer_text);
}

Run and waitCopy Anchor Link

client.browserRuns.run(params, options?) creates the run once, then reads it with browserRuns.get until its status is one of BROWSER_RUN_FINAL_STATUSES, and returns it. A run that ends failed, partial, cancelled or timed_out is returned, not thrown: read its outcome.

options is a RunBrowserRunOptions: a RequestOptions plus pollIntervalMs and timeoutMs. Each request of the wait takes the request options. pollIntervalMs is the milliseconds between reads of the run, default 2000. timeoutMs is how long to wait for the run to end, in milliseconds: the whole wait, not one request, default 3000000 (50 minutes: a run may wait queued for 15 and browse for 30).

When the time runs out it throws BrowserRunTimeoutError, whose run is the run as last read and timeoutMs the wait budget. The run keeps going: read it again later, or cancel it. A create that fails throws its own error. That run may still have started when the error is ambiguous, such as APIConnectionError after the server accepted the request: pass your own idempotency_key and call run again with the same key and body, which returns that run instead of starting a second billed one. Any other failure after the create, such as a read that fails after its retries or aborting signal, throws BrowserRunWaitError, whose runId is the run that started and cause the error that stopped the wait. That run keeps going and is billed when it ends: read it with browserRuns.get by that id, or cancel it, since calling run again starts another.

import { BrowserRunTimeoutError, BrowserRunWaitError } from "nace-sdk";

try {
  const finished = await client.browserRuns.run(
    {
      task: "What are the store's opening hours on Saturday?",
      start_url: "https://shop.example.com/contact",
      allowed_origins: ["https://shop.example.com"],
    },
    { pollIntervalMs: 3_000, timeoutMs: 600_000 },
  );
  console.log(finished.status, finished.outcome?.kind, finished.answer_text);
} catch (err) {
  if (err instanceof BrowserRunTimeoutError) {
    await client.browserRuns.cancel(err.run.id);
  } else if (err instanceof BrowserRunWaitError) {
    console.error(`run ${err.runId} is still going`, err.cause);
  } else {
    throw err;
  }
}