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

# Interact

> Keep working on a page you already scraped in a live browser session. Run code or plain-words steps on it, then close it. Billed by the hour open.

Interact opens a browser session on a page you already scraped. Run code or a plain-words step on it, as many times as you need, then close it. Use it when [browser actions](https://docs.stophy.dev/scrape/browser-actions.md) are not enough: a form with several steps, a value you only see after clicking through, or a page you want to look at before you decide what to do.

## Make a request

You need an API key and the `id` of a scrape from the last 24 hours. Scrape the page first, then send code to `POST /v1/scrape/{id}/interact`.

```bash cURL theme={null}
SCRAPE_ID=$(curl -s -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }' | jq -r .id)

curl -X POST https://api.stophy.dev/v1/scrape/$SCRAPE_ID/interact \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "return await page.title();" }'
```

```typescript TypeScript theme={null}
const headers = {
  Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  "Content-Type": "application/json",
};

const scrape = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers,
  body: JSON.stringify({ url: "https://example.com" }),
});
const { id } = await scrape.json();

const response = await fetch(`https://api.stophy.dev/v1/scrape/${id}/interact`, {
  method: "POST",
  headers,
  body: JSON.stringify({ code: "return await page.title();" }),
});
const run = await response.json();
console.log(run.result);
```

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

import requests

headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}

scrape = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers=headers,
    json={"url": "https://example.com"},
)
scrape_id = scrape.json()["id"]

response = requests.post(
    f"https://api.stophy.dev/v1/scrape/{scrape_id}/interact",
    headers=headers,
    json={"code": "return await page.title();"},
)
print(response.json()["result"])
```

The first call opens the session on the page the scrape read. If that scrape ran [actions](https://docs.stophy.dev/scrape/browser-actions.md), they run again first so the page is as the scrape left it. The same location and `blockAds` choice carry over. Send `url` to open another URL instead.

In your code, `page` is the session's browser page. It has Playwright-style methods such as `page.title()` and `page.locator(selector)`. Code runs as Node.js by default. Send `language` as `python` or `bash` to change that.

## Read the response

`result` is the value your code returned, as text. `output` is what it printed. The links let you connect your own tools or watch the session. They are cut here.

```json theme={null}
{
  "success": true,
  "output": "",
  "stdout": "",
  "result": "Example Domain",
  "stderr": "",
  "exitCode": 0,
  "killed": false,
  "truncated": false,
  "cdpUrl": "wss://api.stophy.dev/v1/interact/5bf74358-c6ae-4d2c-bb55-209267f5acf5/cdp?token=…",
  "liveViewUrl": "https://api.stophy.dev/v1/interact/5bf74358-c6ae-4d2c-bb55-209267f5acf5/live#…",
  "interactiveLiveViewUrl": "https://api.stophy.dev/v1/interact/5bf74358-c6ae-4d2c-bb55-209267f5acf5/live#…",
  "costUsd": 0,
  "requestId": "40c13e01-cc73-4fcf-bc52-ad3ca2b5bea0"
}
```

The call itself costs nothing. You pay for the time the session is open, when it closes.

## Close the session

Send `DELETE` to the same path as soon as you are done. This is when the time is billed.

```bash cURL theme={null}
SCRAPE_ID="<the id your scrape returned>"
curl -X DELETE https://api.stophy.dev/v1/scrape/$SCRAPE_ID/interact \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const id = "<the id your scrape returned>";
const response = await fetch(`https://api.stophy.dev/v1/scrape/${id}/interact`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
console.log(await response.json());
```

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

import requests

scrape_id = "<the id your scrape returned>"
response = requests.delete(
    f"https://api.stophy.dev/v1/scrape/{scrape_id}/interact",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
print(response.json())
```

This real session was open for about 9 seconds and cost \$0.004. The response is cut to the fields that matter.

```json theme={null}
{
  "success": true,
  "sessionDurationMs": 8965,
  "costUsd": 0.004,
  "creditsUsed": 2,
  "requestId": "4cd26d99-e3ac-4b9b-8797-82e11d5a0cad"
}
```

`sessionDurationMs` is how long the session was open. A session also ends by itself after 5 minutes without a call, and after 10 minutes at most. You are billed for the time it was open either way, so close it yourself.

## Options

Send `code` or `prompt`. A body with neither returns `400 invalidRequest` with the message `Send code or a prompt.`

| Field | Type | Default | Effect |
| - | - | - | - |
| `code` | `string` | none | A script that drives the page, up to 200,000 characters. |
| `prompt` | `string` | none | What you want done in plain words, up to 10,000 characters. An agent does it on the page. |
| `language` | `string` | `"node"` | The language of `code`: `node`, `python` or `bash`. |
| `timeout` | `number` | `30` | Seconds the run may take, 1 to 300. A run that goes over is stopped and returns `killed: true`. |
| `url` | `string` | the scrape's URL | Open this URL instead, on the first call. On a later call it moves the session there. |
| `zeroDataRetention` | `boolean` | `false` | Keep nothing from this session. Send it on the first call. |

| Response field | What it holds |
| - | - |
| `result` | The value the code returned, as text. |
| `output`, `stdout`, `stderr` | What the code printed. Output past 200,000 characters is cut and `truncated` is `true`. |
| `exitCode`, `killed`, `error` | How the run ended. `error` is set when it failed or ran out of time. |
| `steps`, `page` | For `prompt`: the steps taken, and the page's `url` and `title` at the end. |
| `cdpUrl` | Connect a CDP client such as Playwright to the session. |
| `liveViewUrl`, `interactiveLiveViewUrl` | Watch the session, or watch and take control. |
| `warning` | Set when a scrape action did not replay. It names the action. |

## Price

$0.06 per hour while the session is open, billed when you close it, one minute at least. Once a `prompt` has run in a session, it is $0.84 per hour for the rest of that session. Traffic through the session costs $5 per GB on the default network and $0.20 per GB direct or through your own proxy. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Limits and errors

* A scrape id that is more than 24 hours old, or a scrape sent with `zeroDataRetention`, returns `404 notFound`. Scrape the page again.
* A free account can have 3 sessions open at once, and a paid account 10. Over that, the call returns `429 rateLimited`. Close one and send it again.
* Once a session has ended, the next call on the same scrape opens a new one, and it is billed on its own.
* `zeroDataRetention` on a call that reaches a session already open without it returns `400 invalidRequest`. Close the session with `DELETE`, then send it on the first call.
* A `DELETE` on a scrape with no open session returns `200` and bills nothing.

## Related

* [Browser actions](https://docs.stophy.dev/scrape/browser-actions.md) run steps before the read, with no session to close.
* [Browser overview](https://docs.stophy.dev/browser/overview) opens a session on any URL, not only a scraped one.
* [Browser execute](https://docs.stophy.dev/browser/execute.md) runs code in a session you opened yourself.
* [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md) explains the scrape id and its 24 hours.


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