Skip to main content

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.

Use this API to create and manage Rollouts. For an introduction to rollout concepts, see the rollout workflows documentation.

​
Get a Rollout

Retrieve a specific rollout by its name to view its configuration and current state. 
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "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. 
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances?pageSize=50&filter=state:live" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "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. 
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: 
{
  "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. 
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

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). 
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: 
{
  "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. 
curl -X GET "https://experiments.confidence.dev/v1/workflows/rollout/instances/brcdajvw7dfuod7cj9iq" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "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. 
curl -X GET "https://stats.confidence.dev/v2/workflows/rollout/instances/brcdajvw7dfuod7cj9iq/analysisResults/abc123" \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "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"
        }
      }
    }
  ]
}