> ## Documentation Index > Fetch the complete documentation index at: https://docs.browseract.com/llms.txt > Use this file to discover all available pages before exploring further. # Run an official bot template (create a task) > Starts a new task execution from an official Bot template and returns a `task_id`. Use `GET /v3/bots/templates` to discover templates and `GET /v3/bots/templates/{template_id}` to inspect the template `input_schema`. Provide an `input` object that conforms to the schema. Optionally select a `proxy_region` returned by `GET /v3/bots/regions`, and configure completion or status-change callbacks. Template runs do not support the MCP execution context. ## OpenAPI ````yaml /openapi_3.json post /v3/bots/templates/{template_id}/runs openapi: 3.0.3 info: title: BrowserAct API description: > BrowserAct's API lets you list and run BrowserAct bots programmatically and monitor their execution. **Core concepts (same as the Dashboard):** - **Bot**: a published Bot automation that can be run through the API. - **Task**: a single bot execution record (the "run"). The public `bot_type=agent` value represents **SkillFlow**, not the legacy Agent app type. ## Base URL All requests use the following base URL: ``` https://api.browseract.com ``` ## API versioning The API is versioned in the URL path (for example, `/v3/bots/...`). ## Authentication Authenticate with a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` API keys are scoped to a company and channel. Do not send internal session headers such as `x-session-company-id` or `x-session-api-channel`; BrowserAct injects them after authentication. ## Requests - Send request bodies as JSON. - Set `Content-Type: application/json` for endpoints that accept a body. - Run inputs use an `input` object that must conform to the bot or template `input_schema`. ## Response codes - `200` for successful queries, creates, cancels, and resumes - `400` for invalid parameters, business validation failures, or resources not visible to the current API key - `500` for server-side errors Successful responses return the business object directly without a data wrapper. Error responses use `code`, `msg`, `data`, `ts`, `time`, and `traceId`. ## Pagination List endpoints use **page-based pagination** with these query parameters: - `page` (starts at 1) - `limit` (maximum depends on the endpoint) Paginated responses include `page`, `limit`, `items`, `total_pages`, and `total_count`. ## Webhooks (optional) When creating a task, you can provide: - `callback_url`: called when a task **finishes**, **fails**, or is **canceled**. - `status_change_callback_url`: called whenever the public task status changes. Both callbacks receive the complete `BotRunDetailResponse` directly, without an additional `data` wrapper. Callback URLs cannot resolve to private or local addresses. ## Task status values `created`, `running`, `pausing`, `paused`, `finished`, `canceled`, `failed`. ## Common error codes - `99001`: Request parameter error - `99002`: No operation permission - `10013`: Proxy region does not exist - `10020`: Bot is not published - `10021`: SkillFlow LLM configuration is incomplete - `10111`: Bot does not exist or is not visible - `10112`: Task does not exist - `10121`: Task has already completed - `10127`: Only a paused task can be resumed - `10142`: Required Bot input is missing - `10143`: Required SkillFlow input is missing - `10176`: Bot template does not exist - `10879`: SkillFlow runs do not support resume ## Rate limits To protect platform stability, rate limits may apply. If you hit a limit, reduce request frequency and retry with backoff. ## Need help? Join our Discord community: https://discord.com/invite/UpnCKd7GaU version: v3 contact: name: BrowserAct Support url: https://discord.com/invite/UpnCKd7GaU servers: - url: https://api.browseract.com description: API host security: - HTTPBearer: [] tags: - name: Tasks description: >- Create and manage bot execution tasks. Start a task, poll its status or full details, and retrieve outputs after it finishes. - name: Bots description: >- Bots are published Bot automations. Use these endpoints to list runnable bots and inspect their input and output schemas. - name: Bot Templates description: >- Official Bot templates curated by BrowserAct. Templates provide a fast way to start common scraping and automation use cases. - name: Regions description: >- Supported proxy regions that can be used when running an official Bot template. paths: /v3/bots/templates/{template_id}/runs: post: tags: - Tasks - Bot Templates summary: Run an official bot template (create a task) description: >- Starts a new task execution from an official Bot template and returns a `task_id`. Use `GET /v3/bots/templates` to discover templates and `GET /v3/bots/templates/{template_id}` to inspect the template `input_schema`. Provide an `input` object that conforms to the schema. Optionally select a `proxy_region` returned by `GET /v3/bots/regions`, and configure completion or status-change callbacks. Template runs do not support the MCP execution context. operationId: createTemplateRun parameters: - name: template_id in: path required: true description: Public Bot template identifier. schema: type: string example: '3001' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BotTemplateRunCreateRequest' examples: basic: summary: Start a Bot template task value: input: url: https://example.com withProxyAndWebhooks: summary: Use a proxy region and receive webhook callbacks value: input: url: https://example.com proxy_region: US callback_url: https://your-server.com/webhooks/bot-template-callback status_change_callback_url: https://your-server.com/webhooks/task-status-change-callback responses: '200': description: Template run created. content: application/json: schema: $ref: '#/components/schemas/BotRunCreatedResponse' example: task_id: '93002' status: created '400': description: Bot template not found. Returns error code 10176. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' callbacks: runCompleted: '{$request.body#/callback_url}': post: summary: Receive the terminal V3 template run detail requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BotRunDetailResponse' responses: '200': description: Callback accepted. method: post type: path path: '{$request.body#/callback_url}' runStatusChanged: '{$request.body#/status_change_callback_url}': post: summary: >- Receive the current V3 template run detail after a public status change requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BotRunDetailResponse' responses: '200': description: Callback accepted. method: post type: path path: '{$request.body#/status_change_callback_url}' components: schemas: BotTemplateRunCreateRequest: type: object properties: input: type: object additionalProperties: true description: >- Run input object. Its shape must conform to the template input_schema; use an empty object when no inputs are required. proxy_region: type: string description: Optional proxy region code returned by the regions endpoint. example: US callback_url: type: string format: uri maxLength: 2048 description: >- Optional. HTTP/HTTPS URL to receive a POST notification when the task **finishes**, **fails**, or is **canceled**. Maximum length: 2048 characters. Must be publicly reachable (no private/local addresses). status_change_callback_url: type: string format: uri maxLength: 2048 description: >- Optional. HTTP/HTTPS URL to receive a POST notification whenever the task status changes (e.g., running, paused, finished, canceled, failed). Maximum length: 2048 characters. Must be publicly reachable (no private/local addresses). required: - input BotRunCreatedResponse: type: object properties: task_id: type: string description: Task ID status: $ref: '#/components/schemas/BotRunStatus' required: - task_id - status ErrorResponse: type: object properties: code: type: integer description: Response code. `0` means success; non-zero means failure. msg: type: string description: Human-readable error message (present when `code` is non-zero). data: type: object nullable: true description: Error details (shape may vary by error). ts: type: integer format: int64 description: Server timestamp (milliseconds). time: type: string description: Server time. traceId: type: string description: Error ID for tracking in logs. required: - code - msg - ts - time - traceId example: code: 123 msg: Invalid task_id data: null ts: 1786634400000 time: '2026-08-13 18:00:00' traceId: a1b2c3d4e5f6 BotRunDetailResponse: type: object properties: task_id: type: string description: Task ID log_detail_url: type: string format: uri description: URL to detailed execution logs for this task. bot_id: type: string description: Public bot identifier used by a normal Bot run. bot_type: $ref: '#/components/schemas/BotType' bot_name: type: string description: Bot display name when available for a normal Bot run. status: $ref: '#/components/schemas/BotRunStatus' created_at: type: string format: date-time description: Task creation time finished_at: type: string format: date-time description: Task finish time (if ended) input: type: object additionalProperties: true description: Input object accepted for this run. task_failure_info: $ref: '#/components/schemas/BotRunFailureInfoResponse' output: nullable: true description: Present only when the task has ended. output_files: type: object additionalProperties: $ref: '#/components/schemas/BotRunOutputFileResponse' description: >- Business result files keyed by format, for example json, md, csv or xml. download_files: type: array items: $ref: '#/components/schemas/BotRunDownloadFileResponse' description: Files generated by the task (if any). files_expires_at: type: integer format: int64 description: Expiration timestamp for download files. steps: type: array items: $ref: '#/components/schemas/TaskStepDto' description: Steps executed within the task. live_url_info: $ref: '#/components/schemas/BotRunLiveUrlInfoResponse' description: Present only when the task is `running`. credit: type: integer format: int64 description: Credits consumed by this task. required: - task_id - log_detail_url - bot_type - status - created_at - input BotRunStatus: type: string enum: - created - running - finished - canceled - pausing - paused - failed description: Public lifecycle status of a bot run. BotType: type: string enum: - workflow - agent description: >- Public bot type. agent represents SkillFlow, not the legacy Agent app type. BotRunFailureInfoResponse: type: object properties: code: type: integer description: Error code message: type: string description: Error message required: - code - message BotRunOutputFileResponse: type: object properties: file_name: type: string description: Business result file name. file_size: type: integer format: int64 description: Business result file size in bytes when available. download_url: type: string description: Temporary URL for downloading the business result file. required: - file_name - download_url BotRunDownloadFileResponse: type: object properties: guid: type: string description: File unique identifier file_name: type: string description: Display file name. file_size: type: integer format: int64 description: File size in bytes. status: type: string description: File status (value may vary) progress: type: integer description: Download progress (0-100) download_url: type: string description: Temporary download URL, available after upload completes. download_start_time: type: integer format: int64 description: Download start time in epoch milliseconds. download_completed_time: type: integer format: int64 description: Download completion time in epoch milliseconds. expires_at: type: integer format: int64 description: Download expiration time in epoch milliseconds. error_message: type: string description: >- Failure or cancellation message when file transfer does not complete. create_time: type: integer format: int64 description: File record creation time in epoch milliseconds. TaskStepDto: type: object properties: id: type: string description: Step ID step: type: integer description: Step sequence number evaluation_previous_goal: type: string description: Evaluation result of the previous step step_goal: type: string description: Goal of the current step screenshots_url: type: string description: Screenshot URL captured during this step status: $ref: '#/components/schemas/TaskStepStatusEnum' required: - id - step - evaluation_previous_goal - step_goal - screenshots_url - status BotRunLiveUrlInfoResponse: type: object properties: live_url: type: string description: Live view URL. Can be embedded in an `