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

# Runs API

> Trigger flow execution, poll for results, retrieve run results, and terminate in-progress runs programmatically

All requests require an API key in the `X-API-Key` header. See [API Reference](/docs/api-reference.md) for authentication details.

***

## List Devices

Discover the device and OS permutations that can be requested for cloud runs.

> [!NOTE]
>
> **GET** `/api/v1/devices` — Returns `200 OK`

Optional query parameters are `platform` (`android` or `ios`) and `physical`
(`true` or `false`). Each model appears once with its supported `os_versions`.

```bash theme={null}
curl "https://backend.usebugradar.com/api/v1/devices?physical=false" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response (abbreviated):

```json theme={null}
{
  "devices": [
    {
      "platform": "android",
      "physical": false,
      "model": "Pixel 10 Pro",
      "os_versions": ["17", "16"]
    },
    {
      "platform": "ios",
      "physical": false,
      "model": "iPhone 18 Pro",
      "os_versions": ["27.0"],
      "fast_os_versions": ["27.0"]
    },
    ...
  ]
}
```

Choose a model and one of its `os_versions`. For iOS simulators,
`fast_os_versions` identifies choices with an optimized startup path. Every
returned combination is supported.

***

## Run Flows

Trigger flow execution. Returns a `batch_id` to poll via [Run Status](#run-status) and a `batch_url` to view or share the entire batch in the dashboard.

> [!NOTE]
>
> **POST** `/api/v1/flows/run` — Returns `200 OK`

### Request Body

**bundle\_id** `string`

App bundle identifier (mobile). Required for mobile runs. If no app has this bundle ID and platform yet, the request returns `404` with the response header `X-BugRadar-Error: build_not_found`.

**platform** `string`

`ios` or `android`. Required with `bundle_id`.

**app\_id** `string`

Web app identifier. Required for web runs. For mobile runs, optionally pass it with `bundle_id` and `platform` to pick the app that was [uploaded with that `app_id`](/docs/api-ci#start-upload); omit it to run the app identified by bundle ID alone. Passing your bundle ID as `app_id` is the same as leaving it out.

**app\_build\_id** `string`

Optional. Pin the run to a specific build (UUID) instead of the app's active build — useful for testing a particular CI/CD build. The build must belong to the resolved app, otherwise the request returns `404`. To find the build for a commit, see [List App Builds](/docs/api-apps.md#list-app-builds).

A build uploaded from a branch other than your default branch may run your [code-managed flows](/docs/code-managed-flows.md) as they are at its commit. See [Branch builds run at their commit](#branch-builds-run-at-their-commit).

**ref** `string`

Optional. Run your [code-managed flows](/docs/code-managed-flows.md) as they are on a branch or at a commit, instead of as they are on your default branch. Pass a branch name or a full 40-character commit SHA, together with `repo_full_name`, and select with `flow_ids`, `suite_ids`, `labels`, `folder_ids`, or `folder_paths`. Flows and suites stored in that repo use their files at that commit. Flows and suites created in the dashboard run as saved.

Without `app_build_id`, the build comes from the ref: the build uploaded for that commit, or for a branch, its newest build. If no build matches, the request returns `404`; the app's active build is never used. That `404` carries the response header `X-BugRadar-Error: build_not_found`. To wait while another CI job uploads the build, retry on that header with a time limit; the GitHub Action waits 10 minutes. If the header never clears, check `bundle_id`, `platform`, and `app_id` for typos. BugRadar reads the ref from GitHub, so the repo must be connected through the BugRadar GitHub App.

`resolve_suite_context`, `suite_overrides`, and `parallelize_flows` work the same with `ref`, except with `folder_paths` (see below). For a flow stored in the repo, `suite_overrides` must name a suite stored in the same repo that contains the flow at that commit; otherwise the request returns `400`.

**repo\_full\_name** `string`

Repository in `owner/repo` format, exactly as connected to BugRadar. Required with `ref`. Returns `404` if the repo isn't connected to your organization.

**suite\_ids** `string[]`

Suite UUIDs to run. At least one of `suite_ids`, `flow_ids`, `labels`, `folder_ids`, or, with `ref`, `folder_paths` is required.

**parallelize\_flows** `boolean`

Optional suite execution override. Explicit `true` or `false` takes precedence
over each suite's saved **Run flows in parallel** setting. Omit it or send
`null` to use the saved suite setting.

**flow\_ids** `string[]`

Flow UUIDs to run. At least one of `suite_ids`, `flow_ids`, `labels`, `folder_ids`, or, with `ref`, `folder_paths` is required.

When provided, suite auth instructions and suite-scoped variables are resolved automatically unless `resolve_suite_context` is set to `false`. See [Suite context for individual flows](#suite-context-for-individual-flows) below.

**labels** `string[]`

Label **names** to run (e.g. `["smoke", "checkout"]`). Runs the union of the suites and flows carrying any of these labels; a flow already covered by a matched suite runs once. Returns `400` if nothing matches. See [Run by Label](/docs/api-labels.md#run-by-label).

**folder\_ids** `string[]`

[Folder](/docs/flows.md#running-a-folder) UUIDs to run. Copy one from the folder's
**⋯** menu on the Flows page (**Copy folder ID**), or list them with the MCP
`folders_list` tool.

Runs every suite and flow beneath each folder, at any depth. Each suite runs
in full, including flows it holds that are filed in other folders. A flow
that belongs to a suite runs only as part of that suite, so the folder skips
it when the suite is elsewhere. The folder also skips a flow that `flow_ids`
lists, so that flow runs once. Every other flow runs on its own, without a
suite's auth instructions or suite-scoped variables.

The response and [Run Status](#run-status) include `name`: the folder's name,
or for several folders the first three names followed by "and N more".

* With `ref`, a folder from that repo runs as it is at the ref, the same as
  `folder_paths` below. A folder from a different repo returns `400`.
* With a branch build's `app_build_id`, a folder from that repo can run as it
  is at the build's commit. See [Branch builds run at their commit](#branch-builds-run-at-their-commit).
* A broken file beneath the folder at that commit: `400` naming the file.
* Unknown folder: `404` with `Folder not found: <ids>`.
* Nothing to run in the folders and nothing else selected: `404`. When every flow there belongs to a suite outside those folders, the message says so.
* `503` with `Running folders is not available yet. Try again in a few minutes.` while BugRadar finishes an update. Retry later.

**folder\_paths** `string[]`

Folders to run by path below `.BugRadar/`, for example `Auth/Onboarding`.
Requires `ref` and `repo_full_name`. Can't be combined with `all`,
`flow_ids`, `suite_ids`, `labels`, `folder_ids`, `suite_overrides`, or
`resolve_suite_context`.

Runs every suite and flow beneath each folder as they are at the ref, the
same way `folder_ids` does. Flows and suites created in the dashboard and
filed in the folder also run, as saved. Use it for a folder that exists only
on a branch.

* Unknown path: `404` with `folder '<path>' does not exist at the ref`.
* Invalid path: `400` with `folder path '<path>' is not valid. Use a path below .BugRadar/, for example Auth/Onboarding.`
* A broken file beneath the folder: `400` naming the file.
* A suite beneath the folder that wouldn't run all of its tests: `400` with `suite '<key>' would not run all of its tests: <reason>`.
* Nothing to run in the folders and nothing else selected: `404` with `No active suites or flows are in the selected folder(s)`.
* Every flow in the folders belongs to a suite outside them, and nothing else is selected: `404` with `Each flow in the selected folder(s) belongs to a suite outside those folders. Run that suite instead.`

**resolve\_suite\_context** `boolean` (default: true)

When running individual flows via `flow_ids`, whether to look up the flow's suite and run auth instructions first. Defaults to `true`. Set to `false` to run the flow without suite auth or suite-scoped variables — useful for unauthenticated smoke tests or flows that handle login themselves.

**suite\_overrides** `object`

Optional. When a flow belongs to multiple suites, pass a JSON object mapping each ambiguous `flow_id` to the `suite_id` whose auth instructions and variables should be used, e.g. `{"<flow_id>": "<suite_id>"}`. Ignored when `resolve_suite_context` is `false`.

**variables** `string | object`

Key-value variables to attach to the build being run (the pinned `app_build_id` if provided, otherwise the active build) and inject into flow instructions via `${env:KEY}`. Accepts a string (`"KEY1=VALUE1,KEY2=VALUE2"`) or a JSON object (`{"KEY1": "VALUE1"}`). See [Build Variables](/docs/variables.md#build-variables).

**web\_browser** `string`

For web apps: which browser to run the flow in. One of:

* `chrome` — real Google Chrome (default). Includes proprietary codecs (H.264, AAC) and Widevine DRM. Use this unless you have a specific reason to pick another browser.
* `chromium` — open-source Chromium. No proprietary codecs, no DRM, deterministic and vendor-neutral.
* `firefox` — Mozilla Firefox stable.
* `edge` — Microsoft Edge stable.

Aliases accepted: `Chrome` / `Google Chrome` → `chrome`; `msedge` / `Microsoft Edge` → `edge`. Ignored for mobile runs.

**location** `string`

Optional. Two-letter ISO country code, such as `MX`. The run's browser or device traffic leaves from that country. Web runs and Android emulator runs only: not iOS, physical devices, or local devices. See [Proxy location](/docs/run-location.md).

**locale** `string`

Optional. Language and region the app opens in, such as `de-DE`, or a bare language such as `de`. Works on every platform and device. See [Language & region](/docs/language-and-region.md).

**dependencies** `array`

Optional for web apps. Override the app's default Chrome extensions for this
run. Each entry can be an extension app UUID or an object that pins an exact
build:

```json theme={null}
[
  "extension-app-uuid",
  {
    "app_id": "another-extension-app-uuid",
    "app_build_id": "extension-build-uuid"
  }
]
```

Omit this field to inherit the web app's attached defaults. Pass `[]` to run
without extensions. When extensions load, `web_browser` defaults to `chrome`;
`chrome` and `chromium` run as requested, `edge` runs in Chromium, and
`firefox` is rejected with a `400` because Chrome extensions are not
supported there.

**device** `object`

Optional for mobile apps. Selects the execution target and, when specified,
the exact supported device permutation. Fields are `physical` (defaults to
`false`), `model` (for example,
`"Pixel 10 Pro"`), and `os_version` (for example, `"17"`). Set `model` or
`os_version` to `"latest"` to explicitly request rolling resolution for that
field. This lets you pin one while keeping the other current. For a real
device, `match` sets how strictly each pinned field must match when the
device is busy: `{"model": "exact"}`, `{"os_version": "exact"}`, or both.
Fields default to `"similar"`, which allows the closest free device. Use
[List Devices](#list-devices) to discover valid combinations. Omit it to use
the recommended default. A request with no supported match fails fast with a
clear error. For an iOS simulator, use `physical: false` with a listed iPhone
or iPad model and iOS version. For a real iOS device, use `physical: true`
and an `.ipa` build.

**devices** `object[]`

Use instead of `device` to choose each device of a two-device flow. Pass
exactly two entries in Device 1, Device 2 order. A run can mix one-device and
two-device flows: one-device flows use the first entry, and a two-device flow
run with `device` (or with neither field) uses that selection for both
devices. Both entries must select virtual devices
(`physical: false`) or both must select real devices (`physical: true`). Model
and OS can be exact, `"latest"`, or omitted for rolling resolution. Each
real-device entry also takes `match` (for example `{"model": "exact"}`). Both
devices use the run's app build and platform.

```json theme={null}
[
  { "physical": true, "model": "iPhone 17 Pro", "os_version": "26" },
  { "physical": true, "model": "iPhone 16 Pro", "os_version": "18" }
]
```

See [Multi-Device Testing](/docs/multi-device-testing.md) for a complete setup and
execution guide.

For example, keep the model and OS current on every run:

```json theme={null}
{
  "device": {
    "physical": false,
    "model": "latest",
    "os_version": "latest"
  }
}
```

### Suite context for individual flows

When you trigger a single flow via `flow_ids`, BugRadar resolves the suite it belongs to and runs that suite's **Auth Instructions** first — the same behavior as running the flow manually from the dashboard.

```bash theme={null}
# Runs auth instructions first, then the flow (default)
curl -X POST https://backend.usebugradar.com/api/v1/flows/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "flow_ids": ["660e8400-e29b-41d4-a716-446655440001"]
  }'

# Skip suite auth — run only the flow instructions
curl -X POST https://backend.usebugradar.com/api/v1/flows/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "flow_ids": ["660e8400-e29b-41d4-a716-446655440001"],
    "resolve_suite_context": false
  }'
```

> [!TIP]
>
> If a flow belongs to multiple suites, the request returns `400` unless you pass `suite_overrides` mapping that flow to one of its suite UUIDs, e.g. `{"660e8400-e29b-41d4-a716-446655440001": "550e8400-e29b-41d4-a716-446655440000"}`.

### Branch builds run at their commit

When you send a branch build's `app_build_id` with `flow_ids`, `suite_ids`, `labels`, or `folder_ids` and no `ref`, BugRadar can run your code-managed flows as they are at the build's commit — as if you had passed that commit as `ref`. A pull request's CI then tests the pull request's flow changes against the pull request's build. This applies to any branch other than your default branch, including long-lived ones like `develop` or `release/*`, not only pull request branches. The build you named still runs.

This happens when all of these hold:

* The build was uploaded with a full 40-character `commit_sha`, a `branch_name`, and a `repo_full_name` (see [Confirm Upload](/docs/api-ci.md#confirm-upload)).
* That GitHub repo is connected to your organization through an active BugRadar GitHub App installation, with code-managed flows turned on.
* `branch_name` isn't the repo's default branch.
* At least one selected flow, suite, or folder is stored in that repo, and none is stored in a different repo.
* Unless `resolve_suite_context` is `false`: no selected flow from the repo belongs to a suite created in the dashboard, and each `suite_overrides` entry names a selected flow and, for a flow from the repo, a suite from the same repo.

Otherwise the run uses the flows from your default branch.

This changes what existing CI jobs that send a branch build's `app_build_id` run. To keep running your default branch's flows, pass `repo_full_name` and set `ref` to your default branch.

If GitHub doesn't know the commit, or the repo is too large to read, the run uses the flows from your default branch. If GitHub is unavailable, the request fails with an error you can retry. If the build's commit deletes, renames, or breaks the file of a flow or suite you selected, the request also fails; the error names the flow's key or the file.

When the run uses the build's commit, every flow in it, including ones created in the dashboard, gets the repository context (`.BugRadar/BugRadar.md`) at that commit. The response includes `inferred_ref`:

```json theme={null}
"inferred_ref": {
  "repo_full_name": "myorg/myrepo",
  "commit_sha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
  "branch": "feature/new-login"
}
```

> [!NOTE]
>
> A flow added in a pull request exists only on that branch until it merges. If every flow you select is like that and you select no suite, a request that doesn't run at a commit returns `400` naming the flow and, when BugRadar knows it, its pull request. Pass `ref` with the branch's head commit to run it.

### Example Request

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/flows/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_id": "com.company.app",
    "platform": "android",
    "suite_ids": ["550e8400-e29b-41d4-a716-446655440000"],
    "variables": "PR_NUMBER=42,BRANCH=feature/login"
  }'
```

### Example: Run with Chrome extensions

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/flows/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-web-app-uuid",
    "flow_ids": ["660e8400-e29b-41d4-a716-446655440001"],
    "dependencies": [
      "extension-app-uuid",
      {
        "app_id": "wallet-extension-app-uuid",
        "app_build_id": "wallet-extension-build-uuid"
      }
    ]
  }'
```

All dependency apps and pinned builds must belong to the same organization as
the primary web app. Duplicate app IDs are loaded once; conflicting build pins
return `400`.

### Example Response

```json theme={null}
{
  "status": "success",
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "batch_url": "https://usebugradar.com/runs/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "flow_group_run_ids": ["f1a2b3c4-d5e6-7890-abcd-ef1234567890"],
  "flow_run_count": 5,
  "snoozed_flow_count": 1
}
```

`flow_run_count` counts the flows that will run. `snoozed_flow_count` counts the [snoozed](/docs/flows.md#snoozing-a-test) flows the run skipped. A request that names exactly one flow in `flow_ids` or `flow_keys`, with no suite, label, or folder selector, runs it even when it is snoozed.

A run with `folder_ids` or `folder_paths` also returns the run's `name`, for example `"name": "Checkout"`. Other runs leave `name` out here, and [Run Status](#run-status) returns it as `null`, with one exception. A branch run from [MCP](/docs/mcp-setup.md) that is attached to the branch's open pull request also has a name in Run Status, for example `"name": "suite 'Smoke' on feature/login"`.

***

## Run Status

Poll execution status for a batch triggered by [Run Flows](#run-flows).

> [!NOTE]
>
> **GET** `/api/v1/runs/status` — Returns `200 OK`

### Query Parameters

**batch\_id** `string` *required*

The `batch_id` from `/api/v1/flows/run`.

### Example Request

```bash theme={null}
curl -X GET "https://backend.usebugradar.com/api/v1/runs/status?batch_id=BATCH_ID" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "batch_url": "https://usebugradar.com/runs/batches/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Checkout",
  "is_complete": true,
  "timestamp": "2025-01-31T12:34:56.789Z",
  "app": {
    "id": "com.company.app",
    "bundle_id": "com.company.app",
    "name": "My App",
    "platform": "android",
    "url": "https://storage.example.com/builds/app.apk"
  },
  "git": {
    "commit_sha": "abc123",
    "branch": "main"
  },
  "summary": {
    "total_groups": 2,
    "passed_groups": 1,
    "failed_groups": 1,
    "total_flows": 10,
    "passed_flows": 8,
    "failed_flows": 2,
    "error_flows": 0,
    "terminated_flows": 0,
    "skipped_flows": 0,
    "snoozed_flows": 1
  },
  "run_groups": [
    {
      "name": "Login Suite",
      "status": "passed",
      "url": "https://usebugradar.com/runs/groups/group-uuid-1",
      "source": "ci",
      "actor": { "id": "770e8400-e29b-41d4-a716-446655440077", "name": "CI Key", "type": "api_key" },
      "dependency_app_build_ids": ["extension-build-uuid"],
      "runs": [
        {
          "id": "run-uuid-1",
          "name": "Login with valid credentials",
          "status": "passed",
          "url": "https://usebugradar.com/runs/flow/run-uuid-1",
          "summary": "Successfully logged in and verified the dashboard loaded."
        }
      ],
      "snoozed_runs": [
        {
          "id": "run-uuid-3",
          "name": "Login with SSO",
          "status": "snoozed",
          "url": "https://usebugradar.com/runs/flow/run-uuid-3"
        }
      ]
    },
    {
      "name": "Checkout Suite",
      "status": "failed",
      "url": "https://usebugradar.com/runs/groups/group-uuid-2",
      "source": "schedule",
      "actor": { "id": "f8d8fb05-6292-4daa-9bf4-b0cc3b40a366", "name": "BugRadar", "type": "system" },
      "dependency_app_build_ids": [],
      "runs": [
        {
          "id": "run-uuid-2",
          "name": "Checkout with expired card",
          "status": "failed",
          "url": "https://usebugradar.com/runs/flow/run-uuid-2"
        }
      ],
      "snoozed_runs": []
    }
  ]
}
```

`app.id` is the app's ID: the bundle ID for a mobile app, or its custom `app_id` when it was [uploaded with one](/docs/api-ci.md#start-upload). `app.bundle_id` is always the bundle ID, so use it if you match on bundle ID. For a web app both hold the app ID.

Each run group also includes:

* `status`: common values include `creating`, `pending`, `queued`, `running`, `reviewing`, `verifying`, `terminating`, `terminated`, `passed`, `failed`, `error`, and `skipped`. Treat this list as non-exhaustive. Poll until a terminal status rather than switching on every value.
* `runs[].status`: each run's own status. It takes the same values, plus `installing`: the run's device is ready and its app is installing. The run then becomes `running` when its test starts, or goes back to `queued` if the install stops first. The group's own `status` stays `queued` or `running` meanwhile.
* `source`: how it was triggered (`ci`, `dashboard`, `schedule`, or `mcp`)
* `actor`: who triggered it, as `{ id, name, type }`, where `type` is `user`, `system`, or `api_key`
* `dependency_app_build_ids`: exact Chrome extension build UUIDs loaded for the group
* `snoozed_runs`: [snoozed](/docs/flows.md#snoozing-a-test) flows the group skipped, each with `status` `snoozed`. They never appear in `runs`.

`summary.snoozed_flows` counts snoozed flows. No other count includes them. A group whose flows are all snoozed has status `passed` and an empty `runs`.

Runs triggered with an API key (this endpoint, MCP, CI) are attributed to the key itself: `type` is `api_key`, `id` is the key's ID, and `name` is the key's name from your dashboard. `source` and `actor` may be `null` for older runs.

***

## Get Run Results

Get full details of a run, including metadata, summary, the raw run recording URL, and all actions with screenshot URLs. Use the `id` from individual runs in the [Run Status](#run-status) response.

> [!NOTE]
>
> **GET** `/api/v1/runs/{run_id}` — Returns `200 OK`

### Path Parameters

**run\_id** `string` *required*

UUID of the run. Available in the `runs[].id` and `snoozed_runs[].id` fields from [Run Status](#run-status).

A run whose flow was [snoozed](/docs/flows.md#snoozing-a-test) and skipped has `status` `snoozed`. A run whose device is ready while its app installs has `status` `installing`.

### Example Request

```bash theme={null}
curl -X GET "https://backend.usebugradar.com/api/v1/runs/run-uuid-1" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "run_id": "run-uuid-1",
  "flow_name": "Login with valid credentials",
  "platform": "web",
  "status": "passed",
  "started_at": "2025-01-31T12:34:50.000000+00:00",
  "completed_at": "2025-01-31T12:35:01.000000+00:00",
  "source": "ci",
  "actor": { "id": "770e8400-e29b-41d4-a716-446655440077", "name": "CI Key", "type": "api_key" },
  "dependency_app_build_ids": ["extension-build-uuid"],
  "summary": "Successfully logged in and verified the dashboard loaded.",
  "issues": [
    {
      "type": "ux",
      "severity": "minor",
      "title": "No loading indicator on login",
      "description": "After tapping 'Sign In', there is no visual loading state before the dashboard appears.",
      "actions": [4,5]
    }
  ],
  "url": "https://usebugradar.com/runs/flow/run-uuid-1",
  "recording_url": "https://storage.example.com/recordings/run-uuid-1.mp4",
  "performance_data_url": "https://storage.example.com/perf/run-uuid-1.json?token=...",
  "device_log_url": "https://storage.example.com/logs/run-uuid-1/device.log?token=...",
  "network_log_url": "https://storage.example.com/logs/run-uuid-1/network.jsonl?token=...",
  "actions": [
    {
      "id": "action-uuid-1",
      "position": 1,
      "type": "tap",
      "status": "passed",
      "description": "Tap the 'Sign In' button",
      "value": null,
      "screenshot_url": "https://storage-path/screenshot1.png",
      "annotated_screenshot_url": "https://example.com/screenshot1_annotated.png",
      "executed_at": "2025-01-31T12:34:56.789000+00:00"
    },
    {
      "id": "action-uuid-2",
      "position": 2,
      "type": "send_keys",
      "status": "passed",
      "description": "Type email into the email field",
      "value": "user@example.com",
      "screenshot_url": "https://storage-path/screenshot2.png",
      "annotated_screenshot_url": "https://example.com/screenshot2_annotated.png",
      "executed_at": "2025-01-31T12:34:58.789000+00:00"
    },
    {
      "id": "action-uuid-3",
      "position": 3,
      "type": "pass",
      "status": "passed",
      "description": "Login completed successfully — dashboard is visible",
      "value": null,
      "screenshot_url": "https://storage-path/screenshot3.png",
      "annotated_screenshot_url": null,
      "executed_at": "2025-01-31T12:35:00.789000+00:00"
    }
  ],
  "hook_runs": [
    {
      "hook_type": "action",
      "slug": "verify-offer-sent",
      "name": "Verify Offer Sent",
      "status": "passed",
      "source": "repo",
      "hook_id": null,
      "script_sha256": "9f2c…",
      "frozen": true
    }
  ]
}
```

### Hook runs

**hook\_runs** `object[]`

Each setup, teardown and by-name (`${hooks:Name}`) hook the run executed, oldest first. Suite-level hooks aren't included.

* `hook_type` — `setup`, `teardown`, or `action` (called by name)
* `slug` — the hook's slug
* `name` — the hook's display name
* `status` — `running`, `passed`, `failed`, or `error` (the hook couldn't run, for example a configuration problem)
* `source` — `repo` (a hook file at the run's commit, or your working copy on `--local` or `--cloud` runs) or `database` (a hook stored in BugRadar — added in the dashboard or synced from your default branch)
* `hook_id` — the stored hook's ID; `null` for a repo file
* `script_sha256` — SHA-256 of the hook body that ran; `null` for built-in hooks
* `frozen` — `true` when the body was captured at run start. When `false`, `script_sha256` hashes the hook's current saved body, which may differ from what ran if the hook was edited since.

On older frozen runs, `source`, `hook_id` and `script_sha256` may be `null`. They are also `null`, along with `name`, when two hooks of the same type in one run share a slug.

### Artifact URLs

**dependency\_app\_build\_ids** `string[]`

Exact Chrome extension build UUIDs loaded for this run.

**devices** `object[]`

Per-device metadata and artifact URLs for a two-device run, ordered by
`device_index`. Each entry includes model and OS metadata and that
device's recording, performance, device-log, and network-log URLs.
Single-device runs return an empty array and continue to use the top-level
artifact fields below.

**recording\_url** `string | null`

Public URL for the raw, unannotated MP4 recording of the run. `null` when the run did not produce a recording.

**performance\_data\_url** `string | null`

Time-series performance metrics (memory, CPU, web vitals) as JSON.

**device\_log\_url** `string | null`

Device log (Android `logcat` / iOS syslog) or browser console log (web), as plain text or JSONL.

**network\_log\_url** `string | null`

HTTP requests captured during the run, as JSONL — one entry per request with `method`, `url`, `status`, `resource_type`, `duration_ms`, `response_size`, etc. Failed requests (DNS, abort, CORS) appear with `status: 0` and an `error` string.

Produced for **web** and **iOS** runs (iOS from the cloud simulator; apps that pin their TLS certificate aren't captured). `null` when no traffic was captured. See [Network Traffic](/docs/network-traffic.md).

Any of these may be `null` if the artifact wasn't produced for that run. `performance_data_url`, `device_log_url` and `network_log_url`, here and in `devices`, are signed links that expire after 24 hours. Fetch the run again for fresh ones.

Actions from a two-device run include `device_index` (`1` or `2`).

***

## Terminate Run

Terminate an in-progress flow group run. `run_id` may be a flow group run ID from [Run Flows](#run-flows) (`flow_group_run_ids`) or a flow run ID from [Run Status](#run-status) / [Get Run Results](#get-run-results).

> [!WARNING]
>
> Passing a flow run ID terminates the **entire parent group**, including every sibling flow in that suite or batch, not just the one run.

> [!NOTE]
>
> **POST** `/api/v1/runs/terminate` returns `200 OK`

### Request Body

**run\_id** `string` *required*

UUID of a flow group run or a flow run.

Pending runs are terminated immediately. Queued or running groups are marked `terminating`. Already-terminal runs return `action: "none"`. Unknown or other-organization IDs return `404`.

To watch termination finish, reuse the `batch_id` from [Run Flows](#run-flows) and poll [Run Status](#run-status) until that group's `status` is terminal (`terminated`, `skipped`, `passed`, `failed`, or `error`). The terminate response does not include `batch_id`. You can also poll [Get Run Results](#get-run-results) with the original flow run ID until that flow reaches any terminal status. Children that never started may be `skipped` rather than `terminated`.

### Example Request

```bash theme={null}
curl -X POST https://backend.usebugradar.com/api/v1/runs/terminate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "660e8400-e29b-41d4-a716-446655440001"
  }'
```

This example passes a **flow run** ID. The response echoes that ID in `run_id` and the resolved parent group in `flow_group_run_id`.

### Example Response

```json theme={null}
{
  "run_id": "660e8400-e29b-41d4-a716-446655440001",
  "flow_group_run_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "status": "terminating",
  "message": "Marked for termination (worker will finalize)",
  "action": "terminating"
}
```

**run\_id** `string`

The `run_id` you sent (flow group run or flow run).

**flow\_group\_run\_id** `string`

The parent group that was actually terminated. Same as `run_id` when you passed a group ID.

**status** `string`

Current group status after the request. Typically `terminated` or `terminating`. When `action` is `none`, this is the group's existing terminal status (`passed`, `failed`, `error`, `terminated`, or `skipped`).

**message** `string`

Human-readable outcome, for example `"Marked for termination (worker will finalize)"` or `"Already in terminal state"`.

**action** `string`

`terminated` (pending run stopped immediately), `terminating` (worker will finalize), or `none` (already terminal).

***

## Polling

Poll `/api/v1/runs/status` every 10-15 seconds until `is_complete` is `true`.

```bash theme={null}
while true; do
  RESPONSE=$(curl -s "https://backend.usebugradar.com/api/v1/runs/status?batch_id=$BATCH_ID" \
    -H "X-API-Key: YOUR_API_KEY")

  if [ "$(echo "$RESPONSE" | jq -r '.is_complete')" = "true" ]; then
    echo "$RESPONSE" | jq '.summary'
    break
  fi

  sleep 15
done
```


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