> ## 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 after you scrape it. Send code or a plain words step, read the result, then decide the next step. Close the session when done.

Use Interact 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. It needs an API key and the `metadata.scrapeId` of a scrape from the last 24 hours. A scrape sent with `zeroDataRetention` cannot be interacted with.

```bash 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 .data.metadata.scrapeId)

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();" }'
```

The first call opens a session on the page the scrape read. If that scrape ran `actions`, they run again first. The same location and `blockAds` choice carry over. In your code, `page` is the session's browser page with Playwright style methods such as `page.title()` and `page.locator(selector)`.

```json theme={null}
{
  "success": true,
  "output": "",
  "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#…",
  "costUsd": 0,
  "requestId": "40c13e01-cc73-4fcf-bc52-ad3ca2b5bea0"
}
```

Check `exitCode` and `killed` before you use `result`. The call itself is free. You pay for the time the session is open, when it closes. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Request fields

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

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

## Response fields

| Field | 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. |
| `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. |

## Close the session

Send `DELETE /v1/scrape/{id}/interact` as soon as you are done. The response has `sessionDurationMs` and `costUsd`. A `DELETE` with no open session returns `200` and bills nothing. A session also ends after 5 minutes without a call and after 10 minutes at most, and you are billed for the time it was open. After it ends, the next call on the same scrape opens a new session, billed on its own.

## Limits and errors

* A scrape id older than 24 hours returns `404 notFound`. Scrape the page again.
* Open sessions are capped per plan. Over the cap the call returns `429 rateLimited`. Close one and send again. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).
* `zeroDataRetention` on a call that reaches a session opened without it returns `400 invalidRequest`. Close the session with `DELETE`, then send it on the first call.

To open a session on any URL, see [Browser](https://docs.stophy.dev/browser/overview).


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