> ## Documentation Index > Fetch the complete documentation index at: https://docs.together.ai/llms.txt > Use this file to discover all available pages before exploring further. # Preview rollout defaults > Returns the values a create request would pick for any field left unset, plus the capacity context needed to display them, without creating a rollout. Responses are display state only and re-validated authoritatively at create and start; do not copy response values back into a create request. ## OpenAPI ````yaml openapi.yaml POST /projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults openapi: 3.1.0 info: title: Together APIs description: The Together REST API. See https://docs.together.ai for more details. version: 2.0.0 termsOfService: https://www.together.ai/terms-of-service contact: name: Together Support url: https://www.together.ai/contact license: name: MIT url: https://github.com/togethercomputer/openapi/blob/main/LICENSE servers: - url: https://api.together.ai/v1 description: Default environment for APIs - url: https://api-inference.together.ai/v2 description: Optimized environment for inference security: - bearerAuth: [] paths: /projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults: post: tags: - RolloutService summary: Preview rollout defaults description: >- Returns the values a create request would pick for any field left unset, plus the capacity context needed to display them, without creating a rollout. Responses are display state only and re-validated authoritatively at create and start; do not copy response values back into a create request. operationId: RolloutService_PreviewRolloutDefaults parameters: - name: projectId in: path required: true schema: description: Project identifier. type: string - name: endpointId in: path required: true schema: description: Endpoint identifier. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DE.CreateRolloutRequest' examples: canary: summary: Canary rollout with a metric gate value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 canary: steps: - traffic: 25 - traffic: 50 - traffic: 100 stepInterval: 300s metrics: - name: router_latency stat: METRIC_STAT_TYPE_PERCENTILE percentile: 95 thresholdCheck: value: 30000 operator: THRESHOLD_OPERATOR_LT window: 300s blueGreen: summary: Blue-green cutover value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 blueGreen: {} rolling: summary: Rolling replica swap value: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 rolling: {} required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DE.RolloutDefaultsPreview' examples: canary: summary: Preview of a canary create form with defaults filled in value: spec: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 canary: steps: - traffic: 25 - traffic: 50 - traffic: 100 stepInterval: 300s metrics: - name: router_latency stat: METRIC_STAT_TYPE_PERCENTILE percentile: 95 thresholdCheck: value: 30000 operator: THRESHOLD_OPERATOR_LT window: 300s sourceReplicas: 4 targetReplicas: 1 targetMinReplicas: 1 targetMaxReplicas: 8 warnings: [] frozenPair: false default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/ErrorData' servers: - url: https://api.together.ai/v2 x-codeSamples: - lang: Python label: Together AI SDK (Python) source: | from together import Together client = Together() project_id = client.whoami().project_id # Returns the values a create request would use for unset fields, # without creating a rollout. defaults = client.beta.endpoints.rollouts.preview_defaults( "ep_abc123", project_id=project_id, source_deployment_id="dep_abc123", target_deployment_id="dep_def456", canary={"steps": [{"traffic": 25}, {"traffic": 100}]}, ) print(defaults) - lang: TypeScript label: Together AI SDK (TypeScript) source: > import Together from "together-ai"; const client = new Together(); const { project_id: projectId } = await client.whoami(); // Returns the values a create request would use for unset fields, // without creating a rollout. const defaults = await client.beta.endpoints.rollouts.previewDefaults( "ep_abc123", { projectId, sourceDeploymentId: "dep_abc123", targetDeploymentId: "dep_def456", canary: { steps: [{ traffic: 25 }, { traffic: 100 }] }, }, ); console.log(defaults); - lang: JavaScript label: Together AI SDK (JavaScript) source: > import Together from "together-ai"; const client = new Together(); const { project_id: projectId } = await client.whoami(); // Returns the values a create request would use for unset fields, // without creating a rollout. const defaults = await client.beta.endpoints.rollouts.previewDefaults( "ep_abc123", { projectId, sourceDeploymentId: "dep_abc123", targetDeploymentId: "dep_def456", canary: { steps: [{ traffic: 25 }, { traffic: 100 }] }, }, ); console.log(defaults); components: schemas: DE.CreateRolloutRequest: type: object description: >- Strategy, metric gates, timing, and cleanup policy for shifting traffic between two deployments under one endpoint. required: - sourceDeploymentId - targetDeploymentId oneOf: - x-stainless-variantName: Canary required: - canary - x-stainless-variantName: BlueGreen required: - blueGreen - x-stainless-variantName: Rolling required: - rolling properties: sourceDeploymentId: type: string description: Deployment that traffic shifts away from. targetDeploymentId: type: string description: Deployment that traffic shifts toward. canary: allOf: - $ref: '#/components/schemas/DE.CanaryConfig' description: >- Canary rollout strategy configuration. Mutually exclusive with blueGreen and rolling. blueGreen: allOf: - $ref: '#/components/schemas/DE.BlueGreenConfig' description: >- Blue-green rollout strategy configuration. Mutually exclusive with canary and rolling. rolling: allOf: - $ref: '#/components/schemas/DE.RollingConfig' description: >- Rolling rollout strategy configuration. Mutually exclusive with canary and blueGreen. metrics: type: array items: $ref: '#/components/schemas/DE.MetricRule' description: >- Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts. finalSourceReplicas: type: integer description: >- Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source. finalTargetReplicas: type: integer description: >- Optional target replica floor at completion. Must be at least 1 when set; defaults to the source deployment's replica count at create time, or to the source and target deployments' combined replica count when both already stand in the endpoint traffic split after a cancel. The completed target's autoscaling max lands at the landing ceiling, max(this value, the source max, the target's own max); the rollout may lift the target max at first wake, at the first step that needs it, or at completion unless an operator changes max mid-run. The lifted ceiling remains after completion, and PreviewRolloutDefaults reports a coming lift as ROLLOUT_WILL_RAISE_TARGET_MAX. A pre-existing target whose own autoscaling min is higher keeps that floor, reported as FINAL_BELOW_INHERITED_MIN. A target that starts stopped lands exactly at this value; if the source min was higher, PreviewRolloutDefaults reports FINAL_BELOW_SOURCE_MIN. DE.RolloutDefaultsPreview: type: object description: >- Completed create-form state — the caller's spec with defaulted values filled in, the steps the rollout is expected to walk, and the capacity context the defaults were computed from. Display only. required: - spec - sourceReplicas - targetReplicas - targetMinReplicas - targetMaxReplicas - warnings example: spec: sourceDeploymentId: dep_source123 targetDeploymentId: dep_target456 canary: steps: - traffic: 25 - traffic: 50 - traffic: 100 stepInterval: 300s metrics: - name: router_latency stat: METRIC_STAT_TYPE_PERCENTILE percentile: 95 thresholdCheck: value: 30000 operator: THRESHOLD_OPERATOR_LT window: 300s sourceReplicas: 4 targetReplicas: 1 targetMinReplicas: 1 targetMaxReplicas: 8 warnings: [] frozenPair: false properties: spec: allOf: - $ref: '#/components/schemas/DE.CreateRolloutRequest' description: >- The caller's spec with defaulted values filled in for display. canary.steps is echoed exactly as sent; the suggested ladder is returned in estimatedEffectiveSteps instead. estimatedEffectiveSteps: type: array items: $ref: '#/components/schemas/DE.RolloutStep' description: >- Steps the rollout is expected to walk when the caller leaves steps unset. Display only. Empty when the caller supplied steps or no ladder applies. frozenPair: type: boolean description: >- True when both deployments stand in the endpoint traffic split, so the rollout resumes from the current split rather than from zero. See warnings for standing split shapes that StartRollout will still reject. estimatedSeedPercent: type: integer description: >- Percentage of the pair's traffic currently reaching the target, the floor the suggested steps start above. Unset when not a frozen pair or unknown; 0 is a real measurement. sourceReplicas: type: integer description: >- Source deployment replica count the defaults were computed from. Zero is a real value. targetReplicas: type: integer description: >- Target deployment replica count the defaults were computed from. Zero is a real value. targetMinReplicas: type: integer description: >- Target deployment autoscaling minimum replica count. Zero is a real value. targetMaxReplicas: type: integer description: >- Target deployment autoscaling maximum replica count. Zero is a real value. warnings: type: array items: $ref: '#/components/schemas/DE.PreviewWarning' description: >- Findings to surface next to the form when a later gate will refuse the spec or a standing guarantee is lost. An empty list means the shown values are safe to submit as-is; render message for unrecognized codes. landingMinReplicas: type: integer description: >- Expected autoscaling minimum replicas for the completed target; unset while the final target replicas cannot be resolved. landingMaxReplicas: type: integer description: >- Expected autoscaling maximum replicas for the completed target; unset while the final target replicas cannot be resolved. ErrorData: type: object required: - error properties: error: type: object properties: message: type: string nullable: false type: type: string nullable: false param: type: string nullable: true default: null code: type: string nullable: true default: null required: - type - message DE.CanaryConfig: type: object description: >- Canary strategy configuration for gradual traffic progression. An empty config uses the default 5, 25, 50, 100 percent ladder; over a frozen traffic-split pair left by cancel, the default ladder is derived at start from the pair's current served share so it begins above it. properties: steps: type: array items: $ref: '#/components/schemas/DE.RolloutStep' description: >- Optional progression steps. Defaults to 5, 25, 50, 100 percent when empty; explicit steps must increase and end at 100 percent. stepInterval: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional positive soak between steps. Defaults to 3m if omitted, and grows to cover metric rule windows plus ingestion lag. DE.BlueGreenConfig: type: object properties: {} additionalProperties: false x-stainless-empty-object: true description: >- Blue-green strategy configuration for a single cutover to the target deployment. DE.RollingConfig: type: object properties: {} additionalProperties: false x-stainless-empty-object: true description: >- Rolling strategy configuration for small batches that ramp target replicas up while shrinking source replicas to what their remaining traffic share needs. DE.MetricRule: type: object description: Metric gate evaluated during a rollout. required: - name oneOf: - x-stainless-variantName: Threshold required: - thresholdCheck - x-stainless-variantName: Regression required: - regressionCheck properties: name: enum: - inflight_requests - router_error_rate - router_latency type: string description: >- Required catalogue key for the metric to gate on. `serving_latency` is retired. stat: enum: - METRIC_STAT_TYPE_AVG - METRIC_STAT_TYPE_PERCENTILE type: string description: >- Aggregation used for the metric. Optional for router_error_rate and inflight_requests; omitted values default to METRIC_STAT_TYPE_AVG. Required for router_latency, where AVG or PERCENTILE may be used. percentile: type: integer description: >- Percentile value, such as 99. Set only when stat is METRIC_STAT_TYPE_PERCENTILE. thresholdCheck: allOf: - $ref: '#/components/schemas/DE.ThresholdCheck' description: >- Threshold evaluation criteria. Mutually exclusive with regressionCheck. regressionCheck: allOf: - $ref: '#/components/schemas/DE.RegressionCheck' description: >- Regression evaluation criteria. Mutually exclusive with thresholdCheck. window: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: string description: >- Optional query window for the metric. Defaults to the step soak duration. DE.RolloutStep: type: object description: One stage of a canary rollout progression. required: - traffic properties: traffic: type: integer description: >- Required percentage of traffic on the target deployment for this step. replicas: type: integer description: Optional explicit target replica count for this step. DE.PreviewWarning: type: object description: >- A non-blocking finding attached to a rollout defaults preview; expected end-state facts are structured fields on RolloutDefaultsPreview. required: - code - message properties: code: type: string description: >- Machine-readable warning code. Current vocabulary is START_WILL_REJECT, FINAL_BELOW_SOURCE_MIN, and FIRST_STEP_AT_SEED; render message for unrecognized codes. message: type: string description: Plain-language description of the finding, safe to show users as-is. DE.ThresholdCheck: type: object description: >- Threshold criteria that fail when the target metric violates the configured bound. required: - operator properties: value: type: number description: |- Finite threshold value. Interpreted in the metric's unit: router_error_rate is a ratio in [0, 1], router_latency is milliseconds, and inflight_requests is in-flight requests per ready replica averaged over the rule window. Thresholds that no achievable value could pass, or that every achievable value passes, are rejected at create. Omitting this value is read as 0. Set 0 explicitly for the strictest threshold: nothing at all is tolerated. operator: enum: - THRESHOLD_OPERATOR_GT - THRESHOLD_OPERATOR_GTE - THRESHOLD_OPERATOR_LT - THRESHOLD_OPERATOR_LTE type: string description: Required comparison operator applied to the target metric value. DE.RegressionCheck: type: object description: >- Regression criteria that fail when the target regresses against the source beyond a limit. required: - direction properties: maxRegressionPercent: type: number description: >- Finite maximum allowed regression percentage, greater than or equal to 0. Omitting this value is read as 0. A value of 0 is the strictest budget; any regression fails, and exactly-at-budget passes. direction: enum: - REGRESSION_DIRECTION_HIGHER_IS_WORSE - REGRESSION_DIRECTION_LOWER_IS_WORSE type: string description: >- Required direction that indicates whether higher or lower metric values are worse. securitySchemes: bearerAuth: type: http scheme: bearer x-bearer-format: bearer x-default: default ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.