# uip tm perf-scenario load-groups

> Syntax and options for `uip tm perf-scenario load-groups`, which binds test cases to a performance scenario and tunes their load profile.

`uip tm perf-scenario load-groups` manages the load groups bound to a performance scenario. A load group is one test case bound to a scenario with a load profile — virtual users, ramp-up/peak/ramp-down timing, SLO thresholds, and robot type.

This page is part of the [`uip tm perf-scenario`](./uip-test-manager-perf-scenario.md) command group — see that page for scenario lifecycle verbs (`create`, `get`, `list`, `execute`, `stop`, `list-dry-run-reports`) and shared concepts.

## Synopsis

```text
uip tm perf-scenario load-groups add --scenario-key <key> [--project-key <key>] (--test-case-key <key> | --test-case-id <uuid>) --folder-key <uuid> --package-name <name> [--package-version <version>] [--virtual-users <n>] [--ramp-up-minutes <n>] [--peak-minutes <n>] [--ramp-down-minutes <n>] [--delay-minutes <n>] [--max-response-time-ms <ms>] [--max-error-rate <rate>] [--robot-type <type>]
uip tm perf-scenario load-groups update --load-group-id <uuid> --project-key <key> [--virtual-users <n>] [--ramp-up-minutes <n>] [--peak-minutes <n>] [--ramp-down-minutes <n>] [--delay-minutes <n>] [--max-response-time-ms <ms>] [--max-error-rate <rate>] [--multiplexing-factor <n>] [--robot-type <type>] [--enabled <bool>]
uip tm perf-scenario load-groups remove --load-group-id <uuid> --project-key <key>
uip tm perf-scenario load-groups list --project-key <key> --execution-id <uuid> [--query <expr>]
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). Every verb accepts `--log-level <level>` (default `Information`).

:::note
`--project-key` is optional on `add` (derived from the `--scenario-key` prefix when omitted) but a required `.requiredOption()` on `update`, `remove`, and `list`, since those identify their target by a bare UUID with no derivable project prefix.
:::

## uip tm perf-scenario load-groups add

Bind a test case to a scenario as a new load group. Sets dry-run defaults for the load profile — dial them in later with `update` once a dry run passes.

### Options

| Flag | Description |
|---|---|
| `--scenario-key <key>` | **Required.** Scenario object key (for example, `SP1:7`). |
| `--project-key <key>` | Owning project. Optional — derived from the `--scenario-key` prefix when omitted. |
| `--test-case-key <key>` | Test case object key to bind (for example, `SP1:602`). Resolved to its UUID via the API. Provide this or `--test-case-id`. |
| `--test-case-id <uuid>` | Test case UUID to bind directly, skipping the key lookup. Provide this or `--test-case-key`. |
| `--folder-key <uuid>` | **Required.** Orchestrator folder key (must be a GUID). |
| `--package-name <name>` | **Required.** Orchestrator package name containing the automation. |
| `--package-version <version>` | Orchestrator package version. Defaults to the latest published version for the package when omitted (resolved via an Orchestrator lookup). |
| `--virtual-users <n>` | Virtual user count. Defaults to `1`. |
| `--ramp-up-minutes <n>` | Ramp-up duration in minutes. Defaults to `0`. |
| `--peak-minutes <n>` | Peak duration in minutes. Defaults to `1`. |
| `--ramp-down-minutes <n>` | Ramp-down duration in minutes. Defaults to `0`. |
| `--delay-minutes <n>` | Delay before start, in minutes. Defaults to `0`. |
| `--max-response-time-ms <ms>` | Max response time SLO in ms; the server requires at least `100`. Defaults to `100`. |
| `--max-error-rate <rate>` | Max error rate SLO (fraction, for example `0.01` for 1%); the server requires at least `0.0001`. Defaults to `0.0001`. |
| `--robot-type <type>` | Robot type: `standard`, `template`, `elasticRobotPool`, `cloudRobotVm`, `serverless`. Defaults to `standard`. |

### Examples

```bash
# bind by test case key
uip tm perf-scenario load-groups add \
  --scenario-key SP1:7 \
  --test-case-key SP1:602 \
  --folder-key 94821c49-ab85-49cb-94e1-f82c6d8973be \
  --package-name Checkout_Tests \
  --robot-type serverless
```

```bash
# bind by test case id directly (skips the key lookup)
uip tm perf-scenario load-groups add \
  --scenario-key SP1:7 \
  --test-case-id f0b7f77f-482b-0400-a9c4-0b49497eb136 \
  --folder-key 94821c49-ab85-49cb-94e1-f82c6d8973be \
  --package-name Checkout_Tests \
  --package-version 1.0.2
```

### Data shape

```json
{
  "Code": "LoadGroupAdd",
  "Data": {
    "ScenarioKey": "SP1:7",
    "TestCaseKey": "SP1:602",
    "LoadGroupId": "8e322581-0a25-0000-738b-0b49fd936ca1",
    "PackageName": "Checkout_Tests",
    "PackageVersion": "1.0.2",
    "VirtualUsers": 1,
    "Result": "Added"
  }
}
```

## uip tm perf-scenario load-groups update

Update one load group's load profile in place (virtual users, ramp/peak/ramp-down minutes, SLO thresholds, robot type, enabled state). Only the flags you pass change — everything else is preserved. Use this between a passing dry run and a full `performanceTesting` run to dial in the real load profile.

### Options

| Flag | Description |
|---|---|
| `--load-group-id <uuid>` | **Required.** The scenario's load group UUID (the `LoadGroupId` field from [`perf-scenario get`](./uip-test-manager-perf-scenario.md#uip-tm-perf-scenario-get), `execute`, or `add` above — **not** the per-execution id from `list` below). |
| `--project-key <key>` | **Required.** Owning project. |
| `--virtual-users <n>` | New virtual user count. |
| `--ramp-up-minutes <n>` | New ramp-up duration in minutes. |
| `--peak-minutes <n>` | New peak duration in minutes. |
| `--ramp-down-minutes <n>` | New ramp-down duration in minutes. |
| `--delay-minutes <n>` | New delay before start, in minutes. |
| `--max-response-time-ms <ms>` | New max response time SLO in ms (server requires at least `100`). |
| `--max-error-rate <rate>` | New max error rate SLO (server requires at least `0.0001`). |
| `--multiplexing-factor <n>` | Multiplexing factor — the recommended value is emitted at the end of a dry run (`list-dry-run-reports` → `RecommendedMultiplexingFactor`). |
| `--robot-type <type>` | New robot type: `standard`, `template`, `elasticRobotPool`, `cloudRobotVm`, `serverless`. |
| `--enabled <bool>` | Enable (`true`) or disable (`false`) this load group. |

### Example

```bash
uip tm perf-scenario load-groups update \
  --load-group-id 8e322581-0a25-0000-738b-0b49fd936ca1 \
  --project-key SP1 \
  --virtual-users 50 \
  --ramp-up-minutes 2 \
  --peak-minutes 10
```

### Data shape

```json
{
  "Code": "LoadGroupUpdate",
  "Data": {
    "LoadGroupId": "8e322581-0a25-0000-738b-0b49fd936ca1",
    "VirtualUsers": 50,
    "RampUpMinutes": 2,
    "PeakMinutes": 10,
    "RampDownMinutes": 0,
    "DelayMinutes": 0,
    "MaxResponseTimeMs": 100,
    "MaxErrorRate": 0.0001,
    "MultiplexingFactor": null,
    "Enabled": true,
    "RobotType": "standard",
    "Result": "Updated"
  }
}
```

Fields you didn't pass are echoed back at their current (unchanged) value, not omitted — the response reflects the full merged load group, not just the delta.

## uip tm perf-scenario load-groups remove

Remove a load group from a scenario. Detaches the test case and its load profile; the test case itself and any past execution data are left untouched.

### Options

| Flag | Description |
|---|---|
| `--load-group-id <uuid>` | **Required.** The scenario's load group UUID (the `LoadGroupId` field from `perf-scenario get` or `add` above). |
| `--project-key <key>` | **Required.** Owning project. |

### Example

```bash
uip tm perf-scenario load-groups remove \
  --load-group-id 8e322581-0a25-0000-738b-0b49fd936ca1 \
  --project-key SP1
```

### Data shape

```json
{
  "Code": "LoadGroupRemove",
  "Data": {
    "LoadGroupId": "8e322581-0a25-0000-738b-0b49fd936ca1",
    "Result": "Removed"
  }
}
```

This is a hard removal with no confirmation flag — the CLI does not gate it behind `-y`/`--yes`.

## uip tm perf-scenario load-groups list

List the load groups **of one execution** (test case, SUT, virtual users, thresholds, status). This is different from the scenario's own load-group list: use [`perf-scenario get`](./uip-test-manager-perf-scenario.md#uip-tm-perf-scenario-get) to see the load groups configured on the scenario itself.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--execution-id <uuid>` | **Required.** Scenario execution id (the `ExecutionId` from `perf-scenario execute`). |
| `--query <expr>` | jq-style filter applied to the output data. |

### Example

```bash
uip tm perf-scenario load-groups list \
  --project-key DEMO \
  --execution-id 80694766-5a44-0000-0985-0b49fd93832d
```

### Data shape

```json
{
  "Code": "PerfLoadGroupsList",
  "Data": {
    "Data": [
      {
        "Id": "082486b0-8d51-0000-b54a-0b4a1388f850",
        "Status": "Finished"
      }
    ]
  }
}
```

This response is a thin PascalCase pass-through of the underlying SDK payload rather than a purpose-built row shape, so the exact field set can be richer than shown here (test case, SUT, virtual users, thresholds) — inspect a real response or use `--query` to shape it. The `Id` field here is the per-execution load group id that [Execution data](./uip-test-manager-perf-scenario-execution-data.md)'s `http-errors list` and `automation-errors list` expect as `--load-group-id`.

## Related

- [uip tm perf-scenario](./uip-test-manager-perf-scenario.md) — scenario lifecycle and shared concepts.
- [Execution data](./uip-test-manager-perf-scenario-execution-data.md) — inspect a finished or in-progress execution.
- [Reports](./uip-test-manager-perf-scenario-report.md) — render authored reports for an execution or a comparison.
- [testcases](./uip-test-manager-testcases.md) — `link-automation` is what gives a test case the `automationId` that `add` and `perf-scenario list-dry-run-reports` depend on.
- [uip or folders list](./uip-or-folders.md) — source of the `--folder-key` used by `add`.

## See also

- [Test Manager overview](./uip-test-manager.md)