> ## 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. # Retrieve a task > Returns comprehensive information about a task, including: - current `status` - step-level progress (`steps`) - output (if finished) - failure details (if failed) If you only need the current status, use `GET /v2/workflow/get-task-status`. ## OpenAPI ````yaml /openapi_2.json get /v2/workflow/get-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/get-task: get: tags: - Tasks summary: Retrieve a task description: >- Returns comprehensive information about a task, including: - current `status` - step-level progress (`steps`) - output (if finished) - failure details (if failed) If you only need the current status, use `GET /v2/workflow/get-task-status`. operationId: getTask parameters: - name: task_id in: query description: Task ID returned by `run-task` or `run-task-by-template`. required: true schema: type: string minLength: 1 example: task_123456789 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/WorkflowTaskResponse' '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: WorkflowTaskResponse: type: object description: >- Full task details, including step-level progress and outputs (when available). 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' steps: type: array description: Steps executed within the task. items: $ref: '#/components/schemas/TaskStepDto' 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. download_files: type: array description: Files generated by the task (if any). items: $ref: '#/components/schemas/TaskDownloadFileView' files_expires_at: type: integer format: int64 description: Expiration timestamp for download files. workflow_id: type: string description: Workflow ID input_parameters: type: string description: Input parameters used for this run, as `key=value` pairs. log_detail_url: type: string description: URL to detailed execution logs for this task. required: - created_at - id - status - steps - workflow_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 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 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 TaskStepDto: type: object description: A single step within a task execution. properties: id: type: string description: Step ID step: type: integer format: int32 description: Step sequence number status: $ref: '#/components/schemas/StepStatus' 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 required: - evaluation_previous_goal - id - screenshots_url - status - step - step_goal 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 `