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

# Discovery Runs

> Give the agent a goal and let it explore your web or mobile app on its own, with no saved steps and no pull request, reporting every bug it finds.

A discovery run lets the agent loose on your app. You supply only a goal, such as `Explore the checkout flow and find bugs`, and the agent decides what to test as it goes. There is no saved test, no step list, and no pull request. Use it to surface bugs your authored tests never anticipated.

## When to use it

| Mode                                           | Steps come from                         | Best for                                               |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------------------ |
| Saved tests                                    | Steps you write and save                | Flows that must be verified the same way every time    |
| [Exploration agent](/run/pr-exploration-agent) | A plan written from each pull request   | Testing what a specific code change affects            |
| Discovery run                                  | The agent, step by step, from your goal | Open-ended bug hunting across an area or the whole app |

A discovery run does not save a test. When it finds a flow worth keeping, turn it into a saved test so it runs on every change.

## Start from the dashboard

1. Open your project and select **Tests**.
2. Click **Add test** and switch to the **Discovery run** tab.
3. Describe the goal. Leave it empty to use the default goal, `Explore the app and find bugs`. A typed goal must be at least 10 characters.
4. On mobile projects, pick the device and the uploaded app to explore.
5. Submit. The dialog closes and the live run opens in the **Results** tab.

Web projects explore the project's URL. Mobile projects need an uploaded app before a run can start.

## How the agent explores

* The agent opens one exploration step at a time, gives it a title, and reports each bug it finds.
* A failed step does not stop the run. A dead end is recorded as a finding and the agent keeps exploring.
* The run ends when the agent decides the goal is covered, or when it hits a limit.
* [Agent instructions](/run/agent-instructions), [project memory](/guides/project-memory), and your project's [credentials](/auth/credentials) apply to discovery runs like any other run.

### Limits

| Limit                    | Value                                        |
| ------------------------ | -------------------------------------------- |
| Exploration steps        | Up to 12 per run                             |
| Run duration             | Up to 15 minutes                             |
| Consecutive failed steps | After 3 in a row, the agent wraps up the run |
| Goal length              | 2000 characters maximum                      |

Each discovery run counts as one run toward your usage.

## Read the result

Discovery runs use a different verdict than saved tests:

| Outcome   | Meaning                                                                    |
| --------- | -------------------------------------------------------------------------- |
| `PASSED`  | The agent explored and reported no blocking bugs                           |
| `FAILED`  | The agent reported at least one blocking bug                               |
| `BLOCKED` | No step succeeded and every failure was caused by the environment or setup |

The run description summarizes how many steps were explored, how many passed and failed, how many issues were found, and the agent's closing assessment. Reported bugs also appear in the project's [Issues](/run/issues) tab. See [Understand Results](/run/results) for steps, screenshots, and videos.

## Start from the API

```bash theme={"theme":"vesper"}
curl -X POST https://tester.army/api/v1/projects/$PROJECT_ID/discovery-runs \
  -H "Authorization: Bearer $TESTERARMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Explore the settings area and find bugs"}'
```

| Field         | Required | Description                                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------------------- |
| `goal`        | Yes      | What to explore, 8 to 2000 characters                                                        |
| `targetUrl`   | No       | URL to explore instead of the project's URL. Web only                                        |
| `platform`    | No       | `web`, `ios`, or `android`. Defaults to `web` for web projects and `ios` for mobile projects |
| `appId`       | No       | Uploaded app to explore. Defaults to the project's latest app for the platform. Mobile only  |
| `deviceModel` | No       | Device variant within the platform, such as `ipad`. Omit for the default phone-sized device  |

The response is `202` with `status: "queued"`, the `runId`, `projectId`, and resolved `platform`. Poll `GET /api/v1/runs/{id}` for the outcome. See the [API reference](/api-reference/introduction) and [API keys](/auth/api-keys).

## Start from MCP

Coding agents connected through the [MCP server](/cli/mcp) can call `run_discovery` with a `projectId`, a `goal`, and an optional `targetUrl`, then poll `get_run` for the verdict. Mobile projects explore the latest uploaded app.