Actions

Click, type, choose, scroll: options.actions runs steps in the page before the data is extracted. They run in a browser if you use one, and without one too: links are followed and forms are submitted with plain requests.

"options": {
  "actions": [
    { "fill": "#q", "value": "lamp" },
    { "click": "#go" }
  ]
}

See it workCopy Anchor Link

The demo shop has a search form with a hidden security token. Fill it in and submit it, without a browser: the API reads the form, keeps the hidden token and the session cookie, and posts it like a browser would:

The response tells you what each action did:

"actions": [
  {
    "action": "fill",
    "status": "emulated",
    "detail": "set the field's value for the next form submission"
  },
  {
    "action": "select",
    "status": "emulated",
    "detail": "set the field's value for the next form submission"
  },
  {
    "action": "click",
    "status": "emulated",
    "detail": "submitted the form as POST /demo/shop/search"
  }
]

The "Gift ideas" button only works with JavaScript. Without a browser it's skipped; with one, it runs:

Ready-made recipes for pagination, "Load more" buttons, cookie banners, forms and infinite scroll are in Recipes.

Available actionsCopy Anchor Link

Each action is an object with one action name:

Up to 50 actions per request. The data is extracted from the page as it is after the last action.

AI actionsCopy Anchor Link

Describe what to do instead of writing selectors: { "ai": "…" } reads the page's buttons, links and fields, and turns the instructions into the actions above.

The result lists the actions it ran, so you can copy them into a request without AI:

{
  "action": "ai",
  "status": "done",
  "detail": "5 action(s)",
  "ai": {
    "actions": [{ "click": "#accept" }, { "click": "#load-more" }, { "wait": 1000 }, { "click": "#load-more" }, { "wait": 1000 }],
    "cached": false,
    "cost_usd": 0.0003
  }
}

• Remembered: the plan is kept per site page and instructions (numbers and ids in the path don't count, so /product/12 and /product/13 share it). Later requests replay it without calling the model: "cached": true, and no AI credits.
• Repaired: when a remembered action no longer works (the site changed), the model plans the rest again from the current page, and the new plan replaces the old one.
• Plans are kept per account: instructions may hold values you don't want shared.
• One element in plain words works in any action that takes a selector: { "click": { "ai": "the Load more button" } }, { "fill": { "ai": "the search box" }, "value": "lamp" }. It's an ai action for that one step, remembered the same way.
• It needs a browser, and is billed like an AI call only when the model is asked.

With and without a browserCopy Anchor Link

The same actions work in both cases. Without a browser, what a plain request can do is emulated, and the rest is skipped, never fatal:

When an action is skipped, a warning suggests setting options.browser.

ResultsCopy Anchor Link

actions in the response lists each action in order:

When an action failsCopy Anchor Link

In a browser, an action fails when its element doesn't appear before the timeout: the request stops with 422 ACTION_FAILED, naming the action:

{
  "error": {
    "code": "ACTION_FAILED",
    "message": "actions[1] (click) failed: Timeout 15000ms exceeded."
  }
}

Mark an action "optional": true to carry on instead, like closing a cookie banner that isn't always there:

"actions": [
  { "click": "#accept-cookies", "optional": true },
  { "click": "#load-more" }
]

ACTION_FAILED triggers fallback strategies, so you can try another engine, or no browser at all, when an action fails.