> ## 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 workflow template (create a task) > Starts a new task execution from an **official workflow template** and returns a `task_id`. Use `GET /v2/workflow/list-official-workflow-templates` to discover templates. ## OpenAPI ````yaml /openapi_2.json post /v2/workflow/run-task-by-template openapi: 3.1.0 info: title: BrowserAct API version: v2 description: > BrowserAct's API lets you run BrowserAct workflows programmatically and monitor their execution. **Core concepts (same as the Dashboard):** - **Workflow**: a reusable automation blueprint (the "design"). - **Task**: a single execution record of a workflow (the "run"). ## 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, `/v2/...`). ## Authentication Authenticate with a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` ## Requests - Send request bodies as JSON. - Set `Content-Type: application/json` for endpoints that accept a body. ## Response codes We use standard HTTP status codes: - `2xx` for successful requests - `4xx` for client-side errors (invalid parameters, missing auth, etc.) - `5xx` for server-side errors ## Errors For most error responses, the API returns a standard JSON envelope: - `code`: non-zero means an error - `msg`: human-readable error message - `traceId`: include this when contacting support ## Pagination List endpoints use **page-based pagination** with these query parameters: - `page` (starts at 1) - `limit` (1-500) Paginated responses include: `page`, `limit`, `items`, `total_pages`, `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 task status changes (e.g. running -> paused -> running). ## Task status values `created`, `running`, `finished`, `canceled`, `pausing`, `paused`, `failed`, `unknown`. ## 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 contact: name: BrowserAct Support url: https://discord.com/invite/UpnCKd7GaU servers: - url: https://api.browseract.com description: Production security: - HTTPBearer: [] tags: - name: Tasks description: | Create and manage **tasks** (executions). Typical flow: 1) Start a task (`run-task` or `run-task-by-template`) 2) Poll for status (`get-task-status`) or full details (`get-task`) 3) Retrieve outputs from the task response once finished - name: Workflows description: >- Workflows are reusable automation blueprints created in the BrowserAct Dashboard. Use these endpoints to list workflows and fetch a workflow's expected input parameters. - name: Workflow Templates description: >- Official workflow templates curated by BrowserAct. Templates are a fast way to start with common scraping/automation use cases. - name: Regions description: >- Supported proxy regions that can be used when running template-based tasks. paths: /v2/workflow/run-task-by-template: post: tags: - Tasks - Workflow Templates summary: Run an official workflow template (create a task) description: >- Starts a new task execution from an **official workflow template** and returns a `task_id`. Use `GET /v2/workflow/list-official-workflow-templates` to discover templates. operationId: runTemplateTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunWorkflowTemplateTaskRequest' examples: basic: summary: Run a template task value: proxyRegion: US workflow_template_id: tpl_123456789 input_parameters: - name: url value: https://example.com responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TaskCreatedResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ResponseData' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ResponseData' components: schemas: RunWorkflowTemplateTaskRequest: type: object description: >- Request body used to start a new task from an official workflow template. properties: proxyRegion: type: string description: Optional. Proxy region code. Defaults to `US`. example: US workflow_template_id: type: string description: The official workflow template ID to run. example: tpl_123456789 input_parameters: type: array description: Input parameters for this run. items: $ref: '#/components/schemas/InputParamItemDto' example: - name: url value: https://example.com callback_url: type: string description: Optional. See `RunWorkflowTaskRequest.callback_url`. example: https://your-server.com/webhooks/workflow-callback maxLength: 2048 status_change_callback_url: type: string description: Optional. See `RunWorkflowTaskRequest.status_change_callback_url`. example: https://your-server.com/webhooks/task-status-change-callback maxLength: 2048 required: - workflow_template_id TaskCreatedResponse: type: object description: Response returned after successfully creating a task. properties: id: type: string description: >- The unique `task_id`. Use it to poll status/results or to stop/resume the task. example: task_123456789 profile_id: type: string description: >- Returned only when `save_browser_data` is `true`. Use it to reuse browser data (e.g., cookies) in later runs. example: profile_abc123 required: - id ResponseData: type: object description: >- Standard error response envelope. Most successful responses return the resource directly (without this envelope). When an error occurs, you can use `traceId` to help BrowserAct support locate the issue. properties: code: type: integer format: int32 description: Response code. `0` means success; non-zero means failure. example: 123 msg: type: string description: Human-readable error message (present when `code` is non-zero). example: Invalid task_id data: description: Error details (shape may vary by error). type: object additionalProperties: true example: {} ts: type: integer format: int64 description: Server timestamp (milliseconds). example: 1699335116000 time: type: string format: date-time description: Server time in ISO 8601 format. example: '2023-11-07T05:31:56Z' traceId: type: string description: Error ID for tracking in logs. example: b4bb01c1b2b14f11a6a2d7c1c8b0e3a1 InputParamItemDto: type: object description: A single workflow input parameter passed when starting a task. properties: name: type: string description: >- Parameter name (must match the workflow's input parameter definition). example: keyword value: type: string description: Parameter value as a string. example: laptops securitySchemes: HTTPBearer: type: http scheme: bearer description: Send your API key in the `Authorization` header as `Bearer `. ````