> ## 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. # List tasks > Returns a paginated list of tasks (workflow executions). ### Filtering - Use `status` to filter by task status. - Use `workflow_id` to only list tasks created from a specific workflow. - Use `workflow_name` to search by workflow name (case-insensitive partial match). - Use `created_at_from` / `created_at_to` to filter by task creation time (ISO 8601, UTC). ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. ## OpenAPI ````yaml /openapi_2.json get /v2/workflow/list-tasks 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/list-tasks: get: tags: - Tasks summary: List tasks description: >- Returns a paginated list of tasks (workflow executions). ### Filtering - Use `status` to filter by task status. - Use `workflow_id` to only list tasks created from a specific workflow. - Use `workflow_name` to search by workflow name (case-insensitive partial match). - Use `created_at_from` / `created_at_to` to filter by task creation time (ISO 8601, UTC). ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. operationId: pageTasks parameters: - name: status in: query description: Filter tasks by status. required: false schema: $ref: '#/components/schemas/TaskStatus' example: running - name: workflow_id in: query description: Only return tasks created from this workflow ID. required: false schema: type: string example: wf_123456789 - name: workflow_name in: query description: >- Filter by workflow name using a case-insensitive partial match (contains). required: false schema: type: string example: price monitor - name: created_at_from in: query description: >- Lower bound of task creation time (inclusive). ISO 8601 format, e.g. `2024-01-01T00:00:00Z`. required: false schema: type: string format: date-time example: '2024-01-01T00:00:00Z' - name: created_at_to in: query description: >- Upper bound of task creation time (inclusive). ISO 8601 format, e.g. `2024-12-31T23:59:59Z`. required: false schema: type: string format: date-time example: '2024-12-31T23:59:59Z' - name: page in: query description: Page number to retrieve (starts at 1). required: false schema: type: integer minimum: 1 example: 1 - name: limit in: query description: Number of tasks per page (max 500). required: false schema: type: integer minimum: 1 maximum: 500 example: 50 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PageRespWorkflowTaskSimpleResponse' '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: TaskStatus: type: string description: |- Current task status. - `created`: Task is created but not yet running - `running`: Task is currently executing - `finished`: Task completed successfully - `canceled`: Task was canceled (e.g., via Stop Task) - `pausing`: Task is transitioning into paused state - `paused`: Task is paused and can be resumed - `failed`: Task ended with an error - `unknown`: Unknown or unsupported status enum: - created - running - finished - canceled - pausing - paused - failed - unknown PageRespWorkflowTaskSimpleResponse: type: object description: Paginated response containing tasks and metadata. properties: page: type: integer format: int32 description: Current page number. limit: type: integer format: int32 description: Number of items per page. items: type: array description: Tasks for the current page. items: $ref: '#/components/schemas/WorkflowTaskSimpleResponse' total_pages: type: integer format: int32 description: Total number of pages available. total_count: type: integer format: int32 description: Total number of items. 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 WorkflowTaskSimpleResponse: type: object description: A simplified task representation used in list responses. properties: id: type: string description: Task ID output: $ref: '#/components/schemas/TaskOutputDto' description: Present only when the task has ended. status: $ref: '#/components/schemas/TaskStatus' live_url_info: $ref: '#/components/schemas/LiveUrlInfo' description: Present only when the task is `running`. live_url: type: string deprecated: true description: Deprecated. Use `live_url_info.live_url` instead. profile_id: type: string description: Browser profile ID for reusing browser data. created_at: type: string format: date-time description: Task creation time finished_at: type: string format: date-time description: Task finish time (if ended) task_failure_info: $ref: '#/components/schemas/TaskFailureInfo' credit: type: integer format: int64 description: Credits consumed by this task. example: 42 workflow_id: type: string description: Workflow ID input_parameters: type: string description: Workflow input parameters in key=value form. example: keyword=laptops;max_items=50 required: - created_at - id - status - workflow_id TaskOutputDto: type: object description: |- Task output produced by the workflow. The exact output depends on the workflow. Common patterns: - `string`: plain text or JSON string - `files`: URLs for output files (if any) properties: string: type: string description: Plain output string (format depends on the workflow). example: '{"items":[...]}' files: type: array description: Output file URLs (if any). items: type: string LiveUrlInfo: type: object description: |- Information for viewing a live task execution. Available only when the task status is `running`. properties: width: type: integer format: int32 description: Viewport width example: 1280 height: type: integer format: int32 description: Viewport height example: 720 live_url: type: string description: Live view URL. Can be embedded in an `