> ## 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 Task > Create and start a new task. You can either: 1. Start a new task without a sessionId (auto-creates a session with US proxy by default). Note: Tasks without a sessionId are one-off tasks that automatically close the session upon completion (keep_alive=false). Use sessionSettings to configure the auto-created session (e.g. proxyCountryCode, profileId, screen dimensions). 2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration) Note: Without sessionSettings, a US proxy is enabled by default. Providing sessionSettings overrides defaults — proxy is only enabled if proxyCountryCode is set. For full control over session configuration (e.g. keep_alive), create a session first via POST /sessions with your desired settings, then pass that sessionId when creating tasks. ## OpenAPI ````yaml cloud/openapi/v2.json post /tasks openapi: 3.1.0 info: title: Browser Use Public API v2 summary: Browser Use API for running web agents (v2) version: 2.0.0 servers: - url: https://api.browser-use.com/api/v2 description: Production server security: [] paths: /tasks: post: tags: - Tasks summary: Create Task description: >- Create and start a new task. You can either: 1. Start a new task without a sessionId (auto-creates a session with US proxy by default). Note: Tasks without a sessionId are one-off tasks that automatically close the session upon completion (keep_alive=false). Use sessionSettings to configure the auto-created session (e.g. proxyCountryCode, profileId, screen dimensions). 2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration) Note: Without sessionSettings, a US proxy is enabled by default. Providing sessionSettings overrides defaults — proxy is only enabled if proxyCountryCode is set. For full control over session configuration (e.g. keep_alive), create a session first via POST /sessions with your desired settings, then pass that sessionId when creating tasks. operationId: create_task_tasks_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTaskRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskCreatedResponse' '400': description: Session is stopped or has running task content: application/json: schema: anyOf: - $ref: '#/components/schemas/SessionStoppedError' - $ref: '#/components/schemas/SessionHasRunningTaskError' title: Response 400 Create Task Tasks Post '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/SessionNotFoundError' '422': description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '429': description: Too many concurrent active sessions content: application/json: schema: $ref: '#/components/schemas/TooManyConcurrentActiveSessionsError' security: - APIKeyHeader: [] components: schemas: CreateTaskRequest: properties: task: type: string maxLength: 50000 minLength: 1 title: Task description: The task prompt/instruction for the agent. llm: $ref: '#/components/schemas/SupportedLLMs' title: LLM description: The LLM model to use for the agent. default: browser-use-2.0 startUrl: anyOf: - type: string - type: 'null' title: Start URL description: The URL to start the task from. maxSteps: type: integer maximum: 10000 minimum: 1 title: Max Steps description: Maximum number of steps the agent can take before stopping. default: 100 structuredOutput: anyOf: - type: string - type: 'null' title: Structured Output description: The stringified JSON schema for the structured output. sessionId: anyOf: - type: string format: uuid - type: 'null' title: Session ID description: The ID of the session where the task will run. metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: The metadata for the task. Up to 10 key-value pairs. secrets: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Secrets description: >- The secrets for the task. Allowed domains are not required for secrets to be injected, but are recommended. allowedDomains: anyOf: - items: type: string type: array - type: 'null' title: Allowed Domains description: The allowed domains for the task. opVaultId: anyOf: - type: string - type: 'null' title: 1Password Vault ID description: >- The ID of the 1Password vault to use for the task. This is used to inject secrets into the task. sessionSettings: anyOf: - $ref: '#/components/schemas/SessionSettings' - type: 'null' title: Session Settings description: >- Session configuration for auto-created sessions. Only applies when session_id is not provided. Ignored when using an existing session. highlightElements: type: boolean title: Highlight Elements description: Tells the agent to highlight interactive elements on the page. default: false flashMode: type: boolean title: Flash Mode description: Whether agent flash mode is enabled. default: false thinking: type: boolean title: Thinking description: Whether agent thinking mode is enabled. default: false vision: anyOf: - type: boolean - type: string const: auto title: Vision description: >- Whether agent vision capabilities are enabled. Set to 'auto' to let the agent decide based on the model capabilities. default: true systemPromptExtension: type: string maxLength: 2000 title: System Prompt Extension description: Optional extension to the agent system prompt. default: '' judge: type: boolean title: Judge description: Enable judge mode to evaluate task completion against ground truth. default: false judgeGroundTruth: anyOf: - type: string maxLength: 10000 - type: 'null' title: Judge Ground Truth description: Expected answer for judge evaluation. judgeLlm: anyOf: - $ref: '#/components/schemas/SupportedLLMs' - type: 'null' title: Judge LLM description: >- The LLM model to use for judging. If not provided, uses the default judge LLM. skillIds: anyOf: - items: type: string type: array - type: 'null' title: Skill IDs description: >- List of skill IDs to enable for this task. Use ['*'] to enable all available skills for the project. type: object required: - task title: CreateTaskRequest description: Request model for creating a task TaskCreatedResponse: properties: id: type: string format: uuid title: ID description: Unique identifier for the created task sessionId: type: string format: uuid title: Session ID description: Session ID where the task was created type: object required: - id - sessionId title: TaskCreatedResponse description: Response model for creating a task SessionStoppedError: properties: detail: type: string title: Detail default: >- Browser session is stopped. Please start a new session and try again. type: object title: SessionStoppedError description: Error response when trying to use a stopped session SessionHasRunningTaskError: properties: detail: type: string title: Detail default: >- Agent session already has a running task. Please wait for it to finish or stop it manually. type: object title: SessionHasRunningTaskError description: Error response when session already has a running task SessionNotFoundError: properties: detail: type: string title: Detail default: Session not found type: object title: SessionNotFoundError description: Error response when a session is not found 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 TooManyConcurrentActiveSessionsError: properties: detail: type: string title: Detail default: >- Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan. type: object title: TooManyConcurrentActiveSessionsError description: Error response when user has too many concurrent active sessions SupportedLLMs: type: string enum: - browser-use-llm - browser-use-2.0 - gpt-4.1 - gpt-4.1-mini - o4-mini - o3 - gemini-2.5-flash - gemini-2.5-pro - gemini-3-pro-preview - gemini-3-flash-preview - gemini-flash-latest - gemini-flash-lite-latest - claude-sonnet-4-20250514 - claude-sonnet-4-5-20250929 - claude-sonnet-4-6 - claude-opus-4-5-20251101 - gpt-4o - gpt-4o-mini - llama-4-maverick-17b-128e-instruct - claude-3-7-sonnet-20250219 title: SupportedLLMs SessionSettings: properties: profileId: anyOf: - type: string format: uuid - type: 'null' title: Profile ID description: >- Browser profile ID for persistent browser state (cookies, local storage, etc.). proxyCountryCode: anyOf: - $ref: '#/components/schemas/ProxyCountryCode' - type: 'null' title: Proxy Country Code description: >- Proxy country code for geo-targeted browsing. Defaults to US. Set to null to disable proxy. default: us browserScreenWidth: anyOf: - type: integer maximum: 6144 minimum: 320 - type: 'null' title: Browser Screen Width description: Custom screen width in pixels for the browser. browserScreenHeight: anyOf: - type: integer maximum: 3456 minimum: 320 - type: 'null' title: Browser Screen Height description: Custom screen height in pixels for the browser. enableRecording: type: boolean title: Enable Recording description: If True, enables session recording. Defaults to False. default: false type: object title: SessionSettings description: |- Session configuration for auto-created sessions. These settings only apply when no session_id is provided. 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 securitySchemes: APIKeyHeader: type: apiKey in: header name: X-Browser-Use-API-Key ````