GET /api/v1/deployments/:id — Get a Single Deployment

The Get Deployment endpoint retrieves every piece of information stored for a single deployment run — its current status, associated project, build logs, public URL, and more. The lookup is ownership-scoped: a deployment is only returned if it belongs to a project owned by the authenticated user, preventing unauthorized access to other users’ deployment data.

`GET /api/v1/deployments/:id`

This endpoint requires an active session. Authentication is handled via a session cookie issued after sign-in. See the Authentication reference for details.

Request

Path Parameters

string

required

The CUID of the deployment to retrieve (e.g., clxyz123abc456def). CUIDs are returned in the id field of any deployment object from the List Deployments endpoint.

Response

A successful response returns HTTP 200 with the following shape:

{
  "message": "Deployment fetched successfully",
  "data": {
    "deployment": { /* single Deployment object with embedded project */ }
  }
}

Deployment fields

data.deployment

object

The full deployment record.

Show Deployment object

string

CUID uniquely identifying this deployment.

projectId

string

CUID of the parent project.

branch

string

The Git branch that was deployed (e.g., main).

commitHash

string | null

Full SHA of the deployed commit. null if not available at the time the deployment record was created.

status

DeploymentStatus

Current lifecycle stage. One of:

Value	Meaning
`PENDING`	Job is queued, not yet started
`CLONING`	Repository is being cloned
`DETECTING`	Framework / runtime is being auto-detected
`ALLOCATING`	A container port is being allocated
`BUILDING`	Docker image is being built
`DEPLOYING`	Container is starting up
`SUCCESS`	Deployment is live and healthy
`FAILED`	Deployment ended with an error

url

string | null

Public URL of the live deployment. Populated only once status reaches SUCCESS.

port

integer | null

Internal container port allocated for this deployment. null until the ALLOCATING stage completes.

logs

string | null

Stored log output from the build and deploy pipeline. Available after the deployment completes. For live streaming during an active deployment, use the Deployment Logs SSE endpoint.

error

string | null

Error message describing why the deployment failed. null for non-failed deployments.

createdAt

string (ISO 8601)

Timestamp when the deployment record was created.

updatedAt

string (ISO 8601)

Timestamp of the most recent update to this record.

completedAt

string | null (ISO 8601)

Timestamp when the deployment reached a terminal state (SUCCESS or FAILED). null while still in progress.

project

object

Full project object embedded in the response. Key fields include id, name, repositoryFullName, defaultBranch, deploymentUrl, buildCommand, startCommand, and rootDirectory.

Example

curl -X GET https://your-domain.com/api/v1/deployments/clxyz123abc456def \
  -H "Cookie: session=<your-session-token>"

Example response:

{
  "message": "Deployment fetched successfully",
  "data": {
    "deployment": {
      "id": "clxyz123abc456def",
      "projectId": "clproj789ghi012jkl",
      "branch": "main",
      "commitHash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "status": "FAILED",
      "url": null,
      "port": null,
      "logs": "[SYSTEM] Cloning repository...\n[SYSTEM] Detecting framework...\n...",
      "error": "Build command exited with code 1",
      "createdAt": "2024-11-01T14:22:00.000Z",
      "updatedAt": "2024-11-01T14:23:15.000Z",
      "completedAt": "2024-11-01T14:23:15.000Z",
      "project": {
        "id": "clproj789ghi012jkl",
        "name": "my-app",
        "repositoryFullName": "acme-org/my-app",
        "defaultBranch": "main",
        "deploymentUrl": null,
        "buildCommand": "npm run build",
        "startCommand": "npm start",
        "rootDirectory": null
      }
    }
  }
}

Error Responses

Status	Error	Description
`401`	`Unauthorized`	No valid session cookie was provided.
`404`	`Deployment not found`	No deployment with the given `id` exists, or it belongs to a different user’s project.
`500`	`Failed to fetch deployment`	An unexpected server-side error occurred.

Overview

Projects

Deployments

Webhooks

GET /api/v1/deployments/:id — Get a Single Deployment