Start a rollout

POST

projects

{projectId}

endpoints

{endpointId}

rollouts

{id}

start

Together AI SDK (Python)

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

rollout = client.endpoints.rollouts.start(
    "rol_abc123",
    project_id=project_id,
    endpoint_id="ep_abc123",
)
print(rollout.id, rollout.state)

import Together from "together-ai";

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const rollout = await client.endpoints.rollouts.start("rol_abc123", {
  projectId,
  endpointId: "ep_abc123",
});
console.log(rollout.id, rollout.state);

import Together from "together-ai";

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const rollout = await client.endpoints.rollouts.start("rol_abc123", {
  projectId,
  endpointId: "ep_abc123",
});
console.log(rollout.id, rollout.state);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/{id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/{id}/start"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "endpointId": "<string>",
  "sourceDeploymentId": "<string>",
  "targetDeploymentId": "<string>",
  "strategy": "ROLLOUT_STRATEGY_TYPE_ROLLING",
  "state": "ROLLOUT_STATE_RUNNING",
  "createdAt": "2023-11-07T05:31:56Z",
  "status": {
    "totalSteps": 123,
    "steps": [
      {
        "stepIndex": 123,
        "targetTrafficPercent": 123,
        "state": "ROLLOUT_STEP_STATE_PENDING",
        "metrics": [
          {
            "name": "<string>",
            "stat": "METRIC_STAT_TYPE_AVG",
            "percentile": 123,
            "check": "METRIC_CHECK_TYPE_THRESHOLD",
            "sourceValue": 123,
            "targetValue": 123,
            "threshold": 123,
            "operator": "THRESHOLD_OPERATOR_GT",
            "maxRegressionPercent": 123,
            "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
            "verdict": "METRIC_VERDICT_PASS",
            "failureReason": "<string>"
          }
        ],
        "startedAt": "2023-11-07T05:31:56Z",
        "completedAt": "2023-11-07T05:31:56Z",
        "failureReason": "<string>"
      }
    ],
    "condition": {
      "category": "ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION",
      "message": "<string>",
      "atStep": 123,
      "observedAt": "2023-11-07T05:31:56Z",
      "metrics": [
        {
          "name": "<string>",
          "stat": "METRIC_STAT_TYPE_AVG",
          "percentile": 123,
          "check": "METRIC_CHECK_TYPE_THRESHOLD",
          "sourceValue": 123,
          "targetValue": 123,
          "threshold": 123,
          "operator": "THRESHOLD_OPERATOR_GT",
          "maxRegressionPercent": 123,
          "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
          "verdict": "METRIC_VERDICT_PASS",
          "failureReason": "<string>"
        }
      ],
      "type": "CapacityLimited"
    },
    "updatedAt": "2023-11-07T05:31:56Z",
    "conditions": [
      {
        "category": "ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION",
        "message": "<string>",
        "atStep": 123,
        "observedAt": "2023-11-07T05:31:56Z",
        "metrics": [
          {
            "name": "<string>",
            "stat": "METRIC_STAT_TYPE_AVG",
            "percentile": 123,
            "check": "METRIC_CHECK_TYPE_THRESHOLD",
            "sourceValue": 123,
            "targetValue": 123,
            "threshold": 123,
            "operator": "THRESHOLD_OPERATOR_GT",
            "maxRegressionPercent": 123,
            "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
            "verdict": "METRIC_VERDICT_PASS",
            "failureReason": "<string>"
          }
        ],
        "type": "CapacityLimited"
      }
    ]
  },
  "currentStep": 123,
  "currentTrafficPercent": 123,
  "startedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "etag": "<string>",
  "pauseInfo": {
    "pausedAt": "2023-11-07T05:31:56Z",
    "reason": "<string>"
  },
  "maxSurge": 123,
  "maxUnavailable": 123
}

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

string

required

Rollout identifier.

Response

Public view of a rollout resource, including runtime progress and any pause or abort reason.

string

required

read-only

Output only. Unique rollout identifier.

endpointId

string

required

read-only

Output only. Endpoint this rollout belongs to.

sourceDeploymentId

string

required

read-only

Output only. Deployment that traffic is shifting away from.

targetDeploymentId

string

required

read-only

Output only. Deployment that traffic is shifting toward.

strategy

enum<string>

required

read-only

Output only. Rollout strategy selected at creation.

Available options:

ROLLOUT_STRATEGY_TYPE_ROLLING,

ROLLOUT_STRATEGY_TYPE_CANARY,

ROLLOUT_STRATEGY_TYPE_BLUE_GREEN

state

enum<string>

required

read-only

Output only. High-level rollout lifecycle state.

Available options:

ROLLOUT_STATE_RUNNING,

ROLLOUT_STATE_PAUSED,

ROLLOUT_STATE_STABILIZING,

ROLLOUT_STATE_COMPLETED,

ROLLOUT_STATE_PENDING,

ROLLOUT_STATE_SYSTEM_PAUSED,

ROLLOUT_STATE_CANCELLING,

ROLLOUT_STATE_CANCELED,

ROLLOUT_STATE_PAUSING

createdAt

string<date-time>

required

read-only

Output only. Timestamp when the rollout was created.

status

object

required

Output only. Derived runtime progress, step summary, and pause or abort failure details.

Show child attributes

currentStep

integer

read-only

Output only. Zero-based index of the current step. Unset while PENDING; step 0 is reported explicitly after start.

currentTrafficPercent

integer

read-only

Output only. Applied percentage of traffic on the target deployment.

startedAt

string<date-time>

read-only

Output only. Timestamp when the rollout started running.

completedAt

string<date-time>

read-only

Output only. Timestamp when the rollout reached a terminal state.

etag

string

read-only

Output only. Opaque version tag for optimistic concurrency control.

pauseInfo

object

Output only. Why and when the rollout was paused. Set while a pause is pending or effective (PAUSING, PAUSED, or SYSTEM_PAUSED) and cleared after resume or abort; while PAUSING, pausedAt records when the pause was requested.

Show child attributes

maxSurge

integer

read-only

Output only. The maxSurge the rollout was created with. Absent when it was not set.

maxUnavailable

integer

read-only

The maxUnavailable the rollout was created with. Absent when it was not set.

⌘I

Together AI SDK (Python)

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

rollout = client.endpoints.rollouts.start(
    "rol_abc123",
    project_id=project_id,
    endpoint_id="ep_abc123",
)
print(rollout.id, rollout.state)

import Together from "together-ai";

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const rollout = await client.endpoints.rollouts.start("rol_abc123", {
  projectId,
  endpointId: "ep_abc123",
});
console.log(rollout.id, rollout.state);

import Together from "together-ai";

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const rollout = await client.endpoints.rollouts.start("rol_abc123", {
  projectId,
  endpointId: "ep_abc123",
});
console.log(rollout.id, rollout.state);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/{id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts/{id}/start"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "endpointId": "<string>",
  "sourceDeploymentId": "<string>",
  "targetDeploymentId": "<string>",
  "strategy": "ROLLOUT_STRATEGY_TYPE_ROLLING",
  "state": "ROLLOUT_STATE_RUNNING",
  "createdAt": "2023-11-07T05:31:56Z",
  "status": {
    "totalSteps": 123,
    "steps": [
      {
        "stepIndex": 123,
        "targetTrafficPercent": 123,
        "state": "ROLLOUT_STEP_STATE_PENDING",
        "metrics": [
          {
            "name": "<string>",
            "stat": "METRIC_STAT_TYPE_AVG",
            "percentile": 123,
            "check": "METRIC_CHECK_TYPE_THRESHOLD",
            "sourceValue": 123,
            "targetValue": 123,
            "threshold": 123,
            "operator": "THRESHOLD_OPERATOR_GT",
            "maxRegressionPercent": 123,
            "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
            "verdict": "METRIC_VERDICT_PASS",
            "failureReason": "<string>"
          }
        ],
        "startedAt": "2023-11-07T05:31:56Z",
        "completedAt": "2023-11-07T05:31:56Z",
        "failureReason": "<string>"
      }
    ],
    "condition": {
      "category": "ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION",
      "message": "<string>",
      "atStep": 123,
      "observedAt": "2023-11-07T05:31:56Z",
      "metrics": [
        {
          "name": "<string>",
          "stat": "METRIC_STAT_TYPE_AVG",
          "percentile": 123,
          "check": "METRIC_CHECK_TYPE_THRESHOLD",
          "sourceValue": 123,
          "targetValue": 123,
          "threshold": 123,
          "operator": "THRESHOLD_OPERATOR_GT",
          "maxRegressionPercent": 123,
          "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
          "verdict": "METRIC_VERDICT_PASS",
          "failureReason": "<string>"
        }
      ],
      "type": "CapacityLimited"
    },
    "updatedAt": "2023-11-07T05:31:56Z",
    "conditions": [
      {
        "category": "ROLLOUT_FAILURE_CATEGORY_METRIC_REGRESSION",
        "message": "<string>",
        "atStep": 123,
        "observedAt": "2023-11-07T05:31:56Z",
        "metrics": [
          {
            "name": "<string>",
            "stat": "METRIC_STAT_TYPE_AVG",
            "percentile": 123,
            "check": "METRIC_CHECK_TYPE_THRESHOLD",
            "sourceValue": 123,
            "targetValue": 123,
            "threshold": 123,
            "operator": "THRESHOLD_OPERATOR_GT",
            "maxRegressionPercent": 123,
            "direction": "REGRESSION_DIRECTION_HIGHER_IS_WORSE",
            "verdict": "METRIC_VERDICT_PASS",
            "failureReason": "<string>"
          }
        ],
        "type": "CapacityLimited"
      }
    ]
  },
  "currentStep": 123,
  "currentTrafficPercent": 123,
  "startedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "etag": "<string>",
  "pauseInfo": {
    "pausedAt": "2023-11-07T05:31:56Z",
    "reason": "<string>"
  },
  "maxSurge": 123,
  "maxUnavailable": 123
}

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

TOGETHER APIS

SDK LIBRARIES

ERROR CODES

Authorizations

Path Parameters

Response