> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser actions

> Run ordered steps such as click, scroll, type or screenshot on a page before Scrape reads it. Capture mid flow results and handle a step that fails.

`actions` runs up to 50 steps in order before the page is read. Use it to load more results, open a tab, fill a search box or capture the page at the right moment. It needs an API key. Without one the call returns `401 apiKeyRequired`.

This request scrolls, clicks "More", waits a second, takes a screenshot, then reads the page it ends on:

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "formats": ["markdown", "links"],
    "actions": [
      { "type": "scroll", "direction": "down", "amount": "viewport" },
      { "type": "click", "selector": "a.morelink" },
      { "type": "wait", "milliseconds": 1000 },
      { "type": "screenshot" }
    ]
  }'
```

The formats describe the page after the last step. Captures from the middle come back under `data.actions`, in the order the steps ran. `metadata.sourceURL` is the URL you sent and `metadata.url` is where the page ended up.

```json theme={null}
{
  "success": true,
  "data": {
    "actions": {
      "screenshots": ["https://stophy.agentfsusercontent.com/screenshots/48b7bf25-92a3-42ce-9fe5-2dbe858fb872.jpg"],
      "scrapes": [],
      "javascriptReturns": [],
      "pdfs": []
    },
    "metadata": {
      "sourceURL": "https://news.ycombinator.com/",
      "url": "https://news.ycombinator.com/?p=2"
    }
  }
}
```

## Steps

| `type` | Fields | What it does |
| - | - | - |
| `wait` | `milliseconds`, 1 to 60,000 | Pauses. |
| `wait` | `selector` | Waits up to 30 seconds for a matching element. |
| `click` | `selector` | Clicks the first match, looking for it for up to 5 seconds. `all` is accepted only as `false`. |
| `write` | `text` | Types the text. |
| `press` | `key`, up to 40 characters, such as `Enter` | Presses a key. |
| `scroll` | `direction`: `down` (default), `up`, `left`, `right`. `amount`: 1 to 100,000 pixels, `"viewport"` or `"max"`. `maxScrolls`: 1 to 50. `selector`: an inner container. | Scrolls. `"max"` keeps going until the page stops growing. |
| `screenshot` | `fullPage`, `quality` 1 to 100, `viewport` `{ width, height }` | Takes a JPEG. The link comes back in `actions.screenshots` and works for 7 days. |
| `scrape` | none | Captures the page here. URL and HTML come back in `actions.scrapes`. |
| `executeJavascript` | `script`, up to 20,000 characters | Runs for up to 5 seconds. The result comes back in `actions.javascriptReturns` as `{ type, value }`. |
| `pdf` | `format`: `Letter`, `Legal`, `Tabloid`, `Ledger` or `A0` to `A6`. `landscape`. `scale`: 0.1 to 2. | Prints the page. The link comes back in `actions.pdfs`. |
| `perform` | `action`: a step in plain words, 1 to 500 characters | Does something like `Click the Load more button` in up to 5 browser steps, up to 30 seconds, and never leaves the site. At most 5 per call. |

## Failures and limits

* When a step fails, the later steps do not run. You still get the page as it stood, with a `warning` that names the step and says why. Always read `warning` when you send actions. To find the right selector, try it in an [Interact](https://docs.stophy.dev/scrape/interact.md) session.
* A step that does not fit the table returns `400 invalidRequest` and names the step.
* `screenshot` and `pdf` steps with `zeroDataRetention` return `400 invalidRequest`, because they are kept as files.
* A read with actions is always live. Waits count toward `timeout`.
* The actions add no fee. See [Pricing](https://docs.stophy.dev/account/pricing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.