Create a rollout

curl --request POST \
  --url https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts \
  --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"
    }
  ]
}
'

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

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

POST

projects

{projectId}

endpoints

{endpointId}

rollouts

curl --request POST \
  --url https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/rollouts \
  --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"
    }
  ]
}
'

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

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

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

⌘I

TOGETHER APIS

SDK LIBRARIES

ERROR CODES

Authorizations

Path Parameters

Body

Response