> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "List deployments"
description: "List deployments the authenticated user can access."
method: "GET"
endpoint: "/api/v1/deployments"
order: 1
last_verified: 2026-07-27
---

<ApiEndpoint
  method="GET"
  endpoint="/api/v1/deployments"
  description="List deployments the authenticated user can access."
>
  <section>
    ### Query parameters

    <ApiAttribute name="project_id" type="string" description="Filter to a single project." required={false} />
    <ApiAttribute name="status" type="string" description="Filter by deployment status, e.g. running, failed, terminated." required={false} />
    <ApiAttribute name="kind" type="string" description="managed or dev. Defaults to managed; pass include_dev=true to see both." required={false} />
    <ApiAttribute name="ref" type="string" description="Filter by deployment ref." required={false} />
    <ApiAttribute name="trace_id" type="string" description="Filter to the deployment associated with a trace." required={false} />
    <ApiAttribute name="promoted" type="boolean" description="Filter to only deployments promoted from another deployment." required={false} />
    <ApiAttribute name="page" type="integer" description="Page number. Defaults to 1." required={false} />
    <ApiAttribute name="page_size" type="integer" description="Results per page, 1-100. Defaults to 20." required={false} />
  </section>

  <Callout type="warning">
`env` and `version` are accepted but not implemented server-side — passing them has no effect on the results. Filter by environment or version client-side using the `env` and `version` fields on each returned deployment.
  </Callout>

  <section>
    ### Request example

    <MultiLanguageCodeBlock
      languages={["bash", "javascript"]}
      value={[
        {
          language: 'bash',
          code: `curl "https://api.agnt5.com/api/v1/deployments?project_id=b6f1a3e2-9c4d-4f7a-8e2b-1a2b3c4d5e6f&status=running" \\
  -H "X-API-KEY: {api_key}"`
        },
        {
          language: 'javascript',
          code: `fetch(\`https://api.agnt5.com/api/v1/deployments?project_id=\${projectId}&status=running\`, {
  headers: { 'X-API-KEY': apiKey }
})`
        }
      ]}
    />

    ```json {{ title: 'Response' }}
    {
      "success": true,
      "message": "Deployments retrieved successfully",
      "data": [
        {
          "id": "8a1c2d3e-...",
          "name": "invoice-processor-production",
          "kind": "managed",
          "endpoint": "https://invoice-processor.deployments.agnt5.com",
          "status": "running",
          "version": "1.4.2",
          "env": "production",
          "git_sha": "a1b2c3d",
          "project_id": "b6f1a3e2-9c4d-4f7a-8e2b-1a2b3c4d5e6f",
          "deployed_by": "3f2b1a0c-...",
          "created": 1753612800000,
          "updated": 1753612800000,
          "started": 1753612830000,
          "max_replicas": 4,
          "min_replicas": 1,
          "active_replicas": 1,
          "failed_replicas": 0,
          "promoted": true,
          "eval_gate_enforcement": "off"
        }
      ],
      "metadata": { "count": 1, "page": 1, "hasNext": false, "hasPrev": false }
    }
    ```
  </section>
</ApiEndpoint>