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. 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 credit 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 failed on Drex's side (internal_error), and a run cancelled while queued. A run cancelled while running is charged its browser time so far. A run whose answer does not match your answer_schema is charged.

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 may cost at most $20 in any 24 hours. 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 of credit and no pay as you go, may have two unfinished runs and document jobs together; past that a create answers 402 with code insufficient_credit 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 are erased 48 hours after it ends. The run itself, its status, usage and cost stay as the billing record, with an empty task. Deleting your account erases them at once and cancels any run still going.