Documentation | Deploy › List Agent Deployments

Deploy

deploy

Methods

Deploy A Built Agent Image ->

post/v5/agentex/deployments

Deploy a successfully built agent image to Kubernetes as a Helm release.

Takes a completed build (referenced by build_id, or by image_name + image_tag) together with the agent manifest and environment config, then starts an asynchronous Temporal workflow that provisions the agent as a Helm release. The call returns immediately with the deployment record in PENDING status — it does not wait for the release to become healthy; poll GET /v5/agentex/deployments/{deployment_id} for status and Kubernetes events and GET /v5/agentex/deployments/{deployment_id}/logs for progress. This is the deploy counterpart to POST /v5/agentex/builds: a build produces the container image, a deployment runs that image. The referenced build must have finished successfully, and the manifest's agent name must match the build's agent.

Set preview=True for an ephemeral deployment: it gets a globally unique Helm release name (so concurrent redeploys never collide), an optional preview_label for grouping, and an expiry (expires_at, defaulting to 8 hours from now); preview_label and expires_at are rejected on non-preview deploys. A non-preview (production) deploy instead supersedes any prior active deployment that shares its Helm release name. Fails with a client error if the build is missing or not in a successful state, if the manifest or environment YAML is invalid or their agent names disagree, or if a secret referenced by the manifest does not exist.

Get An Agent Deployment ->

AgentexCloudDeploy

get/v5/agentex/deployments/{deployment_id}

Get a single agent deployment by ID, including its current status and Kubernetes events.

Returns the deployment record with its latest status and the associated Kubernetes events (deploy_events) observed for the release, which are useful for diagnosing why a deployment is still pending or unhealthy. Poll this after POST /v5/agentex/deployments to track the asynchronous deploy to completion. For the incremental log output rather than status and events, use GET /v5/agentex/deployments/{deployment_id}/logs. Returns 404 if no deployment with this ID exists for the caller's account.

List Agent Deployments -> CursorPage<

AgentexCloudDeploy

get/v5/agentex/deployments

List the account's agent deployments, with pagination and optional filters.

Returns the deployments the caller is authorized to read. Optionally filter by build_id, by agent_name (matched through each deployment's associated build), or by preview_label. A preview_label is non-unique — many deployments can share one (for example every deploy for a branch) — so combine it with limit=1 to fetch the latest deployment for that label. This lists deployments (the running or attempted agent instances); to list the image builds they run, use the agentex builds API.

query Parameters

agent_name: string

Optional

Filter deployments by agent name (via associated build)

build_id: string

Optional

Filter deployments by build ID

ending_before: string

Optional

limit: number

Optional

(maximum: 10000, minimum: 1, default: 100)

preview_label: string

Optional

Filter deployments by preview label (e.g. branch name). The label is non-unique — many deployments can share it. Combine with limit=1 to get the latest deploy for that label.

sort_by: string

Optional

sort_order:

SortOrder

Optional

starting_after: string

Optional

Response fields

has_more: boolean

Whether there are more items left to be fetched.

items: Array<

AgentexCloudDeploy

total: number

The total of items that match the query. This is greater than or equal to the number of items returned.

limit: number

Optional

(default: 100)

The maximum number of items to return.

object: "list"

Optional

(default: "list")

Request example

curl https://api.egp.scale.com/v5/agentex/deployments \
    -H "x-api-key: $SGP_API_KEY"

200Example

{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "account_id": "account_id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "environment_config": "environment_config",
      "manifest_file": "manifest_file",
      "namespace": "namespace",
      "status": "status",
      "build_id": "build_id",
      "deploy_events": [
        {
          "message": "message",
          "reason": "reason",
          "timestamp": "2019-12-27T18:11:19.117Z",
          "type": "type"
        }
      ],
      "expires_at": "2019-12-27T18:11:19.117Z",
      "helm_release_name": "helm_release_name",
      "object": "agentex_cloud_deploy",
      "preview_label": "preview_label"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}

Get Agent Deployment Logs -> { deployment_id, has_more, lines, 1 more... }

get/v5/agentex/deployments/{deployment_id}/logs

Get structured deployment log lines, with cursor-based pagination.

Returns the deployment's log lines in time order together with a next_cursor and a has_more flag. Poll to stream logs incrementally: make the first call without a cursor, then pass the previous response's next_cursor as cursor on each subsequent call, stopping once the deployment reaches a terminal status. Unlike GET /v5/agentex/deployments/{deployment_id}, which returns the deployment's status and Kubernetes events, this returns the raw log output from the deploy process. Returns 404 if no deployment with this ID exists for the caller's account.

Delete And Tear Down A Deployment ->

AgentexCloudDeploy

delete/v5/agentex/deployments/{deployment_id}

Delete an agent deployment and tear down its Kubernetes resources.

Deletes the deployment's Kubernetes resources first, then marks the record as DELETED; the underlying Helm release is subsequently uninstalled asynchronously by FluxCD once the resource is removed. If the Kubernetes teardown fails, the record is left unchanged and the call errors, so the delete can be safely retried. Rejects the call with a client error if the deployment is already in a terminal state (DELETED, CANCELLED, or SUPERSEDED) — a SUPERSEDED record shares its Helm release with the deployment that replaced it, so deleting it would tear down the live release. Returns 404 if no deployment with this ID exists for the caller's account. This removes a running deployment, not the image build behind it, which is managed separately through the agentex builds API.

Domain types

AgentexCloudDeploy = { id, account_id, created_at, 11 more... }

AgentexCloudDeployEvent = { message, reason, timestamp, 1 more... }

Slim event representation for the API response.

DeployLogsResponse = { deployment_id, has_more, lines, 1 more... }

Response containing structured deployment log lines with cursor-based pagination.

The CLI can poll this endpoint to stream logs incrementally:

First call: no after_id
Subsequent calls: after_id=next_cursor from previous response
Stop polling when has_more is False and the deployment reaches a terminal status