---
title: "Start a browser run"
method: POST
path: "/v1/browser/runs"
tags: ["Browser"]
---

# Start a browser run

`POST /v1/browser/runs`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/browser/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/browser/runs/post.ts> (a function with typed inputs; its response is checked against the schema)

Admits a task for a cloud browser agent and answers at once with the queued run; poll `GET /v1/browser/runs/{id}` for its result. The run browses only `allowed_origins`, in a sandbox of its own, and is billed once when it ends: its Drex Max and LLM tokens and its browser seconds at the published prices, never more than `limits.max_cost_usd`. Runs that never start, time out, or end `failed` are not charged; a run cancelled before completion is also free.

- Banking, payment, identity, large social and government sites answer `422` with code `origin_blocked`, as do hosts that are not public.
- An account's runs have a $20 resource limit in any 24 hours unless support raised it; failed and cancelled runs count their measured work without a customer charge. Past that, `429` with code `daily_spend_limit`.
- A run's task, URLs, answer and steps stay until you delete your account.
- Accounts with zero retention cannot create runs (`422`, code `zero_retention_unsupported`).

## Headers

- `Idempotency-Key` string

## Request body

- BrowserRunCreateRequest
  - `task` string, required: What the agent should do, in plain language.
  - `start_url` string, uri, required: An `http` or `https` page on a public host, on the default port, whose origin is in `allowed_origins`.
  - `allowed_origins` string[], required: The origins (`https://shop.example.com`, no path) the run may load. Everything else is blocked.
  - `answer_schema` object, nullable: A JSON Schema (at most 16 KB, without `pattern` or `patternProperties`) the answer must match. With one, `answer` holds the structured answer; a completed answer that does not match fails the run as `answer_invalid`, uncharged.
  - `risky_actions` 'deny': The agent never submits payments, sends messages, or makes other irreversible changes.
  - `limits` BrowserRunLimits
    - `max_cost_usd` number: The most the run may be charged, in US dollars.
    - `max_seconds` integer: How long the run may browse.
    - `max_llm_calls` integer: How many planning and reading calls the agent may make.
  - `model` 'default'
  - `artifacts` BrowserRunArtifactOptions
    - `screenshots` boolean
    - `har` boolean
  - `idempotency_key` string: A retried key returns the same run; the same key with a different body answers `409`.
  - `metadata` object: Up to 20 key-value pairs of your own, as an object of strings (keys up to 64 characters, values up to 500), returned with the run.

## Response `202`

The run, queued.

- BrowserRunRef
  - `id` string, required
  - `object` 'browser_run', required
  - `status` 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled' | 'timed_out', required: `queued` → `running` → one of `succeeded`, `partial`, `failed`, `cancelled`, `timed_out`.
  - `created_at` string, date-time

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `402`: Insufficient available funds (`insufficient_credit`) or an unpaid invoice (`payment_required`).
- `409`: The idempotency key was used before with a different body (`conflict_error`, code `idempotency_conflict`).
- `413`: The body is over 64 KB (`invalid_request_error`, code `payload_too_large`).
- `422`: The body is invalid (`invalid_request_error`, code `invalid_request`), names a site runs may not browse (code `origin_blocked`), or the account has zero retention (code `zero_retention_unsupported`).
- `429`: The shared limit of 50 unfinished document jobs and browser runs for free or low-balance prepaid accounts (code `job_limit_reached`, wait for one to finish); more than 20 queued or running runs on the account, or the per-minute request limit (code `rate_limited`); or the account's browser runs reached their daily resource limit, which counts failed and cancelled runs' measured work although they are not charged (code `daily_spend_limit`, `Retry-After` an hour).
- `500`: Something failed on Drex's side (`internal_error`). Retry.
- `503`: Browser runs are not priced on this deployment (`service_unavailable`, code `browser_billing_not_configured`).

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)