> ## 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 bots > Returns a paginated list of Bots that have a runnable published version. ### Filtering - Use `bot_type` to select a Bot type. The public `agent` value means SkillFlow. - Use `keyword` for a case-insensitive Bot name search. ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. ## OpenAPI ````yaml /openapi_3.json get /v3/bots 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"). The public `bot_type=agent` value represents **SkillFlow**, not the legacy Agent app type. ## 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`: SkillFlow 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 SkillFlow input is missing - `10176`: Bot template does not exist - `10879`: SkillFlow 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: get: tags: - Bots summary: List bots description: >- Returns a paginated list of Bots that have a runnable published version. ### Filtering - Use `bot_type` to select a Bot type. The public `agent` value means SkillFlow. - Use `keyword` for a case-insensitive Bot name search. ### Pagination Use `page` and `limit`. The response includes `total_pages` and `total_count`. operationId: pageBots parameters: - name: bot_type in: query required: false description: Optional bot type filter. agent represents SkillFlow. schema: type: string enum: - workflow - agent example: workflow - name: keyword in: query required: false description: Search keyword (optional). schema: type: string maxLength: 200 example: order - 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 Bots per page (max 100). schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Bots returned. content: application/json: schema: $ref: '#/components/schemas/BotSummaryPage' example: items: - bot_id: '1001' bot_type: workflow name: Order status lookup description: Looks up an order and returns its current status. published_at: '2026-08-10T03:00:00Z' 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: BotSummaryPage: type: object properties: items: type: array description: Items for the current page. items: $ref: '#/components/schemas/BotSummaryResponse' 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 BotSummaryResponse: type: object properties: bot_id: type: string description: Public bot identifier. bot_type: $ref: '#/components/schemas/BotType' name: type: string description: Bot name description: type: string description: Bot description published_at: type: string format: date-time description: Time when the currently runnable bot definition was published. required: - bot_id - bot_type - name BotType: type: string enum: - workflow - agent description: >- Public bot type. agent represents SkillFlow, not the legacy Agent app type. securitySchemes: HTTPBearer: type: http scheme: bearer description: Send your API key in the `Authorization` header as `Bearer `. ````