--- title: "Create a rollout" method: POST path: "/projects/{projectId}/endpoints/{endpointId}/rollouts" tags: ["RolloutService"] --- # Create a rollout `POST /projects/{projectId}/endpoints/{endpointId}/rollouts` Creates a rollout in the pending state without shifting traffic. Start the rollout in a separate request after reviewing its strategy and metric gates. ## Path parameters - `projectId` string, required — Project identifier. - `endpointId` string, required — Endpoint identifier. ## Request body - union — Strategy, metric gates, timing, and cleanup policy for shifting traffic between two deployments under one endpoint. - object - `sourceDeploymentId` string, required — Deployment that traffic shifts away from. - `targetDeploymentId` string, required — Deployment that traffic shifts toward. - `canary` DECanaryConfig, required — Canary strategy configuration for gradual traffic progression. An empty config uses the default 5, 25, 50, 100 percent ladder. - `steps` DERolloutStep[] — Optional progression steps. Defaults to 5, 25, 50, 100 percent when empty; explicit steps must increase and end at 100 percent. - `traffic` integer, required — Required percentage of traffic on the target deployment for this step. - `replicas` integer — Optional explicit target replica count for this step. - `stepInterval` string — Optional positive soak between steps. Defaults to 3m if omitted, and grows to cover metric rule windows plus ingestion lag. - `blueGreen` DEBlueGreenConfig — Blue-green strategy configuration for a single cutover to the target deployment. - `rolling` DERollingConfig — Rolling strategy configuration for capacity-preserving batches that ramp target replicas up while draining source replicas. - `metrics` DEMetricRule[] — Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts. - union — Metric gate evaluated during a rollout. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck, required — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck, required — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - `finalSourceReplicas` integer — Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source. - `finalTargetReplicas` integer — Optional target replica count at completion. Must be at least 1 when set; defaults to the source deployment's replica count at create time. - object - `sourceDeploymentId` string, required — Deployment that traffic shifts away from. - `targetDeploymentId` string, required — Deployment that traffic shifts toward. - `canary` DECanaryConfig — Canary strategy configuration for gradual traffic progression. An empty config uses the default 5, 25, 50, 100 percent ladder. - `steps` DERolloutStep[] — Optional progression steps. Defaults to 5, 25, 50, 100 percent when empty; explicit steps must increase and end at 100 percent. - `traffic` integer, required — Required percentage of traffic on the target deployment for this step. - `replicas` integer — Optional explicit target replica count for this step. - `stepInterval` string — Optional positive soak between steps. Defaults to 3m if omitted, and grows to cover metric rule windows plus ingestion lag. - `blueGreen` DEBlueGreenConfig, required — Blue-green strategy configuration for a single cutover to the target deployment. - `rolling` DERollingConfig — Rolling strategy configuration for capacity-preserving batches that ramp target replicas up while draining source replicas. - `metrics` DEMetricRule[] — Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts. - union — Metric gate evaluated during a rollout. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck, required — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck, required — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - `finalSourceReplicas` integer — Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source. - `finalTargetReplicas` integer — Optional target replica count at completion. Must be at least 1 when set; defaults to the source deployment's replica count at create time. - object - `sourceDeploymentId` string, required — Deployment that traffic shifts away from. - `targetDeploymentId` string, required — Deployment that traffic shifts toward. - `canary` DECanaryConfig — Canary strategy configuration for gradual traffic progression. An empty config uses the default 5, 25, 50, 100 percent ladder. - `steps` DERolloutStep[] — Optional progression steps. Defaults to 5, 25, 50, 100 percent when empty; explicit steps must increase and end at 100 percent. - `traffic` integer, required — Required percentage of traffic on the target deployment for this step. - `replicas` integer — Optional explicit target replica count for this step. - `stepInterval` string — Optional positive soak between steps. Defaults to 3m if omitted, and grows to cover metric rule windows plus ingestion lag. - `blueGreen` DEBlueGreenConfig — Blue-green strategy configuration for a single cutover to the target deployment. - `rolling` DERollingConfig, required — Rolling strategy configuration for capacity-preserving batches that ramp target replicas up while draining source replicas. - `metrics` DEMetricRule[] — Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts. - union — Metric gate evaluated during a rollout. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck, required — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - object - `name` 'inflight_requests' | 'router_error_rate' | 'router_latency' | 'serving_latency', required - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE', required — Required aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `thresholdCheck` DEThresholdCheck — Threshold criteria that fail when the target metric violates the configured bound. - `value` number, required — Required numeric threshold value. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE', required — Required comparison operator applied to the target metric value. - `regressionCheck` DERegressionCheck, required — Regression criteria that fail when the target regresses against the source beyond a limit. - `maxRegressionPercent` number, required — Required maximum allowed regression percentage. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE', required — Required direction that indicates whether higher or lower metric values are worse. - `window` string — Optional query window for the metric. Defaults to the step soak duration. - `finalSourceReplicas` integer — Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source. - `finalTargetReplicas` integer — Optional target replica count at completion. Must be at least 1 when set; defaults to the source deployment's replica count at create time. ## Response `200` OK - DERollout — Public view of a rollout resource and its embedded runtime status. - `id` string, required — Output only. Unique rollout identifier. - `endpointId` string, required — Output only. Endpoint this rollout belongs to. - `sourceDeploymentId` string, required — Output only. Deployment that traffic is shifting away from. - `targetDeploymentId` string, required — Output only. Deployment that traffic is shifting toward. - `strategy` 'ROLLOUT_STRATEGY_TYPE_ROLLING' | 'ROLLOUT_STRATEGY_TYPE_CANARY' | 'ROLLOUT_STRATEGY_TYPE_BLUE_GREEN', required — Output only. Rollout strategy selected at creation. - `state` 'ROLLOUT_STATE_RUNNING' | 'ROLLOUT_STATE_PAUSED' | 'ROLLOUT_STATE_STABILIZING' | 'ROLLOUT_STATE_ABORTING' | 'ROLLOUT_STATE_COMPLETED' | 'ROLLOUT_STATE_ABORTED' | 'ROLLOUT_STATE_PENDING' | 'ROLLOUT_STATE_SYSTEM_PAUSED' | 'ROLLOUT_STATE_CANCELLING' | 'ROLLOUT_STATE_CANCELED' | 'ROLLOUT_STATE_PAUSING', required — Output only. High-level rollout lifecycle state. - `currentStep` integer — Output only. Zero-based index of the current step. Unset while PENDING; step 0 is reported explicitly after start. - `currentTrafficPercent` integer — Output only. Applied percentage of traffic on the target deployment. - `createdAt` string, date-time, required — Output only. Timestamp when the rollout was created. - `startedAt` string, date-time — Output only. Timestamp when the rollout started running. - `completedAt` string, date-time — Output only. Timestamp when the rollout reached a terminal state. - `etag` string — Output only. Opaque version tag for optimistic concurrency control. - `status` DERolloutStatus, required — Derived runtime progress for a rollout. - `totalSteps` integer, required — Total number of steps in the rollout progression. Always serializes when status is present. - `condition` DERolloutCondition — Structured reason a rollout stopped progressing. - `category` 'ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION' | 'ROLLOUT_FAILURE_CATEGORY_METRICS_UNAVAILABLE' | 'ROLLOUT_FAILURE_CATEGORY_TARGET_NOT_READY' | 'ROLLOUT_FAILURE_CATEGORY_SOURCE_NOT_DRAINED' | 'ROLLOUT_FAILURE_CATEGORY_HEALTH_REGRESSION' | 'ROLLOUT_FAILURE_CATEGORY_CAPACITY_EXHAUSTED' | 'ROLLOUT_FAILURE_CATEGORY_ROUTING_ERROR' | 'ROLLOUT_FAILURE_CATEGORY_DEPENDENCY_OUTAGE' | 'ROLLOUT_FAILURE_CATEGORY_ABORTED_BY_OPERATOR' | 'ROLLOUT_FAILURE_CATEGORY_INTERNAL' | 'ROLLOUT_FAILURE_CATEGORY_POLICY_INFEASIBLE' | 'ROLLOUT_FAILURE_CATEGORY_UNDER_SERVED' | 'ROLLOUT_FAILURE_CATEGORY_ENTITLEMENT_LAPSED' — Category that classifies why the rollout stopped. - `message` string — Human-readable explanation for the condition. - `atStep` integer — Step index where the condition arose. Step 0 serializes explicitly. - `observedAt` string, date-time — Timestamp when the condition was observed. - `metrics` DEMetricResult[] — Metrics observed at the failing gate, enriched with their criteria. - `name` string — Metric name as exported to the observability backend. - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE' — Aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `check` 'METRIC_CHECK_TYPE_THRESHOLD' | 'METRIC_CHECK_TYPE_REGRESSION' — Evaluation form used by the metric rule. - `sourceValue` number — Observed source baseline. Set only for regression checks; a 0 reading serializes explicitly. - `targetValue` number — Observed target value. A 0 reading serializes explicitly. - `threshold` number — Threshold criteria used when check is METRIC_CHECK_TYPE_THRESHOLD. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE' — Threshold comparison operator. - `maxRegressionPercent` number — Regression percentage limit used when check is METRIC_CHECK_TYPE_REGRESSION. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE' — Direction that indicates whether higher or lower values are worse. - `verdict` 'METRIC_VERDICT_PASS' | 'METRIC_VERDICT_BREACHED' | 'METRIC_VERDICT_UNAVAILABLE' — Result of evaluating this metric at the gate. - `steps` DERolloutStepStatus[], required — Per-step rollout execution summaries. - `stepIndex` integer — Index of this step in the rollout progression. Step 0 serializes explicitly. - `targetTrafficPercent` integer — Target traffic percentage configured for this step. Always serializes for recorded steps. - `state` 'ROLLOUT_STEP_STATE_PENDING' | 'ROLLOUT_STEP_STATE_RUNNING' | 'ROLLOUT_STEP_STATE_PASSED' | 'ROLLOUT_STEP_STATE_FAILED' — Execution state of this rollout step. - `metrics` DEMetricResult[] — Metric gate results for this step. - `name` string — Metric name as exported to the observability backend. - `stat` 'METRIC_STAT_TYPE_AVG' | 'METRIC_STAT_TYPE_MIN' | 'METRIC_STAT_TYPE_MAX' | 'METRIC_STAT_TYPE_PERCENTILE' — Aggregation used for the metric. - `percentile` integer — Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. - `check` 'METRIC_CHECK_TYPE_THRESHOLD' | 'METRIC_CHECK_TYPE_REGRESSION' — Evaluation form used by the metric rule. - `sourceValue` number — Observed source baseline. Set only for regression checks; a 0 reading serializes explicitly. - `targetValue` number — Observed target value. A 0 reading serializes explicitly. - `threshold` number — Threshold criteria used when check is METRIC_CHECK_TYPE_THRESHOLD. - `operator` 'THRESHOLD_OPERATOR_GT' | 'THRESHOLD_OPERATOR_GTE' | 'THRESHOLD_OPERATOR_LT' | 'THRESHOLD_OPERATOR_LTE' — Threshold comparison operator. - `maxRegressionPercent` number — Regression percentage limit used when check is METRIC_CHECK_TYPE_REGRESSION. - `direction` 'REGRESSION_DIRECTION_HIGHER_IS_WORSE' | 'REGRESSION_DIRECTION_LOWER_IS_WORSE' — Direction that indicates whether higher or lower values are worse. - `verdict` 'METRIC_VERDICT_PASS' | 'METRIC_VERDICT_BREACHED' | 'METRIC_VERDICT_UNAVAILABLE' — Result of evaluating this metric at the gate. - `startedAt` string, date-time — Timestamp when this step started. - `completedAt` string, date-time — Timestamp when this step completed. - `failureReason` string — Failure reason when this step failed. - `updatedAt` string, date-time — Timestamp of the most recent progress update. - `pauseInfo` DEPauseInfo — Pause metadata returned while a rollout is paused. - `reason` string — Human-readable reason recorded when the rollout was paused. - `pausedAt` string, date-time, required — Timestamp when the rollout was paused. ## Other responses - `default` — Default error response --- [API](https://skmtc.net/together/apis/together-apis.md) · [All operations](https://skmtc.net/together/apis/together-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/together/together-apis/versions/f26a23fab8e0/schema)