---
title: List Builds
protocol: rest
method: GET
endpoint: /v1/projects/{projectId}/builds
description: "List all builds for a project"
---

# List Builds

Returns a paginated list of builds for a project, ordered by most recent first.

<Endpoint method="GET" path="/v1/projects/{projectId}/builds" />

## Path Parameters

<ParamField path="projectId" type="string" required>
  The project ID (e.g., `prj_abc123`).
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  Number of results per page. Maximum: `100`.
</ParamField>

<ParamField query="status" type="string">
  Filter by build status. One of: `queued`, `building`, `deployed`, `failed`.
</ParamField>

<ParamField query="branch" type="string">
  Filter by Git branch name.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of build objects.

  <Expandable title="Build object">
    <ResponseField name="id" type="string">
      Build identifier (e.g., `bld_abc123`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Build status: `queued`, `building`, `deployed`, `failed`.
    </ResponseField>

    <ResponseField name="trigger" type="string">
      What triggered the build: `push`, `manual`, `api`, `github_app`.
    </ResponseField>

    <ResponseField name="branch" type="string">
      Git branch that was built.
    </ResponseField>

    <ResponseField name="commitSha" type="string">
      Git commit SHA.
    </ResponseField>

    <ResponseField name="commitMessage" type="string">
      Git commit message.
    </ResponseField>

    <ResponseField name="isPreview" type="boolean">
      Whether this is a preview deployment.
    </ResponseField>

    <ResponseField name="url" type="string">
      Deployed URL for this build.
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Build duration in milliseconds.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="deployedAt" type="string">
      ISO 8601 timestamp when deployment completed.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
```bash cURL
curl https://api.syntext.dev/v1/projects/prj_abc123/builds \
  -H "Authorization: Bearer stx_abc12345_..."
```

```typescript SDK
import { Syntext } from '@syntext/sdk'

const client = new Syntext('stx_abc12345_...')
const { data } = await client.builds.list('prj_abc123')
```

```python Python
from syntext import Syntext

client = Syntext("stx_abc12345_...")
builds = client.builds.list("prj_abc123")
```
</CodeGroup>

### Response

```json
{
  "data": [
    {
      "id": "bld_xyz789",
      "status": "deployed",
      "trigger": "push",
      "branch": "main",
      "commitSha": "a1b2c3d4e5f6",
      "commitMessage": "Update API documentation",
      "isPreview": false,
      "url": "https://api-docs-docs.syntext.dev",
      "duration": 4523,
      "createdAt": "2026-06-28T10:00:00Z",
      "deployedAt": "2026-06-28T10:00:05Z"
    },
    {
      "id": "bld_abc456",
      "status": "deployed",
      "trigger": "github_app",
      "branch": "feature/new-endpoints",
      "commitSha": "f6e5d4c3b2a1",
      "commitMessage": "Add new endpoints section",
      "isPreview": true,
      "url": "https://dev--api-docs.syntext.dev",
      "duration": 3891,
      "createdAt": "2026-06-27T15:30:00Z",
      "deployedAt": "2026-06-27T15:30:04Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 47,
    "totalPages": 3
  }
}
```