/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference List Builds

List Builds

List a project's builds, newest first, with filters for branch, status and preview.

GET/v1/projects/{projectId}/buildsTry it
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
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).

Query Parameters

NameDescription
page:integerquery
Page number, from 1 to 10000.
Default1
pageSize:integerquery
Builds per page, from 1 to 100.
Default20
branch:stringquery
Only builds of this branch (exact match, up to 255 characters).
status:stringquery
Comma-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.
isPreview:stringquery
true 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
data:array
Build 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.
pagination:object
Show 3 child attributesobject

Error Responses

Statuserror.codeWhen
400validation_errorA query parameter is invalid. details maps the parameter to its errors
401unauthorizedNo credential, or an invalid, revoked or expired one
403forbiddenYou are not a member of the project's workspace, or the API key's scope is below read
404not_foundThe 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
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_..."
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
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext