> ## 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 Browsercode Run > Start a new browsercode conversation, or continue one (`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; real v4 dispatch is a follow-up. The continuation-config 400 rule below is REAL (validation). ## OpenAPI ````yaml /cloud/openapi/v1.json post /agents/browsercode/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/browsercode/runs: post: tags: - 'Agent: browsercode' summary: Create Browsercode Run description: >- Start a new browsercode conversation, or continue one (`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; real v4 dispatch is a follow-up. The continuation-config 400 rule below is REAL (validation). operationId: create_browsercode_run_agents_browsercode_runs_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowsercodeRunCreateRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunAccepted' '400': content: application/json: schema: $ref: '#/components/schemas/ContinuationConfigError' description: Bad Request '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: BrowsercodeRunCreateRequest: properties: task: type: string minLength: 1 title: Task description: What you want the agent to do. model: anyOf: - type: string - type: 'null' title: Model description: >- Model to run. New-conversation only — inherited on a continuation. Omit for the server default. sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid description: >- Continue this conversation. Files and config carry over; send a MINIMAL body (task + attachedFileIds). Omit to start a new conversation. workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid description: >- ADVANCED + new-conversation only. Run in an explicit workspace to share files across sessions. Omit on the normal path. browser: anyOf: - $ref: '#/components/schemas/RunBrowserSettings' - type: 'null' description: >- Browser/proxy/screen settings. New-conversation only (inherited on a follow-up). attachedFileIds: anyOf: - items: type: string format: uuid type: array maxItems: 20 - type: 'null' title: Attachedfileids description: >- Upload ids (from POST /agents/browsercode/files) to give THIS run. Allowed on both new and continuation runs. maxCostUsd: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd description: USD cap for this run. New-conversation only; null → server default. judge: anyOf: - $ref: '#/components/schemas/BrowsercodeJudgeSettings' - type: 'null' description: Opt-in post-run LLM judge. New-conversation only. additionalProperties: false type: object required: - task title: BrowsercodeRunCreateRequest description: >- Start a new browsercode conversation OR continue an existing one. ONE door. Omit `session_id` to start a new conversation (full config body). Pass `session_id` to continue a thread (MINIMAL body — config is inherited). Continuation never 409s on a busy session: the turn comes back `queued` and starts automatically when the current run finishes. CONTINUATION RULE (enforced): passing `session_id` together with ANY config field (model / workspaceId / browser / judge / maxCostUsd) → 400. Config is inherited on a follow-up; start a new session to change it. 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. ContinuationConfigError: properties: detail: type: string title: Detail default: >- Config is inherited on a continuation. Start a new session to change model/workspace/browser. type: object title: ContinuationConfigError description: Config field sent on a continuation (session_id present). 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). BrowsercodeJudgeSettings: properties: context: anyOf: - type: string maxLength: 10000 - type: 'null' title: Context description: >- Extra context for the judge: ground truth, evaluation criteria, expected outcomes. Takes precedence over the judge's own criteria. additionalProperties: false type: object title: BrowsercodeJudgeSettings description: |- Opt-in LLM judgement of the finished run. Presence turns the judge on (send {} for defaults); the judge's LLM call is billed to the run. 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 ````