> ## Documentation Index > Fetch the complete documentation index at: https://browseruse-0aece648-larsen-v1-unified-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Browser Use Run > Start a browser-use run, or continue a disposable session (`session_id`). Async: accepts the task and returns a slim `RunAccepted` handle (202). Poll GET /runs/{id}/status or GET /runs/{id} for progress + result. MOCKED dispatch. A stray `workspaceId` is rejected by the request model's validator (shared agent-workspaces are browsercode-only); files still work via `attachedFileIds`. ## OpenAPI ````yaml /cloud/openapi/v1.json post /agents/browser-use/runs openapi: 3.1.0 info: title: Browser Use API v1 summary: Unified /api/v1 preview spec, non-production only version: 1.0.0 servers: - url: https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1 description: Browser Use API v1 (staging) security: [] paths: /agents/browser-use/runs: post: tags: - 'Agent: browser-use' summary: Create Browser Use Run description: >- Start a browser-use run, or continue a disposable session (`session_id`). Async: accepts the task and returns a slim `RunAccepted` handle (202). Poll GET /runs/{id}/status or GET /runs/{id} for progress + result. MOCKED dispatch. A stray `workspaceId` is rejected by the request model's validator (shared agent-workspaces are browsercode-only); files still work via `attachedFileIds`. operationId: create_browser_use_run_agents_browser_use_runs_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowserUseRunCreateRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunAccepted' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: BrowserUseRunCreateRequest: properties: task: type: string minLength: 1 title: Task description: What you want the agent to do in the browser. browser: anyOf: - $ref: '#/components/schemas/RunBrowserSettings' - type: 'null' description: Browser/proxy/screen settings for this run. sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid description: >- Continue a disposable session. 409 if that session is currently busy (browser-use does not queue). Omit to start fresh. model: anyOf: - type: string - type: 'null' title: Model description: Model to run. Omit for the server default. attachedFileIds: anyOf: - items: type: string format: uuid type: array maxItems: 20 - type: 'null' title: Attachedfileids description: Upload ids from POST /agents/browser-use/files to give this run. additionalProperties: false type: object required: - task title: BrowserUseRunCreateRequest description: >- Start a new browser-use run OR continue a disposable session. SIMPLER than browsercode: NO workspace concept (shared agent-workspaces are browsercode-only) and NO code. Sending `workspaceId` is rejected (see the validator) — the capability model is enforced, not silently ignored. Continuation via `session_id` (v2 persist-memory). browser-use 409s on a busy session (it does not queue — that's browsercode's behavior). RunAccepted: properties: id: type: string title: Id description: Run id, e.g. "run_...". agent: type: string enum: - browser-use - browsercode title: Agent description: Which agent is running it. sessionId: type: string format: uuid title: Sessionid description: The conversation this run belongs to (new or continued). workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid description: >- The run's workspace, if the agent has one (browsercode). Its files live here. status: type: string enum: - queued - running - completed - failed - stopped title: Status description: Initial state — 'queued' or 'running'. missingFileIds: items: type: string format: uuid type: array title: Missingfileids description: >- Attached upload ids that could not be confirmed in storage at creation. The run still starts. type: object required: - id - agent - sessionId - status title: RunAccepted description: >- Async run accepted. Poll GET /runs/{id}/status or GET /runs/{id} for progress + result. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError RunBrowserSettings: properties: profileId: anyOf: - type: string format: uuid - type: 'null' title: Profileid description: >- Browser profile to load: persisted cookies, local storage, and other browser state, so the run starts logged in. New-conversation only. proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' description: >- ISO country code to proxy the browser through. Defaults to US. Pass null to run without a proxy. default: us customProxy: anyOf: - $ref: '#/components/schemas/CustomProxy' - type: 'null' description: >- Custom proxy for the browser. Overrides proxyCountryCode. Requires an active subscription. Never stored or inherited by follow-up runs; pass it on each run that should use it. screenWidth: anyOf: - type: integer maximum: 6144 minimum: 320 - type: 'null' title: Screenwidth description: Custom screen width in pixels. Set together with screenHeight. screenHeight: anyOf: - type: integer maximum: 3456 minimum: 320 - type: 'null' title: Screenheight description: Custom screen height in pixels. Set together with screenWidth. record: anyOf: - type: boolean - type: 'null' title: Record description: >- Record the browser session to an mp4, retrievable via GET /browsers/{id} once the browser stops. API runs default to off. Ignored (always off) for Zero Data Retention projects. additionalProperties: false type: object title: RunBrowserSettings description: >- Browser/proxy/screen config for a run. Shared by both agents. Owned by the browser, never the run: on a follow-up in the same session, omitted fields inherit the session's prior browser and explicit values apply only when a NEW browser is provisioned (a live browser is reused as-is). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ProxyCountryCode: type: string enum: - ad - ae - af - ag - ai - al - am - an - ao - aq - ar - as - at - au - aw - az - ba - bb - bd - be - bf - bg - bh - bi - bj - bl - bm - bn - bo - bq - br - bs - bt - bv - bw - by - bz - ca - cc - cd - cf - cg - ch - ci - ck - cl - cm - co - cr - cs - cu - cv - cw - cx - cy - cz - de - dj - dk - dm - do - dz - ec - ee - eg - eh - er - es - et - fi - fj - fk - fm - fo - fr - ga - gd - ge - gf - gg - gh - gi - gl - gm - gn - gp - gq - gr - gs - gt - gu - gw - gy - hk - hm - hn - hr - ht - hu - id - ie - il - im - in - iq - ir - is - it - je - jm - jo - jp - ke - kg - kh - ki - km - kn - kp - kr - kw - ky - kz - la - lb - lc - li - lk - lr - ls - lt - lu - lv - ly - ma - mc - md - me - mf - mg - mh - mk - ml - mm - mn - mo - mp - mq - mr - ms - mt - mu - mv - mw - mx - my - mz - na - nc - ne - nf - ng - ni - nl - 'no' - np - nr - nu - nz - om - pa - pe - pf - pg - ph - pk - pl - pm - pn - pr - ps - pt - pw - py - qa - re - ro - rs - ru - rw - sa - sb - sc - sd - se - sg - sh - si - sj - sk - sl - sm - sn - so - sr - ss - st - sv - sx - sy - sz - tc - td - tf - tg - th - tj - tk - tl - tm - tn - to - tr - tt - tv - tw - tz - ua - ug - uk - us - uy - uz - va - vc - ve - vg - vi - vn - vu - wf - ws - xk - ye - yt - za - zm - zw title: ProxyCountryCode CustomProxy: properties: host: type: string maxLength: 255 minLength: 1 title: Host description: Host of the proxy. port: type: integer maximum: 65535 minimum: 1 title: Port description: Port of the proxy. username: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Username description: Username for proxy authentication. password: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Password description: Password for proxy authentication. ignoreCertErrors: type: boolean title: Ignore Certificate Errors description: >- Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies). default: false type: object required: - host - port title: CustomProxy description: Request model for creating a custom proxy. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Browser-Use-API-Key ````