> ## Documentation Index > Fetch the complete documentation index at: https://docs.browser-use.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Run ## OpenAPI ````yaml /cloud/openapi/v4.json post /runs openapi: 3.1.0 info: title: Browser Use Public API v4 summary: Browser Use agent runs API (v4) version: 4.0.0 servers: - url: https://api.browser-use.com/api/v4 description: Production server security: [] tags: - name: Runs - name: Sessions - name: Workspaces - name: Browsers - name: Profiles paths: /runs: post: tags: - Runs summary: Create Run operationId: create_run_runs_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RunCreateResponse' '400': description: Invalid request (bad session/workspace pairing or file path). '403': description: Zero Data Retention is enabled on the project (V4 unsupported). '404': description: Run, session, workspace, or profile not found. '409': description: The session already has an active run. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: RunCreateRequest: properties: task: type: string minLength: 1 title: Task model: type: string enum: - glm-5.2 - minimax-m3 - claude-opus-4.7 - claude-opus-4.8 - claude-sonnet-5 - gpt-5.5 - gpt-5.6 - gemini-3.5-flash - gemini-3.1-pro - gemini-3-flash title: Model default: minimax-m3 sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid browserSettings: anyOf: - $ref: '#/components/schemas/RunBrowserSettings' - type: 'null' attachedFileIds: anyOf: - items: type: string format: uuid type: array maxItems: 20 - type: 'null' title: Attachedfileids judge: anyOf: - $ref: '#/components/schemas/RunJudgeSettings' - type: 'null' additionalProperties: false type: object required: - task title: RunCreateRequest RunCreateResponse: properties: id: type: string format: uuid title: Id status: type: string enum: - queued - dispatching - running - completed - failed - cancelled title: Status model: type: string title: Model sessionId: type: string format: uuid title: Sessionid workspaceId: type: string format: uuid title: Workspaceid eventsUrl: type: string title: Eventsurl missingFileIds: items: type: string format: uuid type: array title: Missingfileids type: object required: - id - status - model - sessionId - workspaceId - eventsUrl title: RunCreateResponse 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: >- ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions. 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 for the browser. screenHeight: anyOf: - type: integer maximum: 3456 minimum: 320 - type: 'null' title: Screenheight description: Custom screen height in pixels for the browser. additionalProperties: false type: object title: RunBrowserSettings description: >- Browser config, owned by the browser row (never the run). Follow-ups: omitted fields inherit the session's prior browser; explicit values apply only to newly provisioned browsers (a live browser is reused as-is). Profile is the exception: a different profile → 400; an explicit value mismatching the live browser's profile (incl. null vs a profiled browser) declines reuse and provisions fresh. A live browser already matching the requested profile is reused. RunJudgeSettings: properties: context: anyOf: - type: string maxLength: 10000 - type: 'null' title: Context additionalProperties: false type: object title: RunJudgeSettings description: >- Opt-in LLM judgement of the finished run. Presence of this object turns the judge on (send {} for defaults); CP judges the run's trajectory after it goes terminal and surfaces the verdict as RunSummary.judgement (null until it lands). 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 ````