Preview rollout defaults

Together AI SDK (Python)

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)

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);

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);

curl --request POST \
  --url https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults"

	payload := strings.NewReader("{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": null,
    "code": null
  }
}

POST

projects

{projectId}

endpoints

{endpointId}

rollouts

preview-defaults

Together AI SDK (Python)

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)

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);

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);

curl --request POST \
  --url https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults"

	payload := strings.NewReader("{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/preview-defaults")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceDeploymentId\": \"dep_source123\",\n  \"targetDeploymentId\": \"dep_target456\",\n  \"canary\": {\n    \"steps\": [\n      {\n        \"traffic\": 25\n      },\n      {\n        \"traffic\": 50\n      },\n      {\n        \"traffic\": 100\n      }\n    ],\n    \"stepInterval\": \"300s\"\n  },\n  \"metrics\": [\n    {\n      \"name\": \"router_latency\",\n      \"stat\": \"METRIC_STAT_TYPE_PERCENTILE\",\n      \"percentile\": 95,\n      \"thresholdCheck\": {\n        \"value\": 30000,\n        \"operator\": \"THRESHOLD_OPERATOR_LT\"\n      },\n      \"window\": \"300s\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": null,
    "code": null
  }
}

Authorizations

Authorization

string

header

default:default

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

projectId

string

required

Project identifier.

endpointId

string

required

Endpoint identifier.

Body

application/json

Option 1
Option 2
Option 3

Strategy, metric gates, timing, and cleanup policy for shifting traffic between two deployments under one endpoint.

sourceDeploymentId

string

required

Deployment that traffic shifts away from.

targetDeploymentId

string

required

Deployment that traffic shifts toward.

canary

object

required

Canary rollout strategy configuration. Mutually exclusive with blueGreen and rolling.

Show child attributes

blueGreen

object

Blue-green rollout strategy configuration. Mutually exclusive with canary and rolling.

rolling

object

Rolling rollout strategy configuration. Mutually exclusive with canary and blueGreen.

metrics

object[]

Optional metric gates evaluated after each step's soak. Canary only; rejected on rolling and blue-green rollouts.

Metric gate evaluated during a rollout.

Option 1
Option 2

Show child attributes

finalSourceReplicas

integer

Optional final replica count for the source deployment. Defaults to 0, which drains and stops the source.

finalTargetReplicas

integer

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.

Response

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.

spec

object

required

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.

Option 1
Option 2
Option 3

Show child attributes

sourceReplicas

integer

required

Source deployment replica count the defaults were computed from. Zero is a real value.

targetReplicas

integer

required

Target deployment replica count the defaults were computed from. Zero is a real value.

targetMinReplicas

integer

required

Target deployment autoscaling minimum replica count. Zero is a real value.

targetMaxReplicas

integer

required

Target deployment autoscaling maximum replica count. Zero is a real value.

warnings

object[]

required

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.

Show child attributes

estimatedEffectiveSteps

object[]

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.

Show child attributes

frozenPair

boolean

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

integer

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.

landingMinReplicas

integer

Expected autoscaling minimum replicas for the completed target; unset while the final target replicas cannot be resolved.

landingMaxReplicas

integer

Expected autoscaling maximum replicas for the completed target; unset while the final target replicas cannot be resolved.

⌘I

TOGETHER APIS

SDK LIBRARIES

ERROR CODES

Authorizations

Path Parameters

Body

Response