API Reference List Builds
List Builds
List a project's builds, newest first, with filters for branch, status and preview.
API key or session token
Returns a page of builds for a project, newest first. Filter by branch, status or preview to drive a deployments view or a CI status check.
Note
Any workspace member (session JWT), or an API key bound to this project with the read scope or higher. Any plan.
Path Parameters
NameDescription
projectIdThe project ID (e.g.,
3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Query Parameters
NameDescription
pagePage number, from
1 to 10000.Default
1pageSizeBuilds per page, from
1 to 100.Default
20branchOnly builds of this branch (exact match, up to 255 characters).
statusComma-separated list of statuses:
queued, uploading, cloning, parsing, compiling, deploying, deployed, failed, cancelled. The shorthand active expands to every in-progress status (queued, uploading, cloning, parsing, compiling, deploying). For example, status=active,failed.isPreviewtrue for preview builds only, false for production builds only. Omit for both.An unknown status, a page or pageSize out of range, or an isPreview other than true / false returns 400 validation_error.
Response
NameDescription
dataBuild objects — the same fields as Get Build, without
logs. Each row carries triggeredBy, warnings, degraded and progress — { done, total } pages compiled while the build runs, null otherwise (see Get Build). Read a build's log with GET …/builds/{buildId}/logs.paginationShow 3 child attributesobject
pageThe page returned.
pageSizeThe page size used.
totalNumber of builds matching the filters, across all pages.
Error Responses
| Status | error.code | When |
|---|---|---|
| 400 | validation_error | A query parameter is invalid. details maps the parameter to its errors |
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 403 | forbidden | You are not a member of the project's workspace, or the API key's scope is below read |
| 404 | not_found | The project does not exist or is deleted, or the API key belongs to another project |
400 Bad Request
json
{
"error": {
"code": "validation_error",
"message": "Invalid build list query",
"details": {
"status": ["Unknown status \"building\""],
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
Was this page helpful? Yes No
Previous
Next
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10" \
-H "Authorization: Bearer stx_abc12345_..."
const response = await fetch('https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10', {
method: 'GET',
headers: {
'Authorization': 'Bearer stx_abc12345_...',
},
});
const data = await response.json();
console.log(response.status, data);
import requests
url = "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10"
headers = {
"Authorization": "Bearer stx_abc12345_...",
}
response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json())
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer stx_abc12345_...")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status)
fmt.Println(string(body))
}
require "net/http"
require "uri"
uri = URI("https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer stx_abc12345_..."
response = http.request(request)
puts response.code
puts response.body
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10',
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer stx_abc12345_...',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status, PHP_EOL, $response, PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10"))
.header("Authorization", "Bearer stx_abc12345_...")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http;
using System.Text;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds?status=active,failed&isPreview=false&pageSize=10");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer stx_abc12345_...");
using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
Responseapplication/json
200OK
{
"data": [
{
"id": "bld_xyz789",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"priority": 0,
"status": "compiling",
"trigger": "push",
"commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"commitMessage": "Update API documentation",
"filesChanged": ["docs/api-reference/overview.mdx"],
"branch": "main",
"isPreview": false,
"deployUrl": null,
"error": null,
"pageCount": null,
"durationMs": null,
"contentHash": null,
"sourcePath": null,
"deployId": null,
"warnings": 0,
"degraded": [],
"triggeredByUserId": "usr_abc123",
"createdAt": "2026-11-08T10:00:00Z",
"startedAt": "2026-11-08T10:00:01Z",
"completedAt": null,
"triggeredBy": {
"id": "usr_abc123",
"name": "Ada Lovelace",
"avatarUrl": "https://avatars.githubusercontent.com/u/1234567"
},
"progress": { "done": 88, "total": 142 }
},
{
"id": "bld_abc456",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"priority": 0,
"status": "failed",
"trigger": "manual",
"commitSha": null,
"commitMessage": null,
"filesChanged": null,
"branch": "main",
"isPreview": false,
"deployUrl": null,
"error": "MDX compilation failed in docs/quickstart.mdx",
"pageCount": null,
"durationMs": 3891,
"contentHash": null,
"sourcePath": null,
"deployId": null,
"warnings": 0,
"degraded": [],
"triggeredByUserId": null,
"createdAt": "2026-11-07T15:30:00Z",
"startedAt": "2026-11-07T15:30:01Z",
"completedAt": "2026-11-07T15:30:05Z",
"triggeredBy": null,
"progress": null
}
],
"pagination": {
"page": 1,
"pageSize": 10,
"total": 2
}
}