---
title: "Update experiment settings"
method: PATCH
path: "/api/experiments/{experimentId}/settings"
tags: ["experiments"]
---

# Update experiment settings

`PATCH /api/experiments/{experimentId}/settings`

## Request

- Base URL: `https://api.iterable.com`
- URL: `https://api.iterable.com/api/experiments/{experimentId}/settings`
- Auth: API key in header `Api-Key`

Updates settings on a campaign experiment that's in <code>draft</code> or <code>ready</code> status. Iterable changes only the fields you send. Omitted fields keep their current values, and <code>null</code> removes a setting when the field allows it. Blast campaigns accept blast and holdout settings, and triggered campaigns accept trigger settings. This endpoint works only with experiments that test message content: the subject line, preheader text, from name and sender, email body, or all content. It doesn't work with send time or Send Time Decisioning experiments. This endpoint doesn't support journey experiments.

## Path parameters

- `experimentId` integer, required

## Request body

- UpdateExperimentSettingsRequest: Settings for a <code>draft</code> or <code>ready</code> campaign experiment
  - `conversionEventSettings` ConversionEventSettingsRequest: The conversion this experiment measures. Send <code>opens</code> or <code>clicks</code>, or a custom conversion, not both.
    - `customConversionId` integer: ID of a custom conversion, such as a purchase. Send this instead of <code>opens</code> or <code>clicks</code>.
    - `systemConversionEventType` 'opens' | 'clicks': <code>opens</code> or <code>clicks</code>. Any capitalization is accepted. For a purchase or any other conversion, send <code>customConversionId</code> instead.
  - `evenlySplitVariations` boolean: Set to <code>true</code> to split the audience evenly across variants. This removes any blast or trigger test group. To stop splitting evenly, send blast or trigger settings instead. To keep the current split, leave this out from the request.
  - `explorationBlastSettings` BlastExplorationSettingsRequest: Test group for a blast campaign that does not use a set send time
    - `testDurationMinutes` integer, required: How long the test runs before Iterable selects a winner, in minutes.
    - `testSizePercentage` integer, required: Share of the audience used as the test group, split evenly among variants, from 1 to 99 percent.
  - `explorationTriggerSettings` TriggerExplorationSettingsRequest: How a triggered campaign experiment chooses a winner
    - `testSendsPerVariation` integer, required: How many sends each variant needs before Iterable can select a winner.
  - `holdoutSettings` HoldoutSettingsRequest: A group that doesn't receive the experiment. Available only for blast campaigns, and only when the experiment uses a custom conversion.
    - `attributionPeriodHours` integer, required: How long, in hours, a conversion can count for the holdout group.
    - `holdOutGroupSize` integer, required: Share of the audience reserved for the holdout group, from 1 to 99 percent.

## Response `200`

Experiment settings updated

- ExperimentResponse: Full experiment details
  - `allocationMode` string, required: Traffic allocation mode
  - `channelType` 'email' | 'push' | 'sms' | 'in_app' | 'web_push', required: Channel type for the experiment.
  - `constraints` ExperimentConstraints: Experiment constraints/targeting
    - `suppressionListIds` integer[]: List IDs to suppress
    - `targetSegment` string: Target segment description
  - `creationDate` string, date-time: Date the experiment was created
  - `experimentType` string, required: Experiment type
  - `finishDate` string, date-time: End date of the experiment
  - `id` integer, required: Experiment ID
  - `meta` ExperimentMeta, required: Experiment metadata
    - `campaignId` integer: Campaign ID
    - `conversionMetrics` string[], required: Conversion metrics being tracked
    - `customConversionId` integer: ID of the custom conversion event the experiment measures. <code>null</code> if the experiment measures a system event, such as <code>opens</code> or <code>clicks</code>.
    - `name` string, required: Experiment name
    - `orgId` integer, required: Organization ID
    - `projectId` integer, required: Project ID
  - `sizing` ExperimentSizingResponse, required: Experiment traffic allocation
    - `attributionPeriodHours` integer: Attribution window in hours for the holdout group. <code>null</code> if the experiment has no holdout group configured.
    - `holdoutPercentage` number, double: Percentage of total audience reserved as a holdout group that does not receive any experiment traffic. <code>null</code> if the experiment has no holdout group configured.
    - `perVariantPercentage` number, double: Percentage of total audience distributed evenly to each variant for experiments with a blast campaign that include all users. <code>null</code> for other experiment types.
    - `sendsPerVariant` integer: Minimum number of sends each variant must receive before the test phase ends and a winner can be selected. Defaults to 1000. Applies only to triggered campaign experiments.
    - `testDurationMinutes` integer: How long the test phase runs before Iterable selects a winner, in minutes. Defaults to 120 minutes. Applies only to experiments with blast campaigns that are not based on a specified send time.
    - `testGroupPercentage` number, double: Percentage of total audience used as the test group, split evenly among variants (defaults to 20%). During the test phase, Iterable sends to this group to determine which variant performs best.
    - `winnerGroupPercentage` number, double: Percentage of total audience (minus the holdout group) that receives the winning variant after the test phase completes (the optimized group). Users who already received a non-winning variant during the test phase do not receive the winner again.
  - `startDate` string, date-time: Start date of the experiment
  - `status` 'draft' | 'ready' | 'running' | 'finished' | 'winner_found', required: Experiment status
  - `variants` ExperimentVariantSummary[], required: Experiment variants
    - `currentPercentage` number, double, required: Percentage of total audience distributed to this variant, allocated based on the type of experiment you're running.
    - `id` integer, required: Variant ID
    - `isControl` boolean, required: Whether this variant is the control variant
    - `isWinner` boolean, required: Whether this variant is the winner
    - `name` string, required: Variant name
    - `value` ExperimentVariantValue, required: Typed variant value payload. Only present fields are serialized.
      - `sendTime` string: When this variant sends, as an ISO 8601 timestamp. Included only for send time experiments.
      - `stoGroup` string: STO group identifier for STO variants
      - `templateId` integer: ID of the template this variant sends. Included only for experiments that test message content.

## Other responses

- `400`: Invalid parameters
- `401`: Invalid API key
- `404`: Experiment or campaign not found
- `409`: Experiment isn't in <code>draft</code> or <code>ready</code> status
- `500`: Internal server error

## Changes

- **2026-09-30** `cca837e62715`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/iterable/apis/iterable-api/changes/api/experiments/:experimentId/settings/patch.md)

---

[API](https://skmtc.dev/iterable/apis/iterable-api.md) - [All operations](https://skmtc.dev/iterable/apis/iterable-api/llms.txt) - [OpenAPI document](https://skmtc.dev/iterable/apis/iterable-api/revisions/a430ac1d1db7?raw)