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

# Execute

> Run code or a plain-words prompt in an open browser session with one call, then read what it printed, returned and which steps it took.

`POST /v1/browser/{session_id}/execute` runs `code` or a `prompt` in a session you [opened](https://docs.stophy.dev/browser/overview). In your code, `page` is the session's page with Playwright-style methods. Every `page` call is asynchronous, so `await` it.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/browser/$SESSION_ID/execute \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "await page.goto(\"https://example.com\");\nreturn { title: await page.title(), url: await page.url() };"}'
```

```json theme={null}
{
  "success": true,
  "output": "",
  "result": "{\"title\":\"Example Domain\",\"url\":\"https://example.com/\"}",
  "stderr": "",
  "exitCode": 0,
  "killed": false,
  "truncated": false,
  "costUsd": 0
}
```

A failed run still answers `200`. Check `exitCode` and `error` before you trust `result`. Running code does not raise the session price. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Request fields

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

| Field | Default | Meaning |
| - | - | - |
| `code` | none | Code to run, 1 to 200,000 characters |
| `prompt` | none | What to do, in plain words, 1 to 10,000 characters. Ignored when `code` is also sent. Stophy clicks and types for you, up to 50 steps. |
| `language` | `node` | `node`, `python` or `bash`. Used with `code`. |
| `timeout` | `30` for code, `120` for a prompt | Seconds the call may run, 1 to 300 |

`url` and `zeroDataRetention` are not accepted here. Open the page with `page.goto`, and set zero data retention when you open the session.

| `language` | Write | Return a value with |
| - | - | - |
| `node` | `await page.goto(url)`, `await page.locator(selector).click()` | `return` |
| `python` | `page.goto(url)`. `page.url` is a property, not a call. | Set a variable named `result` |
| `bash` | `page goto https://example.com`, one command a line | Print it. There is no `result`. |

## Response fields

| Field | Meaning |
| - | - |
| `output`, `stdout` | What the code printed, or the answer to a prompt. Cut at 200,000 bytes with a note, and `truncated` is `true`. |
| `result` | The value the code returned, as text. Absent when it returned nothing. |
| `stderr` | Errors the code printed, or why a prompt stopped |
| `exitCode` | `0` when it worked. A prompt that could not finish returns `1`. |
| `killed` | `true` when the call ran out of `timeout` |
| `error` | The last line of `stderr` when `exitCode` is not `0` |
| `steps`, `page` | Prompt only: the steps taken and the page it ended on |
| `cdpUrl`, `liveViewUrl`, `interactiveLiveViewUrl` | The session's links |

## Errors

* Code past `timeout`: `killed: true` and `error` `The code ran out of time.`
* The first call right after a session opens can return `503 internalError`. Send it again.
* A session that has ended: `410 notFound`.

A prompt raises the price of the whole session. Run code when you know the steps. To upload a file first, see [Files](https://docs.stophy.dev/browser/files.md).


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