Get Build
Get one build, including its log, and read or stream build logs.
Retrieve one build of a project, including its persisted log and who started it.
Any workspace member (session JWT), or an API key bound to this project with the read scope or higher. Any plan.
Path Parameters
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).buildIdbld_xyz789). It must belong to projectId.Response
dataidprojectIdprioritystatusqueued, uploading, cloning, parsing, compiling, deploying, deployed, failed or cancelled. deployed, failed and cancelled are final.triggerpush, manual, schedule, pull_request, github_app, cli_upload, editor or rollback. editor is a publish of a project written in Syntext — the editor's Publish, a content publish or import, or Trigger Build on such a project. rollback marks an instant rollback, which builds nothing. Dashboard and API builds, and rollbacks that have to rebuild, are manual. stx deploy uploads and promotions are cli_upload. Treat unknown values as possible future additions.commitShanull when the build uses the branch head or uploaded files.commitMessageRoll back to a1b2c3d: Update API documentation.filesChangedbranchisPreviewtrue for a preview build, false for production.deployUrldeployIdnull for previews, versioned builds, builds skipped as unchanged, and builds from before November 2026. A build with a deployId whose deploy is still kept can be rolled back to instantly.errorCancelled by <name> for a cancelled build, or Superseded: build <id> was requested later and is already live, so this build did not publish for a production build that stopped because a later-requested production build had already deployed (see Build order).pageCountdurationMscontentHashwarningswarn lines in the build's log, set when the build finishes. A deployed build with warnings above 0 deployed with a degraded stage (see degraded). 0 for builds from before November 2026.degradedembed (the AI assistant wasn't updated), index (search kept its previous index), openapi, compile, links or deploy. Empty for a clean build.sourcePathnull for git builds.triggeredByUserIdnull for API-key builds, and for webhook builds whose GitHub sender is not matched to a workspace member.triggeredBy{ id, name, avatarUrl } of that user, or null.progress{ done, total }: pages compiled so far out of the build's documentation files, for a "88/142 pages" display. Set only while the build is running (uploading to deploying) and once it has reached the compile stage; it stays at total/total through deploying. null for queued and finished builds, and when progress can't be read in time. List Builds rows carry it too.logsGET …/logs returns. Only this endpoint returns it — List Builds rows do not.timestamplevelinfo, warn or error.messagestagecreatedAtstartedAtcompletedAtqueuedBehindqueued, the build of the same project it is waiting on: the running build, or else the oldest build queued ahead of it. null when the build is not queued or nothing is ahead. Same shape as on Deploy Source Files: { buildId, status, trigger, branch, commitSha, isPreview, createdAt, startedAt }.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
/v1/projects/{projectId}/builds/{buildId}/logsReturns { 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.
Stream the log
/v1/projects/{projectId}/builds/{buildId}/logs/streamA 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:
| Event | Data | What to do |
|---|---|---|
log | One JSON log entry, redacted like GET …/logs | Append it |
complete | deployed, failed or cancelled | The build is over; the stream closes |
heartbeat | Empty, every 15 seconds | Ignore it |
timeout | Empty, after 30 minutes | The 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.
Error Responses
| Status | error.code | When |
|---|---|---|
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 401 | session_revoked | The session behind the token was signed out — sign in again |
| 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 or build does not exist, the build belongs to another project, or the API key belongs to another project |