# List rolling groups

Source: https://www.jawsdeploy.net/rest-api/rolling-groups-list | Section: Rolling Groups

List a project's rolling groups with their settings and member step ids.

`GET /api/project/rolling-groups`

Returns every rolling group in the project. A rolling group is a run of consecutive steps that one machine completes before the next machine starts any of them.

Each group carries `order` - where it sits among the project's steps, derived from its first member and never set by the caller - and `memberStepIds` in step order, projected from the steps' own `rollingGroupId` so the two cannot disagree. `machineOrderTagIds` is an empty array when the order is `MachineName`.

The same membership is visible from the step side on [List project steps](https://www.jawsdeploy.net/rest-api/projects-steps-list), as `rollingGroupId` on each step.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | The project to list groups for. |

## Response fields

| Field | Type | Description |
|---|---|---|
| `projectId` | string | The resolved project id, echoing the one you asked for. |
| `rollingGroups` | object[] | The project's rolling groups, ordered by `order`. Empty array when the project has none - not an error. Each element is described below. |
| `rollingGroups[].rollingGroupId` | string | The group's id. Pass this as `rollingGroupId` when updating, dissolving, or moving a step into the group. |
| `rollingGroups[].projectId` | string | The project the group belongs to. |
| `rollingGroups[].name` | string | Display name, shown in the step list, the deployment preview and the logs. |
| `rollingGroups[].order` | integer | Where the group sits among the project's steps. **Derived** from the order of its first member and never accepted from the caller, so it cannot disagree with the step list. |
| `rollingGroups[].windowSize` | integer | How many machines work through the group at once. `1` means a strict one-at-a-time rollout. Never above the organization's `maxParallelMachines`, which defaults to 8. |
| `rollingGroups[].machineOrder` | string (enum) | The order machines enter the group. One of `MachineName` - alphabetical, case-insensitive - or `TagPriority`, where a machine's rank is the index of the first tag it carries from `machineOrderTagIds`. Within a rank machines are ordered by name; machines carrying none of the tags run last. |
| `rollingGroups[].machineOrderTagIds` | string[] | Tag ids in priority order, first tag highest. Empty array when `machineOrder` is `MachineName` - the list is not persisted for an order that does not use it. |
| `rollingGroups[].waitBetweenMachineGroups` | boolean | The barrier. `true` finishes every machine of one tag rank before the next rank starts. Only ever `true` alongside `machineOrder` of `TagPriority`. |
| `rollingGroups[].onMachineFailure` | string (enum) | Whether the next machine starts after the group fails on one. `StopStep` - the default - starts no further machine; `ContinueToOtherMachines` carries on. Neither stops the deployment; that is `onStepFailure` on the member itself. |
| `rollingGroups[].onMemberFailure` | string (enum) | Whether a machine runs the group's remaining steps after one fails on it. `SkipRestOnThisMachine` - the default - skips them; `ContinueMembers` runs them, which is what a cleanup or notification member needs. |
| `rollingGroups[].onNoTargets` | string (enum) | What the group does when no machine matches any of its steps. `Skip` - the default - logs it as skipped; `Warn` adds a warning; `Fail` fails every step in the group. |
| `rollingGroups[].memberStepIds` | string[] | The member steps, in step order. **Projected** from the steps' own `rollingGroupId` rather than stored on the group, so this and the step list cannot disagree. Always at least one id. |

## Errors

| Status | Meaning |
|---|---|
| 400 | `projectId` is missing, or names a project that does not exist or is deleted - `invalid project ID`. |
| 400 | The group settings failed validation. The body carries `validationErrors`, each with the `property` that failed and its messages. |
| 401 | Missing or invalid Basic auth credentials, or the service account may not edit this project. |

Example request:

```
GET /api/project/rolling-groups?projectId=prj_42 HTTP/1.1
Authorization: Basic <base64(serviceAccountId:apiKey)>
```

Example response:

```
{
  "projectId": "prj_42",
  "rollingGroups": [
    {
      "rollingGroupId": "rg_7a1",
      "projectId": "prj_42",
      "name": "web rollout",
      "order": 3,
      "windowSize": 1,
      "machineOrder": "TagPriority",
      "machineOrderTagIds": ["tag-canary"],
      "waitBetweenMachineGroups": true,
      "onMachineFailure": "StopStep",
      "onMemberFailure": "SkipRestOnThisMachine",
      "onNoTargets": "Skip",
      "memberStepIds": ["step-1", "step-2", "step-3", "step-4"]
    }
  ]
}
```