> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST Create a runner run

> Run the browser agent against a frontend or sandbox

```bash theme={null}
POST /runner/runs
```

Starts a runner run from a natural-language prompt. Pass either `start_url` or a ready `sandbox_id`; when `sandbox_id` is provided, Arga uses the sandbox app URL as the run target and records the sandbox attachment in the run artifacts. If the sandbox is not ready, the API returns `409`.

**Request body**

| Field         | Type     | Required    | Description                                                                                  |
| ------------- | -------- | ----------- | -------------------------------------------------------------------------------------------- |
| `prompt`      | `string` | Yes         | Flow to execute, 1-20,000 characters.                                                        |
| `start_url`   | `string` | Conditional | Absolute HTTP(S) URL. Required unless `sandbox_id` is provided or the prompt contains a URL. |
| `sandbox_id`  | `string` | No          | Ready sandbox to run against. The sandbox must belong to the authenticated user.             |
| `test_config` | `object` | No          | Existing TestConfig to replay instead of recording a new flow.                               |