/session/bql/*
POST/session/bql/*
> Executes BrowserQL queries against an existing session.
BrowserQL is a GraphQL-based query language for browser automation that allows you to interact with web pages using a declarative syntax. Queries execute within the context of your existing session, maintaining browser state and session data across multiple operations.
Request
Query Parameters
Possible values: [datacenter, residential]
Possible values: [0, 1, false, true]
Possible values: [0, 1, false, true]
Body
- Schema
- Example (auto)
- Get browser info:
query { version browser } - Navigate and get content:
mutation { goto(url: "https://example.com") { status } title { title } url { url } } - Fill form and submit:
mutation { goto(url: "https://example.com") { status } type(selector: "input[name='email']", text: "user@example.com") { time } click(selector: "button[type='submit']") { time } } - Extract data:
mutation { querySelector(selector: "h1") { innerHTML } querySelectorAll(selector: ".product") { innerHTML className } }
The GraphQL query string to execute against the browser session.
Example queries:
variables object
Variables to pass to the GraphQL query. Useful for dynamic values.
Example: { "url": "https://example.com", "selector": "h1", "text": "Hello World" }
Variables to pass to the GraphQL query. Useful for dynamic values.
Example: { "url": "https://example.com", "selector": "h1", "text": "Hello World" }
The name of the operation to execute if the query contains multiple operations. Optional - only needed when query has multiple named operations.
{
"query": "string",
"variables": {},
"operationName": "string"
}
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 429
- 500
- 503
Schema
- Fields
- Example (auto)
- Navigation + Title + Element:
{ "goto": { "status": 200 }, "title": { "title": "Example Domain" }, "querySelector": { "innerHTML": "Example Domain" } } - Multiple elements:
{ "querySelectorAll": [{ "innerHTML": "Item 1" }, { "innerHTML": "Item 2" }] } - Screenshot:
{ "screenshot": { "data": "base64encodedimage", "type": "png" } } - PDF:
{ "pdf": { "data": "base64encodedpdf" } } - System info:
{ "version": "1.0.0", "browser": "Chrome/120.0.0.0" } - Form interaction:
{ "type": { "success": true }, "click": { "success": true } } - Array [
- Array [
- ]
- ]
The GraphQL response data. Contains the result of the executed query. Structure depends on the specific query executed.
Example responses:
errors object[]
Array of GraphQL errors, if any occurred during query execution. Only present when errors exist.
Error message describing what went wrong
locations object[]
Locations in the query where the error occurred
Path to the field that caused the error
{
"data": {},
"errors": [
{
"message": "string",
"locations": [
{
"line": 0,
"column": 0
}
],
"path": [
"string"
]
}
]
}
The request contains errors or didn't properly encode content.
The request is missing, or contains bad, authorization credentials.
The request targets a destination that is not allowed.
Resource couldn't be found.
The request took has taken too long to process.
Too many requests are currently being processed.
An internal error occurred when handling the request.
Service is unavailable.