> ## 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

> Click, type, scroll, wait and capture on a page before it is read. Send up to 50 steps in actions. They cost nothing on top of the page.

`actions` runs steps on the page, in order, before Scrape reads it. Use them to load more results, open a tab, fill a search box, or capture a screenshot at the right moment. Actions need an API key.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request scrolls a news front page, clicks its "More" link, waits a second, takes a screenshot, and then reads the page it ends on.

```bash cURL 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" }
    ]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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" },
    ],
  }),
});
const { data } = await response.json();
console.log(data.metadata.url);
console.log(data.actions.screenshots[0]);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "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"},
        ],
    },
)
data = response.json()["data"]
print(data["metadata"]["url"])
print(data["actions"]["screenshots"][0])
```

## Read the response

The formats you asked for describe the page after the last action. `actions` holds what the capture steps produced. This real response is cut. The Markdown was 14,215 characters, and `links` held 197 URLs.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "31. [Frame – 31.5\" color ePaper display](https://trmnl.com/blog/introducing-frame) ( [trmnl.com](https://news.ycombinator.com/from?site=trmnl.com))515 points by …",
    "links": [
      "https://news.ycombinator.com/",
      "https://news.ycombinator.com/news",
      "https://news.ycombinator.com/newest"
    ],
    "actions": {
      "screenshots": [
        "https://stophy.agentfsusercontent.com/screenshots/48b7bf25-92a3-42ce-9fe5-2dbe858fb872.jpg"
      ],
      "scrapes": [],
      "javascriptReturns": [],
      "pdfs": []
    },
    "metadata": {
      "title": "Hacker News",
      "language": "en",
      "sourceURL": "https://news.ycombinator.com/",
      "url": "https://news.ycombinator.com/?p=2",
      "statusCode": 200,
      "contentType": "text/html",
      "cacheState": "miss",
      "scrapeId": "f71d1f77-9bbc-45fa-804f-bdf23017f177",
      "costUsd": 0.001
    }
  },
  "id": "f71d1f77-9bbc-45fa-804f-bdf23017f177",
  "costUsd": 0.001,
  "requestId": "f71d1f77-9bbc-45fa-804f-bdf23017f177"
}
```

`metadata.sourceURL` is the URL you sent. `metadata.url` is where the page ended up, here the second page of results. Each screenshot is a link that works for 7 days.

## Action types

| Type | Fields | What it does |
| - | - | - |
| `wait` | `milliseconds`: 1 to 60,000 | Pauses. |
| `wait` | `selector`: a CSS selector | Waits until an element matching the selector appears, for up to 30 seconds. |
| `click` | `selector`: a CSS selector | Clicks the first match. It looks for the element for up to 5 seconds. `all` is accepted only as `false`. |
| `write` | `text`: the text to type | Types the text. |
| `press` | `key`: up to 40 characters, such as `Enter` | Presses a key. |
| `scroll` | `direction`: `down` (default), `up`, `left` or `right`. `amount`: pixels from 1 to 100,000, `"viewport"` or `"max"`. `maxScrolls`: 1 to 50. `selector`: an inner scroll container. | Scrolls. `"max"` keeps scrolling until the page stops growing, for feeds that load as you go. |
| `screenshot` | `fullPage`: boolean. `quality`: 1 to 100. `viewport`: `{ width, height }`, 200 to 3,840 by 200 to 2,160. | Takes a JPEG. The link comes back in `actions.screenshots`. |
| `scrape` | none | Captures the page at this point. The URL and HTML come back in `actions.scrapes`. |
| `executeJavascript` | `script`: up to 20,000 characters | Runs the script on the page for up to 5 seconds. What it returns comes back in `actions.javascriptReturns` as `{ type, value }`. |
| `pdf` | `format`: `Letter`, `Legal`, `Tabloid`, `Ledger` or `A0` to `A6`. `landscape`: boolean. `scale`: 0.1 to 2. | Prints the page to a PDF. The link comes back in `actions.pdfs`. |
| `perform` | `action`: a step in plain words, 1 to 500 characters | A step such as `Click the Load more button`. It can take up to 5 browser steps on the page, up to 30 seconds, and never leaves the site. |

Captures come back in the order the steps ran.

## A failed action

When a step fails, you still get the page as it stood, and the actions after the failed one do not run. The response has a `warning` that names the step and says why. The call is still billed as one page. This request body clicks a button that does not exist.

```json theme={null}
{
  "url": "https://example.com",
  "actions": [
    { "type": "click", "selector": "button.does-not-exist" }
  ]
}
```

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "This domain is for use in documentation examples without needing permission. …",
    "warning": "PageAction 1 (click) failed: nothing matched button.does-not-exist. This is the page as it stood before that action, and the actions after it did not run.",
    "metadata": {
      "title": "Example Domain",
      "sourceURL": "https://example.com/",
      "url": "https://example.com/",
      "statusCode": 200,
      "cacheState": "miss",
      "costUsd": 0.001
    }
  },
  "id": "c4929bff-2137-4c6e-b071-339c3047981e",
  "costUsd": 0.001,
  "requestId": "c4929bff-2137-4c6e-b071-339c3047981e"
}
```

Always read `warning` when you send actions. To work out which selector to use, open the page in a [browser session](https://docs.stophy.dev/scrape/interact.md) and try it there.

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `actions` | `array of object` | none | 1 to 50 steps, run in order before the page is read. At most 5 can be `perform`. |

## Limits and errors

* Actions need an API key. Without one, the call returns `401 apiKeyRequired`.
* A step that does not fit the table returns `400 invalidRequest` and names the step.
* With `zeroDataRetention`, `screenshot` and `pdf` steps return `400 invalidRequest`, because they are kept as files.
* A read with actions is always live. It is never answered from a stored copy.
* Waits count toward the call's `timeout`. See [Timeouts and errors](https://docs.stophy.dev/scrape/timeouts-and-errors.md).

## Price

\$1 per 1,000 pages. The actions add nothing, and neither do their screenshots, captures and PDFs.

## Related

* [Interact](https://docs.stophy.dev/scrape/interact.md) keeps working on a scraped page after the call.
* [Waiting and rendering](https://docs.stophy.dev/scrape/waiting-and-rendering.md) sets a plain wait without any step.
* [Screenshot](https://docs.stophy.dev/scrape/screenshot.md) takes one picture of the page without actions.
* [Scrape overview](https://docs.stophy.dev/scrape/overview) lists every format and option.


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