---
title: "Roll back a deployment to a previous revision"
method: POST
path: "/v1/deployments/{id}/rollback"
tags: ["Deployments"]
---

# Roll back a deployment to a previous revision

`POST /v1/deployments/{id}/rollback`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v1/deployments/{id}/rollback`
- Auth: HTTP bearer

Re-applies the spec of a previous revision. Pods running the target revision will be retained. Other pods will be drained and restarted with the target revision.
Only the 50 most recent revisions per deployment can be rolled back to; older targets return 404.

## Path parameters

- `id` string, required: Deployment ID or name.

## Request body

- RollbackDeploymentRequest: Request body identifying the deployment revision to roll back to.
  - `revision_identifier` string, required: Revision number or revision ID to roll back to.

## Response `200`

Deployment after rollback

- DeploymentResponseItem
  - `args` string[]: Args are the arguments passed to the container's command
  - `autoscaling` union: Autoscaling contains autoscaling configuration parameters for this deployment. Omitted when autoscaling is disabled (nil)
    - HTTPAutoscalingConfig: Autoscaling config for HTTPTotalRequests and HTTPAvgRequestDuration metrics
      - `metric` 'HTTPTotalRequests' | 'HTTPAvgRequestDuration': Metric must be HTTPTotalRequests or HTTPAvgRequestDuration
      - `target` number: Target is the threshold value. Default: 100 for HTTPTotalRequests, 500 (ms) for HTTPAvgRequestDuration
      - `time_interval_minutes` integer: TimeIntervalMinutes is the rate window in minutes. Default: 10
    - QueueAutoscalingConfig: Autoscaling config for QueueBacklogPerWorker metric
      - `metric` 'QueueBacklogPerWorker': Metric must be QueueBacklogPerWorker
      - `model` string: Model overrides the model name for queue status lookup. Defaults to the deployment app name
      - `target` number: Target is the threshold value. Default: 1.01
    - CustomMetricAutoscalingConfig: Autoscaling config for CustomMetric metric
      - `custom_metric_name` string: CustomMetricName is the Prometheus metric name. Must match [a-zA-Z_:][a-zA-Z0-9_:]*
      - `metric` 'CustomMetric': Metric must be CustomMetric
      - `target` number: Target is the threshold value. Default: 500
  - `capacity_type` 'stable' | 'preemptible': Controls how replicas above reserved capacity behave. `stable` replicas stay running after scale-up; `preemptible` replicas may be evicted during capacity contention.
  - `command` string[]: Command is the entrypoint command run in the container
  - `cpu` number: CPU is the amount of CPU resource allocated to each replica in cores (fractional value is allowed)
  - `created_at` string, date-time: CreatedAt is the ISO8601 timestamp when this deployment was created
  - `description` string: Description provides a human-readable explanation of the deployment's purpose or content
  - `desired_replicas` integer: DesiredReplicas is the number of replicas that the orchestrator is targeting
  - `environment_variables` EnvironmentVariable[]: EnvironmentVariables is a list of environment variables set in the container
    - `name` string, required: Name is the environment variable name (e.g., "DATABASE_URL"). Must start with a letter or underscore, followed by letters, numbers, or underscores
    - `value` string: Value is the plain text value for the environment variable. Use this for non-sensitive values. Either Value or ValueFromSecret must be set, but not both
    - `value_from_secret` string: ValueFromSecret references a secret by name or ID to use as the value. Use this for sensitive values like API keys or passwords. Either Value or ValueFromSecret must be set, but not both
    - `value_from_secret_expires_at` string, date-time: ValueFromSecretExpiresAt is the ISO8601 timestamp when the referenced secret expires and is deleted. Read-only, ignored in requests
  - `gpu_count` integer: GPUCount is the number of GPUs allocated to each replica in this deployment
  - `gpu_type` 'h100-80gb' | 'h100-40gb-mig' | 'h200-140gb' | 'b200-192gb': GPUType specifies the type of GPU requested (if any) for this deployment
  - `health_check_path` string: HealthCheckPath is the HTTP path used for health checks of the application
  - `id` string: ID is the unique identifier of the deployment
  - `image` string: Image specifies the container image used for this deployment
  - `max_replicas` integer: MaxReplicas is the maximum number of replicas to run for this deployment
  - `memory` number: Memory is the amount of memory allocated to each replica in GiB (fractional value is allowed)
  - `min_replicas` integer: MinReplicas is the minimum number of replicas to run for this deployment
  - `model_mounts` ModelMount[]: Model weights mounted into this deployment, including the pinned revisions.
    - `model_id` string, required: Model registry identifier (`ml_...`) whose weights are mounted.
    - `mount_path` string, required: Container path where model weights are mounted, such as `/models`.
    - `revision_id` string: Optional validated revision identifier (`rv_...`) to pin; defaults to the latest validated revision.
  - `name` string: Name is the name of the deployment
  - `object` 'deployment': The object type, which is always `deployment`.
  - `port` integer: Port is the container port that the deployment exposes
  - `ready_replicas` integer: ReadyReplicas is the current number of replicas that are in the Ready state
  - `replica_events` object: ReplicaEvents is a mapping of replica names or IDs to their status events
  - `status` 'Updating' | 'Scaling' | 'Ready' | 'Failed' | 'ScaledToZero'
  - `storage` integer: Storage is the amount of storage (in MB or units as defined by the platform) allocated to each replica
  - `termination_grace_period_seconds` integer: TerminationGracePeriodSeconds is the time in seconds to wait for graceful shutdown before forcefully terminating the replica
  - `updated_at` string, date-time: UpdatedAt is the ISO8601 timestamp when this deployment was last updated
  - `volumes` VolumeMount[]: Volumes is a list of volume mounts for this deployment
    - `mount_path` string, required: MountPath is the path in the container where the volume mounts (e.g., "/data").
    - `name` string, required: Name is the name of the volume to mount. Must reference an existing volume by name or ID
    - `version` integer: Version is the volume version to mount. On create, defaults to the latest version. On update, defaults to the currently mounted version.

## Other responses

- `400`: Invalid request
- `404`: Deployment not found, or revision not found / no longer retained
- `500`: Internal server error

## Changes

- **2026-10-28** `93438ddac711`: 1 info
  - added the optional property `environment_variables/items/value_from_secret_expires_at` to the response with the `200` status
- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v1/deployments/:id/rollback/post.md)

---

[API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/93438ddac711?raw)