> ## 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. Code costs nothing extra; a prompt bills the session at $0.84 per hour.

`POST /v1/browser/{session_id}/execute` runs `code` or a `prompt` in a session you opened, and answers with what it printed and returned. Run as many calls as you need on one session, then close it.

## Run code

[Open a session](https://docs.stophy.dev/browser/overview) first. In your code, `page` is the session's page, with Playwright-style methods. Every `page` call is asynchronous, so `await` it. This call opens a page, then returns its title and address.

```bash cURL theme={null}
SESSION_ID="<the id your session returned>"
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() };"
  }'
```

```typescript TypeScript theme={null}
const sessionId = "<the id your session returned>";
const response = await fetch(
  `https://api.stophy.dev/v1/browser/${sessionId}/execute`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      code: [
        "await page.goto('https://example.com');",
        "return { title: await page.title(), url: await page.url() };",
      ].join("\n"),
    }),
  },
);
const run = await response.json();
console.log(run.result);
```

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

import requests

session_id = "<the id your session returned>"
response = requests.post(
    f"https://api.stophy.dev/v1/browser/{session_id}/execute",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "code": "await page.goto('https://example.com');\n"
        "return { title: await page.title(), url: await page.url() };"
    },
)
print(response.json()["result"])
```

`result` is the value your code returned, as text. `output` is what it printed.

```json theme={null}
{
  "success": true,
  "output": "",
  "stdout": "",
  "result": "{\"title\":\"Example Domain\",\"url\":\"https://example.com/\"}",
  "stderr": "",
  "exitCode": 0,
  "killed": false,
  "truncated": false,
  "cdpUrl": "wss://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/cdp?token=…",
  "liveViewUrl": "https://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/live#…",
  "interactiveLiveViewUrl": "https://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/live#…",
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "2bbe9943-fdf4-4fd7-97f4-92e999ddb15e"
}
```

The call costs nothing. A failed run still answers `200`, so check `exitCode` and `error` before you trust `result`.

## Choose a language

Send `language` as `node` (the default), `python` or `bash`. Each reads the same page.

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

This Python run returned `exitCode` 0 and the same `result` as the Node run above.

```json theme={null}
{
  "language": "python",
  "code": "page.goto('https://example.com')\nresult = {'title': page.title(), 'url': page.url}"
}
```

## Run a prompt

Send `prompt` instead of `code` to say what you want in plain words. Stophy clicks and types on the page for you, up to 50 steps, and answers in words.

```bash cURL theme={null}
SESSION_ID="<the id your session returned>"
curl -X POST https://api.stophy.dev/v1/browser/$SESSION_ID/execute \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Open https://example.com, then click the link on the page and tell me the title of the page it opens."
  }'
```

```typescript TypeScript theme={null}
const sessionId = "<the id your session returned>";
const response = await fetch(
  `https://api.stophy.dev/v1/browser/${sessionId}/execute`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt:
        "Open https://example.com, then click the link on the page and tell me the title of the page it opens.",
    }),
  },
);
const run = await response.json();
console.log(run.result);
console.log(run.steps);
```

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

import requests

session_id = "<the id your session returned>"
response = requests.post(
    f"https://api.stophy.dev/v1/browser/{session_id}/execute",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "prompt": "Open https://example.com, then click the link on the page "
        "and tell me the title of the page it opens."
    },
)
run = response.json()
print(run["result"])
print(run["steps"])
```

This real run took about 13 seconds. The links are cut.

```json theme={null}
{
  "success": true,
  "output": "The link on example.com ('Learn more') opened https://www.iana.org/help/example-domains, and the title of that page is \"Example Domains\".",
  "result": "The link on example.com ('Learn more') opened https://www.iana.org/help/example-domains, and the title of that page is \"Example Domains\".",
  "stderr": "",
  "exitCode": 0,
  "killed": false,
  "truncated": false,
  "steps": [
    "open https://example.com",
    "click link \"Learn more\""
  ],
  "page": {
    "url": "https://www.iana.org/help/example-domains",
    "title": "Example Domains"
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "c03559db-7817-46d6-98c5-e10643d88269"
}
```

`result` and `output` hold the answer. `steps` lists what was done, and `page` is where the session ended up. When the prompt could not be finished, `exitCode` is `1` and `stderr` says why.

## Options

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

| Field | Type | Default | Effect |
| - | - | - | - |
| `code` | `string` | none | Code to run, 1 to 200,000 characters. |
| `prompt` | `string` | none | What to do, in plain words, 1 to 10,000 characters. Ignored when `code` is also sent. |
| `language` | `string` | `node` | `node`, `python` or `bash`. Used with `code`. |
| `timeout` | `number` | `30` for code, `120` for a prompt | Seconds the call may run, 1 to 300. The session's own end still stops it. |

## Read the response

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

## Price

A call costs nothing. What changes is the session's price: a session is $0.06 per hour open, and once a prompt has run it is $0.84 per hour for its whole time. Code never raises the price. Traffic is billed as usual, per GB. A session that opened, ran one prompt and closed after 27 seconds cost $0.022: one minute of browser time at the prompt price, $0.014, and \$0.008 for 1.3 MB of traffic. See [Browser sessions](https://docs.stophy.dev/browser/overview#price).

## Limits and errors

* The first call right after a session opens can fail with `503 internalError` and the message `We couldn't complete your request. Try again shortly.` It is retryable: send it again.
* Code that runs past `timeout` returns `killed: true` and `error` `The code ran out of time.`
* A session that has ended returns `410 notFound` with `This browser session has ended.`
* `url` and `zeroDataRetention` are not accepted on this call. Open the page with `page.goto` in your code, and set zero data retention when you open the session.

## Related

* [Browser sessions](https://docs.stophy.dev/browser/overview) opens and closes the session this call runs in.
* [Files](https://docs.stophy.dev/browser/files.md) puts a file in the session for a file field to use.
* [Tasks](https://docs.stophy.dev/browser/tasks.md) runs a goal on a public site without a session of your own.
* [Browser actions](https://docs.stophy.dev/scrape/browser-actions.md) run steps on a page during one scrape.


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