/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Get Build

Get Build

Get one build, including its log, and read or stream build logs.

GET/v1/projects/{projectId}/builds/{buildId}Try it
API key or session token

Retrieve one build of a project, including its persisted log and who started it.

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).
buildId:stringpathRequired
The build ID (e.g., bld_xyz789). It must belong to projectId.

Response

NameDescription
data:object
The build.
Show 27 child attributesobject

Build logs

Two more endpoints read a build's log. Both take the same path parameters, need the same access (member, or an API key with read), and return 404 not_found for a build that is not in the project.

Read the log

GET/v1/projects/{projectId}/builds/{buildId}/logs

Returns { data: { logs, complete } }. While the build runs, logs holds the lines written so far and complete is false. Once the build is deployed, failed or cancelled, logs is the persisted log and complete is true. Poll until complete is true to follow a build without a stream.

json
{
"data": {
"logs": [
{ "timestamp": "2026-11-08T10:00:00Z", "level": "info", "message": "Build started", "stage": "cloning" },
{ "timestamp": "2026-11-08T10:00:02Z", "level": "warn", "message": "Cancelled by Ada Lovelace", "stage": "cancelled" }
],
"complete": true
}
}

Stream the log

GET/v1/projects/{projectId}/builds/{buildId}/logs/stream

A server-sent event stream. For a running build it sends the lines written so far, then stays open and sends each new line until the build ends. Events:

EventDataWhat to do
logOne JSON log entry, redacted like GET …/logsAppend it
completedeployed, failed or cancelledThe build is over; the stream closes
heartbeatEmpty, every 15 secondsIgnore it
timeoutEmpty, after 30 minutesThe stream closes — reconnect to keep following

For a build that has already finished, the stream sends the whole log and the complete event at once. No line is sent twice.

EventSource cannot set headers, so when there is no Authorization header this endpoint also accepts a session JWT as ?token=<jwt>. A token whose session was signed out gets 401 session_revoked, as on every other endpoint.

bash
curl -N https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds/bld_xyz789/logs/stream \
-H "Authorization: Bearer stx_abc12345_..."
text
event: log
data: {"timestamp":"2026-11-08T10:00:00Z","level":"info","message":"Build started","stage":"cloning"}
event: complete
data: cancelled

Error Responses

Statuserror.codeWhen
401unauthorizedNo credential, or an invalid, revoked or expired one
401session_revokedThe session behind the token was signed out — sign in again
403forbiddenYou are not a member of the project's workspace, or the API key's scope is below read
404not_foundThe project or build does not exist, the build belongs to another project, or the API key belongs to another project

404 Not Found

json
{
"error": {
"code": "not_found",
"message": "Build not found",
"details": { "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/bld_xyz789 \
-H "Authorization: Bearer stx_abc12345_..."
Responseapplication/json
200OK
{
"data": {
"id": "bld_xyz789",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"priority": 0,
"status": "deployed",
"trigger": "push",
"commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"commitMessage": "Update API documentation",
"filesChanged": [
"docs/api-reference/overview.mdx",
"docs/api-reference/endpoints.mdx"
],
"branch": "main",
"isPreview": false,
"deployUrl": "https://api-docs-docs.syntext.dev",
"error": null,
"pageCount": 24,
"durationMs": 4523,
"contentHash": "9f2c4e1a7b3d",
"sourcePath": null,
"deployId": "3f6c1d2e-8a4b-4c9d-9e1f-2a3b4c5d6e7f",
"warnings": 0,
"degraded": [],
"triggeredByUserId": "usr_abc123",
"triggeredBy": {
"id": "usr_abc123",
"name": "Ada Lovelace",
"avatarUrl": "https://avatars.githubusercontent.com/u/1234567"
},
"progress": null,
"logs": [
{ "timestamp": "2026-11-08T10:00:00Z", "level": "info", "message": "Build started", "stage": "cloning" },
{ "timestamp": "2026-11-08T10:00:02Z", "level": "info", "message": "Compiling 24 pages", "stage": "compiling" },
{ "timestamp": "2026-11-08T10:00:04Z", "level": "info", "message": "Deploying to CDN", "stage": "deploying" }
],
"createdAt": "2026-11-08T10:00:00Z",
"startedAt": "2026-11-08T10:00:00Z",
"completedAt": "2026-11-08T10:00:05Z",
"queuedBehind": null
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext