---
title: "Get a deployment"
method: GET
path: "/v2/projects/{projectId}/endpoints/{endpointId}/deployments/{id}"
tags: ["DeploymentService"]
---

# Get a deployment

`GET /v2/projects/{projectId}/endpoints/{endpointId}/deployments/{id}`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v2/projects/{projectId}/endpoints/{endpointId}/deployments/{id}`
- Auth: HTTP bearer

Retrieves a deployment's desired configuration, placement, runtime information, and current provisioning status.

## Path parameters

- `projectId` string, required: Project identifier.
- `endpointId` string, required: Endpoint identifier.
- `id` string, required: Deployment identifier.

## Response `200`

OK

- DEDeployment: Serving workload that binds a model and immutable config to an endpoint and manages its replicas.
  - `id` string, required: Unique deployment identifier.
  - `projectId` string, required: ID of the project that owns the deployment.
  - `endpointId` string, required: ID of the endpoint that contains the deployment.
  - `name` string, required: Project- and endpoint-qualified deployment name in the form `<project_slug>/<endpoint_name>/<deployment_name>`. Pass it as `model` in an inference request to target this deployment directly instead of using the endpoint's traffic split.
  - `createdAt` string, date-time, required: Timestamp when the deployment was created.
  - `updatedAt` string, date-time, required: Timestamp when the deployment was last updated.
  - `modelId` string, required: Deprecated. Use `model`. Model identifier being served, populated during migration.
  - `modelRevisionId` string, required: Deprecated. Use `model` with a /revisions/{revisionId} segment. Pin to a specific model revision.
  - `model` string, required: Pinned model resource in the form `projects/{projectId}/models/{modelId}/revisions/{revisionId}`.
  - `autoscaling` DEAutoscalingResponse, required: Autoscaling configuration for a deployment.
    - `minReplicas` integer, required: Minimum number of replicas. Omit on update to preserve the current value. Set both `minReplicas` and `maxReplicas` to `0` to stop the deployment.
    - `maxReplicas` integer, required: Maximum number of replicas. Defaults to `minReplicas`; omitting it on update preserves the current value.
    - `scaleDownWindow` string: Time a lower replica recommendation must remain stable before scaling down. Defaults to `5m`.
    - `scaleUpWindow` string: Stabilization window before scaling up.
    - `scaleToZeroWindow` string: Idle period after which the deployment automatically stops and releases its replicas.
    - `scalingMetrics` DEScalingMetric[]: Metrics and targets that drive replica recommendations. When omitted, the platform uses concurrent in-flight requests per replica.
      - `name` 'active_sessions' | 'cache_hit_rate' | 'decoding_speed' | 'e2e_latency' | 'gpu_utilization' | 'inflight_requests' | 'throughput_per_replica' | 'token_utilization' | 'ttft', required: Autoscaling metric name from the server allowlist.
      - `type` 'METRIC_TARGET_TYPE_VALUE' | 'METRIC_TARGET_TYPE_UTILIZATION' | 'METRIC_TARGET_TYPE_AVERAGE_VALUE', required: Whether `target` is an absolute value, a utilization percentage, or a per-replica average.
      - `target` number, required: Target interpreted according to `type`. Utilization uses a percentage from 0 to 100, value uses an absolute measurement, and average value uses a per-replica measurement.
      - `percentile` string: Percentile to evaluate for latency-based metrics: `p50`, `p90`, `p95`, or `p99`.
    - `scaleUp` DEScalingRules: Rate limits applied after stabilization and before replica bounds.
      - `policies` DEScalingPolicy[]: Non-empty lists replace the existing policies. To clear policies, include `autoscaling.scaleDown.policies` or `autoscaling.scaleUp.policies` in the update mask and supply an empty scaling rules object or `policies: []`.
        - `type` 'SCALING_POLICY_TYPE_PODS' | 'SCALING_POLICY_TYPE_PERCENT', required: Whether `value` is a replica count or a percentage of the replica count at the start of the trailing period. Scaling events within that period count against the allowance; percentages are rounded to whole replicas.
        - `value` integer, required: Positive replica count or percentage used as the rate-limit amount.
        - `periodSeconds` integer, required: Trailing rate-limit window in seconds, from 1 to 1800.
      - `selectPolicy` 'SCALING_POLICY_SELECT_MAX' | 'SCALING_POLICY_SELECT_MIN' | 'SCALING_POLICY_SELECT_DISABLED': `SCALING_POLICY_SELECT_MIN` chooses the policy allowing the smallest replica change; `SCALING_POLICY_SELECT_MAX` chooses the largest. These are caps, not guaranteed changes. `SCALING_POLICY_SELECT_DISABLED` holds this direction steady while replica bounds still apply. Omitted preserves the existing selector on update. When no selector is configured, authored policies use MAX; with no policies configured, the platform defaults apply. To reset the selector, include `autoscaling.scaleDown.selectPolicy` or `autoscaling.scaleUp.selectPolicy` in the update mask and omit `selectPolicy`. Clear both policies and `selectPolicy` to restore inherited defaults.
    - `scaleDown` DEScalingRules: Rate limits applied after stabilization and before replica bounds.
      - `policies` DEScalingPolicy[]: Non-empty lists replace the existing policies. To clear policies, include `autoscaling.scaleDown.policies` or `autoscaling.scaleUp.policies` in the update mask and supply an empty scaling rules object or `policies: []`.
        - `type` 'SCALING_POLICY_TYPE_PODS' | 'SCALING_POLICY_TYPE_PERCENT', required: Whether `value` is a replica count or a percentage of the replica count at the start of the trailing period. Scaling events within that period count against the allowance; percentages are rounded to whole replicas.
        - `value` integer, required: Positive replica count or percentage used as the rate-limit amount.
        - `periodSeconds` integer, required: Trailing rate-limit window in seconds, from 1 to 1800.
      - `selectPolicy` 'SCALING_POLICY_SELECT_MAX' | 'SCALING_POLICY_SELECT_MIN' | 'SCALING_POLICY_SELECT_DISABLED': `SCALING_POLICY_SELECT_MIN` chooses the policy allowing the smallest replica change; `SCALING_POLICY_SELECT_MAX` chooses the largest. These are caps, not guaranteed changes. `SCALING_POLICY_SELECT_DISABLED` holds this direction steady while replica bounds still apply. Omitted preserves the existing selector on update. When no selector is configured, authored policies use MAX; with no policies configured, the platform defaults apply. To reset the selector, include `autoscaling.scaleDown.selectPolicy` or `autoscaling.scaleUp.selectPolicy` in the update mask and omit `selectPolicy`. Clear both policies and `selectPolicy` to restore inherited defaults.
  - `configId` string, required: Deprecated. Use `config`. Config revision identifier, populated during migration.
  - `config` string, required: Immutable config revision in the form `projects/{projectId}/configs/{configRevisionId}`.
  - `speculatorId` string: Deprecated. Use `speculator`. Speculative decoding model identifier derived from the deployment config.
  - `speculatorRevisionId` string: Deprecated. Use `speculator`. ID of the speculative decoding draft-model revision pinned at creation time.
  - `speculator` string: Pinned draft-model resource used for speculative decoding, in the same form as `model`. Omitted when speculative decoding is disabled.
  - `estimatedEffectiveTrafficShare` number, double: Estimated fraction in [0, 1] of endpoint traffic that reaches this deployment under the current routing configuration. Absent or unrouted deployments are 0.
  - `maxConcurrentRequestsPerReplica` string: Maximum number of inference requests that may be in flight to a single replica. If omitted, the platform uses one less than the config's per-replica concurrency limit to reserve a health-check slot. Values above that maximum are reduced on create and update; 0 means unlimited when the config limit is 1 or less. Changes take effect without restarting replicas.
  - `inactiveTimeout` integer: Minutes without an inference request before the deployment stops automatically. Omitted or 0 means automatic stopping is disabled.
  - `etag` string, required: Opaque version tag for optimistic concurrency control. Supply on update/delete to ensure consistent read-modify-write. If not set, the write overwrites based on current state.
  - `hardware` string, required: Hardware selected by the deployment config, including GPU type and count.
  - `trafficMode` 'TRAFFIC_MODE_LIVE' | 'TRAFFIC_MODE_SHADOW', required: Whether the deployment serves client-visible responses or only mirrored shadow traffic.
  - `runtimeInfo` DERuntimeInfo: Runtime information derived from the deployment's configuration.
    - `engineType` string: Serving engine, such as `vllm`, `trtllm`, or `sglang`.
    - `engineVersion` string: Version of the serving engine.
    - `functionCallingSupported` boolean: Whether the runtime accepts tool and function-calling requests.
    - `structuredOutputSupported` boolean: Whether the runtime can constrain generation to a structured output schema.
  - `desiredReplicas` integer: Number of replicas the autoscaler currently wants across all regions. Not settable on any request; steer it through `autoscaling.minReplicas` and `autoscaling.maxReplicas`.
  - `status` DEDeploymentStatus, required: Current status of a deployment, derived at read time from internal state.
    - `state` 'DEPLOYMENT_STATE_PROVISIONING' | 'DEPLOYMENT_STATE_READY' | 'DEPLOYMENT_STATE_SCALING' | 'DEPLOYMENT_STATE_DEGRADED' | 'DEPLOYMENT_STATE_FAILED' | 'DEPLOYMENT_STATE_STOPPED' | 'DEPLOYMENT_STATE_STOPPING', required: High-level lifecycle state.
    - `readyReplicas` integer: Total replicas actively serving traffic across all clusters.
    - `message` string, required: Human-readable explanation of the current state.
    - `scheduledReplicas` integer: Replicas the scheduler has placed on clusters.
    - `details` DEStatusDetails: Deployment status broken down by each supported dimension.
      - `region` DERegionStatus[], required: Regions where the deployment is actually scheduled or serving replicas, sorted by region.
        - `region` string, required: Region name using the same vocabulary accepted by inline placement regions.
        - `scheduledReplicas` integer, required: Replicas the scheduler has placed in this region.
        - `readyReplicas` integer, required: Replicas serving traffic in this region.
  - `placement` union: Placement controls where a deployment is scheduled.
    - object
      - `inline` DEInlinePlacement, required: Inline placement parameters expanded into scheduling rules by the server.
        - `regions` string[]: Regions where the deployment is allowed to run. Multiple regions allow best-effort replica spreading.
        - `constraint` 'ENFORCEMENT_REQUIRED' | 'ENFORCEMENT_PREFERRED': How strictly the regions list is enforced.
        - `compliancePolicy` DECompliancePolicy: Compliance regimes required by a deployment placement policy.
          - `hipaa` boolean: Restrict placement to HIPAA-attested clusters.
    - object
      - `profile` string, required: UID of a saved placement profile.

## Other responses

- `default`: Default error response

## Changes

- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v2/projects/:projectId/endpoints/:endpointId/deployments/:id/get.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)