> ## 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 a workflow (create a task) > Starts a new task execution for a workflow and returns a `task_id`. ### How it works 1) Choose a workflow in the Dashboard and copy its `workflow_id` 2) Provide any `input_parameters` required by the workflow 3) Optionally enable `save_browser_data` to receive a `profile_id` that can be reused later ### Webhooks You can provide `callback_url` and/or `status_change_callback_url` to receive POST notifications. ## OpenAPI ````yaml /openapi_2.json post /v2/workflow/run-task 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: post: tags: - Tasks summary: Run a workflow (create a task) description: >- Starts a new task execution for a workflow and returns a `task_id`. ### How it works 1) Choose a workflow in the Dashboard and copy its `workflow_id` 2) Provide any `input_parameters` required by the workflow 3) Optionally enable `save_browser_data` to receive a `profile_id` that can be reused later ### Webhooks You can provide `callback_url` and/or `status_change_callback_url` to receive POST notifications. operationId: runTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunWorkflowTaskRequest' examples: basic: summary: Start a workflow task value: workflow_id: wf_123456789 input_parameters: - name: keyword value: laptops withProfileAndWebhooks: summary: Save browser data and receive webhook callbacks value: workflow_id: wf_123456789 input_parameters: - name: keyword value: laptops save_browser_data: true callback_url: https://your-server.com/webhooks/workflow-callback status_change_callback_url: https://your-server.com/webhooks/task-status-change-callback responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TaskCreatedResponse' examples: created: value: id: task_123456789 profile_id: profile_abc123 '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: RunWorkflowTaskRequest: type: object description: Request body used to start a new task from a workflow. properties: workflow_id: type: string minLength: 1 description: The workflow ID to run. example: wf_123456789 input_parameters: type: array description: Input parameters for this run. items: $ref: '#/components/schemas/InputParamItemDto' example: - name: keyword value: laptops save_browser_data: type: boolean description: >- If `true`, the response will include a `profile_id`. You can reuse that `profile_id` in later runs to reuse browser data (e.g., cookies). example: true profile_id: type: string description: >- Reuse browser data from a previous run (e.g., cookies) by providing a `profile_id`. example: profile_abc123 open_incognito_mode: type: boolean deprecated: true description: Deprecated. No longer required. example: false callback_url: type: string 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). example: https://your-server.com/webhooks/workflow-callback maxLength: 2048 status_change_callback_url: type: string 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). example: https://your-server.com/webhooks/task-status-change-callback maxLength: 2048 required: - workflow_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 `. ````