Browser actions

The actions array runs a sequence of browser actions against the page before returning. The API navigates to your url first, then executes each action in order. An array can contain 1 to 50 actions.

{
  "url": "https://example.com/search",
  "actions": [
    { "type": "write", "text": "wireless headphones" },
    { "type": "press", "key": "Enter" },
    { "type": "wait", "selector": ".results" },
    { "type": "scroll", "direction": "down", "amount": 2000 },
    { "type": "screenshot", "full_page": true }
  ]
}

Action types

Each action is an object with a type and its own fields.

frame runs the action inside an iframe. See Act inside an iframe.

Timing

The API loads your url before the first action and, like every navigate, waits for the page to load. After that page load, and after every navigate, click, press, scroll and selectOption, it lets the page settle for about 3 seconds at most, or less once the network goes quiet. write, hover, wait, screenshot, waitForResponse and waitForNetworkIdle run without a settle. The whole sequence must finish within 180 seconds; past that it fails at the next action.

Set waitUntil on the request to choose what loading url waits for instead: the HTML parsed, the load event, or the network going idle. It applies only to loading url.

The settle is best effort, so don't rely on it for content that loads slowly. Wait for what you need: a wait with a selector for an element, a waitForResponse for a network response, or a waitForNetworkIdle for the network to go idle.

Timeouts

A waitForNetworkIdle that runs out under onTimeout: "continue" is listed in timedOutActions.

Capture the page's network requests

Add captureXHR with executeJS: true to get every XHR and fetch() request the session made, including the ones your actions triggered, as xhr. Use a waitForResponse with asResult to return one API response as data instead of the page.

{
  "url": "https://shop.example.com/category/headphones",
  "actions": [
    { "type": "click", "selector": "button.load-more" },
    { "type": "waitForResponse", "url": "/api/products", "statusCodes": [200], "asResult": true }
  ]
}

Act inside an iframe

Give wait, click, scroll, hover or selectOption a frame, a selector for the <iframe> element, and the action runs inside it, cross-origin iframes included. For an iframe inside another, frame is a list of selectors from the outermost iframe in, at most 5. write and press type into whatever has focus, so click the field first. To get the iframes' content back with the page, add includeIframes: true or captureIframes: true. See Iframes.

Response

{
  "statusCode": 200,
  "headers": { "content-type": ["text/html"] },
  "finalUrl": "https://example.com/search?q=wireless+headphones",
  "data": "<!doctype html>…",
  "screenshot": { "format": "png", "base64": "iVBORw0KGgo…" }
}

A failed action still returns 200, and data holds the page as it stood when it failed — usually the quickest way to see why a selector missed. Fields that describe a wait or a limit, such as timedOutActions and iframesTruncated, are absent unless they apply.

Markdown output

Set format: "markdown" to get the final page converted in data, through the same converter a plain /fetch uses, so a page reads the same whichever way you fetched it. Worth setting when the response feeds a model rather than a parser. markdownMode: "full" and mainContentOnly: true work here too.

{
  "url": "https://example.com/search",
  "format": "markdown",
  "markdownMode": "full",
  "actions": [{ "type": "wait", "selector": ".results" }]
}

The response envelope stays JSON either way — finalUrl, screenshot and failedActionIndex have nowhere to ride in a bare Markdown body. format: "raw" is rejected for the same reason. A page too large to convert comes back as HTML; see Large pages.