Browser runs

A browser run is a task for an agent that browses the web for you: "find the cheapest 1 TB SSD on this shop and return its name and price". You send the task, the page to start on and the sites it may visit. Drex runs the agent in a cloud browser of its own, with Drex Max choosing each move, and returns the answer, the steps it took and the evidence it read. A run takes from a few seconds to a few minutes, so you start it and then poll it.

Start a runCopy Anchor Link

curl https://console.nace.ai/v1/browser/runs \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Find the cheapest SSD of at least 1 TB and return its name and price",
    "start_url": "https://shop.example.com/",
    "allowed_origins": ["https://shop.example.com"],
    "answer_schema": {
      "type": "object",
      "properties": { "name": { "type": "string" }, "price": { "type": "number" } },
      "required": ["name", "price"]
    },
    "limits": { "max_cost_usd": 0.05, "max_seconds": 300 }
  }'

The answer is 202 with the queued run:

{ "id": "brun_4c6f395e31ca4486ae3e394982c5aeea", "object": "browser_run", "status": "queued", "created_at": "2026-10-20T11:37:34.000Z" }

Follow a runCopy Anchor Link

Poll GET /v1/browser/runs/{id} every few seconds until status is final:

• queued, then running;
• succeeded: the agent completed the task, or found that what it was asked for does not exist (outcome.kind completed or not_found);
• partial: it stopped at a login, a captcha, an action it may not take, or a limit (blocked_login, blocked_captcha, risky_action_denied, limit_reached);
• failed: the site failed, the answer did not match answer_schema (answer_invalid), or the run failed on Drex's side (internal_error);
• cancelled or timed_out.

A finished run has answer (with an answer_schema), answer_text, final_url, outcome with the evidence the agent read, steps, and usage with what it was charged in cost_usd. A failed run returns none of what it found: its answer, answer_text, final_url, evidence, steps and artifacts are empty, and outcome.reason says why. GET /v1/browser/runs lists your runs, newest first (limit, status, cursor), and GET /v1/browser/runs/{id}/artifacts lists its screenshots. POST /v1/browser/runs/{id}/cancel stops a queued or running run.

The Python and TypeScript SDKs, the nace CLI and the nace-mcp server start a run and wait for it in one call. See Python, TypeScript, CLI and MCP.

What a run may browseCopy Anchor Link

A run browses public sites without signing in, and only the origins you allow. These are refused with 422 and code origin_blocked, whatever you allow:

• hosts that are not public: IP addresses, localhost, .local, .internal and the like;
• banks, payment, brokerage and crypto-exchange sites;
• the sign-in pages of large identity providers (Google, Microsoft, Apple, Yahoo);
• large social networks and messengers;
• government and military sites (.gov, .mil, gov.uk, gouv.fr, go.jp and the like).

PriceCopy Anchor Link

A run is billed once, when it ends, from the same balance as every other call:

A short task (about 35 seconds) costs about $0.006; a typical multi-page task (about 75 seconds, 50,000 Drex Max tokens) about $0.018. A run never costs more than its limits.max_cost_usd. usage on the run shows each count and the total.

Not charged: a run that never started, timed out, or ended failed (site_error, answer_invalid or internal_error), or was cancelled before completion. Failed and cancelled runs still count toward the daily browser resource limit, using their measured work, without debiting your balance.

LimitsCopy Anchor Link

• At most 20 queued or running runs per account; more answer 429 with code rate_limited. Two of them browse at once and the rest wait queued; a run still queued 15 minutes after it was created ends timed_out, uncharged.
• An account's runs have a $20 resource limit in any 24 hours, including the measured work of failed and cancelled runs. A run that could go past it answers 429 with code daily_spend_limit. Contact support to raise it.
• A free account, or one with less than $5 in available funds and no pay as you go, may have 50 unfinished runs and document jobs together; past that a create answers 429 with code job_limit_reached until one ends.
• Accounts with zero data retention cannot create runs: a run keeps its task and answer.

Data retentionCopy Anchor Link

A run's task, URLs, schema, metadata, answer, steps and evidence stay until you delete your account. Deleting your account erases this content and cancels any run still going. Status, usage and cost stay as the billing record.