For AI agents: a documentation index is available at /llms.txt
Skip to main content

/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

    blockAds boolean
    blockAdsInclude string
    launch object
    profile string
    replay boolean
    timeout number
    token string
    trackingId string
    allowedDomains string[]
    credentials object
    externalProxyServer string
    integrationId string
    proxy ProxyType

    Possible values: [datacenter, residential]

    proxyCity string
    proxyCountry string
    proxyLocaleMatch string

    Possible values: [0, 1, false, true]

    proxyPreset string
    proxyState string
    proxySticky string

    Possible values: [0, 1, false, true]

Body

    querystringrequired

    The GraphQL query string to execute against the browser session.

    Example queries:

    • 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 } }
    variables object

    Variables to pass to the GraphQL query. Useful for dynamic values.

    Example: { "url": "https://example.com", "selector": "h1", "text": "Hello World" }

    property name*any

    Variables to pass to the GraphQL query. Useful for dynamic values.

    Example: { "url": "https://example.com", "selector": "h1", "text": "Hello World" }

    operationNamestring

    The name of the operation to execute if the query contains multiple operations. Optional - only needed when query has multiple named operations.

Responses​

Schema
    dataobject

    The GraphQL response data. Contains the result of the executed query. Structure depends on the specific query executed.

    Example responses:

    • 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 } }
    errors object[]

    Array of GraphQL errors, if any occurred during query execution. Only present when errors exist.

  • Array [
  • messagestringrequired

    Error message describing what went wrong

    locations object[]

    Locations in the query where the error occurred

  • Array [
  • linenumberrequired
    columnnumberrequired
  • ]
  • path(string | number)[]

    Path to the field that caused the error

  • ]
Was this page helpful?