> ## 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 Bot execution tasks. ### Filtering - Use `status` to filter by task status. - Use `bot_id` to list tasks created from a specific Bot. - Use `bot_name` to search by Bot name using a contains match. - Use `created_at_from` / `created_at_to` for inclusive task creation time bounds in ISO 8601 format. ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. Normal Bot runs can include `bot_id` and `bot_name`. Official template runs omit template source fields and internal copied Bot IDs. ## OpenAPI ````yaml /openapi_3.json get /v3/bots/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"). ## 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`: Agent bot 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 agent bot input is missing - `10176`: Bot template does not exist - `10879`: Agent bot 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/runs: get: tags: - Tasks summary: List tasks description: >- Returns a paginated list of Bot execution tasks. ### Filtering - Use `status` to filter by task status. - Use `bot_id` to list tasks created from a specific Bot. - Use `bot_name` to search by Bot name using a contains match. - Use `created_at_from` / `created_at_to` for inclusive task creation time bounds in ISO 8601 format. ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. Normal Bot runs can include `bot_id` and `bot_name`. Official template runs omit template source fields and internal copied Bot IDs. operationId: pageRuns parameters: - name: bot_id in: query required: false description: Optional public bot identifier filter. schema: type: string example: '1001' - name: bot_name in: query required: false description: Optional bot name keyword (fuzzy match, contains). schema: type: string example: Order status - name: status in: query required: false description: Filter tasks by status. schema: $ref: '#/components/schemas/BotRunStatus' example: running - name: created_at_from in: query required: false description: >- Lower bound of task creation time (inclusive). ISO 8601 format, e.g. `2024-01-01T00:00:00Z`. schema: type: string format: date-time example: '2026-08-01T00:00:00Z' - name: created_at_to in: query required: false description: >- Upper bound of task creation time (inclusive). ISO 8601 format, e.g. `2024-12-31T23:59:59Z`. schema: type: string format: date-time example: '2026-08-31T23:59:59Z' - name: page in: query required: false description: Page number to retrieve (starts at 1). schema: type: integer minimum: 1 default: 1 - name: limit in: query required: false description: Number of tasks per page (max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Runs returned. content: application/json: schema: $ref: '#/components/schemas/BotRunSummaryPage' example: items: - task_id: '93001' bot_id: '1001' bot_type: workflow bot_name: Order status lookup status: running created_at: '2026-08-13T09:00:00Z' input: order_id: A-100 live_url_info: live_url: https://live.browseract.com/93001 width: 1280 height: 1024 page: 1 limit: 20 total_count: 1 total_pages: 1 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: BotRunStatus: type: string enum: - created - running - finished - canceled - pausing - paused - failed description: Public lifecycle status of a bot run. BotRunSummaryPage: type: object properties: items: type: array description: Tasks for the current page. items: $ref: '#/components/schemas/BotRunSummaryResponse' page: type: integer description: Current page number. limit: type: integer description: Number of items per page. total_count: type: integer format: int64 description: Total number of items. total_pages: type: integer description: Total number of pages available. required: - items - page - limit - total_count - total_pages 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 BotRunSummaryResponse: type: object properties: task_id: type: string description: Task ID bot_id: type: string description: >- Public bot identifier used by a normal Bot run. Absent for an official template 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' 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 - bot_type - status - created_at - input BotType: type: string enum: - workflow - agent description: Public bot type. BotRunFailureInfoResponse: type: object properties: code: type: integer description: Error code message: type: string description: Error message required: - code - message BotRunLiveUrlInfoResponse: type: object properties: live_url: type: string description: Live view URL. Can be embedded in an `