> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.modular.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List deployments

> List all deployments in the organization.



## OpenAPI

````yaml /reference/openapi-deployments.json get /v1/deployments
openapi: 3.1.0
info:
  title: Modular Cloud Deployments API
  version: 0.1.0
  description: >-
    REST API for Modular Cloud deployments. All endpoints are served at
    `https://api.modular.com`.


    Create and manage dedicated inference endpoints on Modular Cloud
    infrastructure.


    > **Not yet available.** Self-serve deployment is coming soon. [Sign up for
    private preview access](https://console.modular.com/signup) to be notified
    when it launches.
servers:
  - url: https://api.modular.com
security:
  - BearerAuth: []
tags:
  - name: Deployments
    description: >-
      Create and manage dedicated inference endpoints on Modular Cloud
      infrastructure.


      > **Not yet available.** Self-serve deployment is coming soon. [Sign up
      for private preview access](https://console.modular.com/signup) to be
      notified when it launches.
paths:
  /v1/deployments:
    get:
      tags:
        - Deployments
      summary: List deployments
      description: List all deployments in the organization.
      operationId: listDeployments
      parameters:
        - name: status
          in: query
          description: Filter by deployment status.
          schema:
            $ref: '#/components/schemas/DeploymentStatus'
        - name: model_id
          in: query
          description: Filter by model identifier.
          schema:
            type: string
        - name: sort
          in: query
          description: Sort field (e.g. `-created_at` for descending creation time).
          schema:
            type: string
      responses:
        '200':
          description: List of deployments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentListResponse'
      x-codeSamples:
        - lang: Python
          label: Python
          source: |-
            import os
            import requests

            response = requests.get(
                "https://api.modular.com/v1/deployments",
                headers={"Authorization": f"Bearer {os.environ['MODULAR_API_KEY']}"},
                params={"status": "running"},
            )

            deployments = response.json()
            for d in deployments["items"]:
                print(d["name"], d["status"])
        - lang: Shell
          label: curl
          source: |-
            curl https://api.modular.com/v1/deployments \
              -H "Authorization: Bearer $MODULAR_API_KEY"
components:
  schemas:
    DeploymentStatus:
      type: string
      enum:
        - unknown
        - non-deployed
        - deploying
        - running
        - unhealthy
        - failed
        - updating
        - scaling
        - terminating
        - terminated
        - image-building
        - image-build-failed
        - model-seed-failed
        - image-build-succeeded
        - scaled-to-zero
        - scaling-up
        - scaling-down
      description: Current lifecycle status of a deployment.
    DeploymentListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeploymentResponse'
        total:
          type: integer
          description: Total number of deployments matching the filter.
      required:
        - items
        - total
    DeploymentResponse:
      type: object
      properties:
        name:
          type: string
          description: Deployment name (the URL-safe slug).
        display_name:
          type: string
        deployment_id:
          type: string
          description: Unique deployment identifier.
        model_id:
          type: string
          description: Model identifier.
        status:
          $ref: '#/components/schemas/DeploymentStatus'
        endpoint_url:
          type: string
          nullable: true
          description: Inference endpoint URL. Null until the deployment is running.
        region_group:
          type: string
        scaling:
          $ref: '#/components/schemas/DeploymentScaling'
        configuration:
          $ref: '#/components/schemas/DeploymentConfiguration'
        replicas:
          $ref: '#/components/schemas/ReplicaStatus'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
      required:
        - name
        - deployment_id
        - model_id
        - status
        - scaling
        - configuration
        - created_at
        - created_by
        - updated_at
        - updated_by
    DeploymentScaling:
      type: object
      properties:
        min_replicas:
          type: integer
          description: Minimum number of running replicas.
        max_replicas:
          type: integer
          description: Maximum number of running replicas.
        behavior:
          $ref: '#/components/schemas/ScalingBehavior'
      required:
        - min_replicas
        - max_replicas
    DeploymentConfiguration:
      type: object
      properties:
        model_path:
          type: string
          description: >-
            Model identifier passed to the inference engine (typically the same
            as `model_id`).
        engine:
          type: string
          description: Inference engine. Use `"max"` for the MAX engine.
          example: max
        mode:
          type: string
          description: Optional deployment mode override.
      required:
        - model_path
    ReplicaStatus:
      type: object
      properties:
        current:
          type: integer
          description: Number of currently running replicas.
        desired:
          type: integer
          description: Number of desired replicas.
      required:
        - current
        - desired
    ScalingBehavior:
      type: object
      properties:
        scale_up:
          $ref: '#/components/schemas/ScalingWindowConfig'
        scale_down:
          $ref: '#/components/schemas/ScalingWindowConfig'
    ScalingWindowConfig:
      type: object
      properties:
        stabilization_window_seconds:
          type: integer
          description: Seconds to wait before acting on scale signals.
      required:
        - stabilization_window_seconds
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Modular Cloud API token. Obtain from the [API Tokens
        page](https://console.modular.com/api_tokens).

````