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

# List deployments

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

## Request

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

Lists the deployments attached to an endpoint, including their model, configuration, scaling settings, placement, and current status.

## Path parameters

- `projectId` string, required: ID of the project that owns the endpoint.
- `endpointId` string, required: ID of the endpoint whose deployments are listed.

## Query parameters

- `limit` integer: Maximum number of deployments to return. Max 500, defaults to 50.
- `after` string: Cursor from a previous deployment list response.
- `orderBy` string: Sort field for the results. Supports `created_at` or `updated_at`, optionally followed by `asc` or `desc`.
- `filter` string: Filter expression using `name`, `state`, `model`, `created_at`, or `updated_at` with comparison operators and AND/OR/NOT; `state` takes a DeploymentState enum name and `model` takes a model resource name. `name` supports substring matching with `:` and prefix/suffix wildcards with `*`, and accepts a bare deployment name or `<project_slug>/<endpoint_name>/<deployment_name>`.

## Response `200`

OK

- DEListDeploymentsResponse: Deployments under an endpoint and pagination metadata.
  - `data` DEDeployment[], required: The list of deployments.
    - `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.
  - `next_cursor` string: Cursor for the next page. Null if there are no more results.
  - `object` 'list', required: Object type. Always `list`.

## 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/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)