> ## Documentation Index > Fetch the complete documentation index at: https://browseruse-0aece648-cursor-proxy-indicator-and-text-6cda.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > Create a session and/or dispatch a task. - Without session_id, without task: creates a new idle session (e.g. for file uploads). - Without session_id, with task: creates a new session and dispatches the task. - With session_id, with task: dispatches the task to an existing idle session. - With session_id, without task: 422 — task is required when targeting an existing session. If keep_alive is false (default), the session auto-stops when the task finishes. If keep_alive is true, the session stays idle after the task, ready for follow-ups. ## OpenAPI ````yaml cloud/openapi/v3.json post /sessions openapi: 3.1.0 info: title: Browser Use Public API v3 summary: Browser Use session-based agent API (v3) version: 3.0.0 servers: - url: https://api.browser-use.com/api/v3 description: Production server security: [] paths: /sessions: post: tags: - Sessions summary: Create Session description: >- Create a session and/or dispatch a task. - Without session_id, without task: creates a new idle session (e.g. for file uploads). - Without session_id, with task: creates a new session and dispatches the task. - With session_id, with task: dispatches the task to an existing idle session. - With session_id, without task: 422 — task is required when targeting an existing session. If keep_alive is false (default), the session auto-stops when the task finishes. If keep_alive is true, the session stays idle after the task, ready for follow-ups. operationId: create_session_sessions_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunTaskRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SessionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: RunTaskRequest: properties: task: anyOf: - type: string - type: 'null' title: Task model: $ref: '#/components/schemas/BuModel' default: bu-mini sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid keepAlive: type: boolean title: Keepalive default: false maxCostUsd: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd profileId: anyOf: - type: string format: uuid - type: 'null' title: Profileid workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' default: us outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema enableScheduledTasks: type: boolean title: Enablescheduledtasks default: false type: object title: RunTaskRequest description: >- Unified request for creating a session or dispatching a task. - Without session_id + without task: creates a new idle session (for file uploads, etc.) - Without session_id + with task: creates a new session and dispatches the task - With session_id + with task: dispatches the task to an existing idle session - With session_id + without task: 422 (task required when dispatching to existing session) SessionResponse: properties: id: type: string format: uuid title: Id status: $ref: '#/components/schemas/BuAgentSessionStatus' model: $ref: '#/components/schemas/BuModel' title: anyOf: - type: string - type: 'null' title: Title output: anyOf: - {} - type: 'null' title: Output outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema liveUrl: anyOf: - type: string - type: 'null' title: Liveurl profileId: anyOf: - type: string format: uuid - type: 'null' title: Profileid workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' maxCostUsd: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd totalInputTokens: type: integer title: Totalinputtokens default: 0 totalOutputTokens: type: integer title: Totaloutputtokens default: 0 proxyUsedMb: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Proxyusedmb default: '0' llmCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Llmcostusd default: '0' proxyCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Proxycostusd default: '0' totalCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Totalcostusd default: '0' createdAt: type: string format: date-time title: Createdat updatedAt: type: string format: date-time title: Updatedat type: object required: - id - status - model - createdAt - updatedAt title: SessionResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BuModel: type: string enum: - bu-mini - bu-max title: BuModel 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 - 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 BuAgentSessionStatus: type: string enum: - created - idle - running - stopped - timed_out - error title: BuAgentSessionStatus 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 securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Browser-Use-API-Key ````