> ## Documentation Index > Fetch the complete documentation index at: https://browseruse-0aece648-codex-deterministic-rerun-docs.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 description: >- The natural-language instruction for the agent to execute (e.g. "Go to amazon.com and find the best-rated wireless mouse under $50"). Required when dispatching to an existing session. model: $ref: '#/components/schemas/BuModel' description: >- The model to use. "gemini-3-flash" is fast and cheap, "claude-sonnet-4.6" is balanced, "claude-opus-4.6" is most capable. See BuModel for details. default: claude-sonnet-4.6 sessionId: anyOf: - type: string format: uuid - type: 'null' title: Sessionid description: >- ID of an existing idle session to dispatch the task to. If omitted, a new session is created. keepAlive: type: boolean title: Keepalive description: >- If true, the session stays alive in idle state after the task completes instead of automatically stopping. This lets you dispatch follow-up tasks to the same session, preserving browser state and files. default: false maxCostUsd: anyOf: - type: number - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd description: >- Maximum total cost in USD allowed for this session. The task will be stopped if this limit is reached. If omitted, a default limit applies (capped by your available balance). 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. Create profiles via the Profiles API. workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid description: >- ID of a workspace to attach to the session. Workspaces provide persistent file storage that carries across sessions. Create workspaces via the Workspaces API. proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' description: >- Country code for the browser proxy (e.g. "US", "DE", "JP"). Set to null to disable the proxy. The proxy routes browser traffic through the specified country, useful for accessing geo-restricted content. default: us outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema description: >- A JSON Schema that the agent's final output must conform to. When set, the agent will return structured data matching this schema in the `output` field of the response. Example: {"type": "object", "properties": {"price": {"type": "number"}, "title": {"type": "string"}}}. enableScheduledTasks: type: boolean title: Enablescheduledtasks description: >- If true, the agent can create scheduled tasks that run on a recurring basis (e.g. "every Monday morning, check my inbox and summarize new emails"). Scheduled tasks are tied to your project and persist beyond the session. Note: all scheduled tasks are visible project-wide, so avoid enabling this in multi-user setups where task isolation is needed. default: false enableRecording: type: boolean title: Enablerecording description: >- If true, records a video of the browser session. The recording URLs will be available in the `recordingUrls` field of the session response after the task completes. default: false skills: type: boolean title: Skills description: >- If true, enables built-in agent skills like Google Sheets integration and file management. Set to false to restrict the agent to browser-only actions. default: true agentmail: type: boolean title: Agentmail description: >- If true, provisions a temporary email inbox (via AgentMail) for the session. The email address is available in the `agentmailEmail` field of the session response. Useful for tasks that require email verification or sign-ups. default: true cacheScript: anyOf: - type: boolean - type: 'null' title: Cachescript description: >- Controls deterministic script caching. `null` (default): auto-detected — enabled when the task contains `@{{value}}` brackets and a workspace is attached. `true`: force-enable script caching even without brackets (caches the exact task). `false`: force-disable, even if brackets are present. When active, the first call runs the full agent and saves a reusable script. Subsequent calls with the same task template execute the cached script with $0 LLM cost. Requires workspace_id when enabled. Example: "Get prices from @{{https://example.com}} for @{{electronics}}". autoHeal: type: boolean title: Autoheal description: >- When cache_script is active, controls whether a lightweight LLM validates the cached script output. If the output looks incorrect (empty, error, wrong structure), the system automatically re-triggers the full agent to generate a new version of the script. Set to false to disable validation and always return the raw script output. default: true type: object title: RunTaskRequest description: >- Create a new session, dispatch a task, or both. - **No `sessionId` + no `task`**: creates an idle session (useful for uploading files before running a task). - **No `sessionId` + `task`**: creates a new session and immediately runs the task. - **`sessionId` + `task`**: dispatches the task to an existing idle session. - **`sessionId` + no `task`**: returns 422 — a task is required when targeting an existing session. SessionResponse: properties: id: type: string format: uuid title: Id description: Unique session identifier. status: $ref: '#/components/schemas/BuAgentSessionStatus' description: >- Current session lifecycle status. Progresses through: `created` (sandbox starting) → `idle` (ready, waiting for task) → `running` (task executing) → `stopped` / `timed_out` / `error`. Poll this field to track progress. model: $ref: '#/components/schemas/BuModel' description: The model tier used for this session. title: anyOf: - type: string - type: 'null' title: Title description: >- Auto-generated short title summarizing the task. Available after the task starts running. output: anyOf: - {} - type: 'null' title: Output description: >- The agent's final output. If `outputSchema` was provided, this will be structured data conforming to that schema. Otherwise it may be a free-form string or null. Populated once the task completes, regardless of whether `isTaskSuccessful` is true or false. outputSchema: anyOf: - additionalProperties: true type: object - type: 'null' title: Outputschema description: The JSON Schema that was requested for structured output, if any. stepCount: type: integer title: Stepcount description: Number of steps the agent has executed so far. default: 0 lastStepSummary: anyOf: - type: string - type: 'null' title: Laststepsummary description: >- Human-readable summary of the most recent agent step (e.g. "Clicking the Submit button"). Useful for showing real-time progress. isTaskSuccessful: anyOf: - type: boolean - type: 'null' title: Istasksuccessful description: >- Whether the task completed successfully. `true` if the agent achieved the goal, `false` if it failed or gave up, `null` if the task is still running or no task was dispatched. liveUrl: anyOf: - type: string - type: 'null' title: Liveurl description: >- URL to view the live browser session. Available immediately on session creation — can be embedded in an iframe to show the browser in real time. recordingUrls: items: type: string type: array title: Recordingurls description: >- URLs to download session recordings. Only populated if `enableRecording` was set to true and the task has completed. default: [] profileId: anyOf: - type: string format: uuid - type: 'null' title: Profileid description: ID of the browser profile loaded in this session, if any. workspaceId: anyOf: - type: string format: uuid - type: 'null' title: Workspaceid description: ID of the workspace attached to this session, if any. proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' description: >- Country code of the proxy used for this session, or null if no proxy. maxCostUsd: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Maxcostusd description: Maximum cost limit in USD set for this session. totalInputTokens: type: integer title: Totalinputtokens description: Total LLM input tokens consumed by this session. default: 0 totalOutputTokens: type: integer title: Totaloutputtokens description: Total LLM output tokens consumed by this session. default: 0 proxyUsedMb: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Proxyusedmb description: Proxy bandwidth used in megabytes. default: '0' llmCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Llmcostusd description: Cost of LLM usage in USD. default: '0' proxyCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Proxycostusd description: Cost of proxy bandwidth in USD. default: '0' browserCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Browsercostusd description: Cost of browser compute time in USD. default: '0' totalCostUsd: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Totalcostusd description: Total session cost in USD (LLM + proxy + browser). default: '0' screenshotUrl: anyOf: - type: string - type: 'null' title: Screenshoturl description: >- URL of the latest browser screenshot. This is a presigned URL that expires after 5 minutes. A new URL is generated each time you fetch the session. agentmailEmail: anyOf: - type: string - type: 'null' title: Agentmailemail description: >- Temporary email address provisioned for this session (via AgentMail). Only present if `agentmail` was enabled. createdAt: type: string format: date-time title: Createdat description: When the session was created. updatedAt: type: string format: date-time title: Updatedat description: When the session was last updated. type: object required: - id - status - model - createdAt - updatedAt title: SessionResponse description: >- Represents a session and its current state. Poll this endpoint to track task progress. The `status` field indicates the session lifecycle stage, and `output` contains the agent's structured result once the task completes. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BuModel: type: string enum: - bu-mini - bu-max - bu-ultra - gemini-3-flash - claude-sonnet-4.6 - claude-opus-4.6 title: BuModel description: >- The model to use for the agent. Each model has different capabilities and pricing. - `bu-mini` / `gemini-3-flash`: Gemini 3 Flash — fast and cost-effective. Best for simple, well-defined tasks like form filling or data extraction. - `bu-max` / `claude-sonnet-4.6`: Claude Sonnet 4.6 — balanced performance. Best for multi-step workflows that require reasoning and decision-making. - `bu-ultra` / `claude-opus-4.6`: Claude Opus 4.6 — most capable. Best for complex tasks that require advanced reasoning, long-horizon planning, or handling ambiguous instructions. 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 description: >- Session lifecycle status. Progresses through: created → idle → running → idle → ... → stopped / timed_out / error. - `created`: Sandbox is starting up. The session is not yet ready to accept tasks. - `idle`: Sandbox is healthy and waiting for a task. You can dispatch a task or upload files. - `running`: A task is currently being executed by the agent. - `stopped`: Session was stopped — either explicitly via the stop endpoint, or automatically after task completion (when `keepAlive` is false). - `timed_out`: Session was cleaned up due to inactivity timeout. - `error`: Sandbox failed to start or encountered an unrecoverable error. 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 ````