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

# Manage Rollouts

> Learn how to create and manage rollouts using the Confidence API.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Manage Rollouts"
  description="Learn how to create and manage rollouts using the Confidence API."
  steps={[
{
  name: "Get a Rollout",
  text: "Retrieve a specific rollout by its name to view its configuration and current state. Response:",
},
{
  name: "List Rollouts",
  text: "List all rollouts in your account. You can filter by state or any other criteria in the response. Use nextPageToken for getting the next page of results. Response:",
},
{
  name: "Create a Rollout",
  text: "Create a new rollout with initial exposure settings. Response:",
},
{
  name: "Set Targeting on a Rollout",
  text: "After creating a rollout, call the UpdateSegment action with the desired targeting configuration. Include the updateMask field relative to segment.",
},
{
  name: "Action Methods",
  text: "Action methods return immediately with an empty result and start the action in the background. Use the GET endpoint for the rollout to monitor the progress by inspecting the pendingTransition field. Update the rollout to increase the reach (percentage of users exposed to the feature). Response:",
},
{
  name: "View Results for a Rollout",
  text: "To view statistical results for your rollout, use a two-step process. First, get the rollout to retrieve the analysisResult resource name from the stats field. Response:",
},
]}
/>

Use this API to create and manage Rollouts. For an introduction to rollout concepts, see the [rollout workflows documentation](/docs/experiments/workflows/rollouts).

## Get a Rollout

Retrieve a specific rollout by its name to view its configuration and current state.

```bash theme={null}
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "name": "workflows/rollout/instances/brcdajvw7dfuod7cj9iq",
  "displayName": "New Search Feature Rollout",
  "createTime": "2024-01-15T10:00:00Z",
  "updateTime": "2024-01-20T14:30:00Z"
}
```

## List Rollouts

List all rollouts in your account. You can filter by state or any other criteria in the response. Use `nextPageToken` for getting the next page of results.

```bash theme={null}
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances?pageSize=50&filter=state:live" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "rollouts": [
    {
      "name": "workflows/rollout/instances/brcdajvw7dfuod7cj9iq",
      "displayName": "New Search Feature Rollout",
      "state": "live"
    },
    {
      "name": "workflows/rollout/instances/bnkv2onacdpvxk8cmqbm",
      "displayName": "Mobile UI Update",
      "state": "live"
    }
  ],
  "nextPageToken": ""
}
```

## Create a Rollout

Create a new rollout with initial exposure settings.

```bash theme={null}
curl -X POST "https://experiments.confidence.dev/v1/workflows/rollout/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "New Search Feature Rollout",
    "flags": {
      "targetingKeySelector": "targeting_key"
    },
    "rollout": {
      "flag": "flags/search-flag",
      "variant": "flags/search-flag/variants/enabled"
    },
    "metrics": {
      "assignmentTable": "assignmentTables/my-assignment-table",
      "entity": "entities/user",
      "bucket": "DAYS",
      "metrics": [
        {
          "metric": "metrics/conversion-rate",
          "metricRole": {
            "metricKind": "SUCCESS",
            "minimumDetectableEffect": 0.01
          },
          "preferredDirection": "INCREASE"
        }
      ]
    }
  }'
```

Response:

```json theme={null}
{
  "name": "rollouts/new-search-feature",
  "displayName": "New Search Feature Rollout",
  "state": "draft",
  "createTime": "2024-01-15T10:00:00Z",
  "updateTime": "2024-01-15T10:00:00Z"
}
```

## Set Targeting on a Rollout

After creating a rollout, call the `UpdateSegment` action with the desired targeting configuration. Include the `updateMask` field relative to `segment`.

```bash theme={null}
curl -X POST "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq:updateSegment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updateMask": "targeting",
    "segment": {
      "name": "segments/pztjlarivt3tyfie5gsb",
      "targeting": {
        "criteria": {
          "country": {
            "attribute": {
              "attributeName": "country",
              "eqRule": {
                "value": {
                  "stringValue": "SE"
                }
              }
            }
          }
        },
        "expression": {
          "and": {
            "operands": [{"ref": "country"}]
          }
        }
      }
    }
  }'
```

## Action Methods

Action methods return immediately with an empty result and start the action in the background. Use the `GET` endpoint for the rollout to monitor the progress by inspecting the `pendingTransition` field.

### Launch a Rollout

```bash theme={null}
curl -X POST "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq:launch" \
  -H "Authorization: Bearer $TOKEN"
```

### Increase Reach

Update the rollout to increase the reach (percentage of users exposed to the feature).

```bash theme={null}
curl -X PATCH "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq?updateMask=rollout" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rollout": {
      "flag": "flags/search-flag",
      "reach": "0.5",
      "variant": "flags/search-flag/variants/enabled"
    }
  }'
```

Response:

```json theme={null}
{
  "name": "rollouts/new-search-feature",
  "displayName": "New Search Feature Rollout"
}
```

## View Results for a Rollout

To view statistical results for your rollout, use a two-step process.

### Step 1: Get the Rollout

First, get the rollout to retrieve the `analysisResult` resource name from the `stats` field.

```bash theme={null}
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "name": "workflows/rollout/instances/brcdajvw7dfuod7cj9iq",
  "displayName": "New Search Feature Rollout",
  "stats": {
    "analysisResult": "workflows/rollout/instances/brcdajvw7dfuod7cj9iq/analysisResults/abc123"
  }
}
```

If your rollout uses multiple exposure filters, check the `stats.analysisResults[]` array instead. Each entry has an `analysisResult` resource name and the corresponding `exposureFilterName`.

### Step 2: Get the Analysis Result

Use the `analysisResult` name from Step 1 to fetch the full statistical analysis
from the [Analysis Results API](/api-reference/get-analysisresult).

```bash theme={null}
curl -X GET "https://stats.confidence.dev/v2/workflows/rollout/instances/brcdajvw7dfuod7cj9iq/analysisResults/abc123" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "name": "workflows/rollout/instances/brcdajvw7dfuod7cj9iq/analysisResults/abc123",
  "exposureFilter": "",
  "annotations": [
    {
      "context": "OVERALL",
      "info": ["Analysis completed successfully"]
    }
  ],
  "results": [
    {
      "id": "metrics/conversion-rate",
      "statsSettings": {
        "method": "METHOD_Z_TEST",
        "adjustedAlpha": 0.05
      },
      "result": {
        "status": {
          "status": "METRIC_RESULT_STATUS_SIGNIFICANT_POSITIVE",
          "metricType": "METRIC_TYPE_SUCCESS"
        }
      }
    }
  ]
}
```