# List a Space's builds Returns the builds created for the Space, newest first, in every state from waiting for source through terminal. Page with `cursor`. GET `/v1/spaces/{spaceId}/builds` ## Authorization `Authorization: Bearer ` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix). ## Path parameters `spaceId` string required ## Query parameters `limit` integer required min 1 · max 100 · default: 20 `cursor` string min length 1 · max length 4096 ## Responses ### 200 Response for status 200 `$schema` string Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header. `data` object[] required Array of `object` - `id` string required Build ID (`bld_` prefix). Opaque, and never derived from a version ID. - `spaceId` string required Space (`spc_` prefix) the build publishes into. - `status` string required Where the build is in its lifecycle. `skipped` means the ignored build command decided no build was needed. Allowed: `waiting_for_source`, `uploading_source`, `queued`, `running`, `succeeded`, `failed`, `canceled`, `skipped` - `input` object required The source a build ran against, with clone URLs and repository connection identifiers removed. - `kind` string required The build ran against an uploaded source archive. - `kind` string required The build ran against repository source. - `ref` string required Branch, tag, or ref the build checked out. - `commit` string Commit the ref resolved to. Absent until resolved. - `branch` string Branch the ref belongs to, when it is known. - `pullRequestNumber` integer Pull request the build was raised for. Absent for builds off a plain branch. - `source` object | any required Publish provenance as declared when the build started: client, git ref data, and publish message. It is present on running and failed builds, which have no version yet; once a version exists its own `source` is authoritative. Null when nothing was declared. - `kind` string required How this version was produced. `variable_update` and `config_update` mark republishes Spacefast makes on its own when a variable or a setting changed; the rest name what published. Allowed: `direct_upload`, `cli`, `dashboard`, `api`, `git`, `import`, `agent`, `build`, `variable_update`, `config_update` - `client` string Client and version that published, for example `spacefast-cli/1.2.3`. - `branch` string Git branch the publish was made from. - `commit` string Git commit the publish was made from. - `message` string One-line description of the publish, shown as the version's headline in the dashboard. There is no separate changelog field. The CLI fills it from the git commit message when it can. - `dirty` boolean Whether the working tree had uncommitted changes when the publish was made. - `metadata` object Extra provenance as string pairs, such as a repository, a CI run URL, a workflow, or an actor. - `git` object - `repository` string | any - `repositoryFullName` string | any - `repositoryUrl` string | any - `ref` string | any - `branch` string | any - `branchAliasUrl` string | any - `commit` string | any - `commitSha` string | any - `pullRequestNumber` number | any - `settingsSnapshot` object required Build settings after saved values and per-run overrides are merged. A build freezes these at creation and runs against them for its whole life. - `rootDirectory` string | any required Directory the build runs in, relative to the source root. Null builds at the root. - `installDirectory` string | any required Directory dependencies install into, relative to the source root. Null installs in the build directory. - `installCommand` string | any required Command that installs dependencies. Null lets the build runner pick one. - `buildCommand` string | any required Command that produces the output. Null lets the build runner pick one. - `outputDirectory` string | any required Directory the built output is collected from, relative to the build directory. Null lets the build runner detect it. - `ignoredBuildCommand` string | any required Command run before the build to decide whether the build is needed. Exiting 0 ends the build as `skipped`; any other exit code continues. Null always builds. - `frameworkPreset` string | any required Framework the source builds with, for example `next` or `vite`. Null lets the build runner detect it. - `platformPreset` string | any required Platform build convention the source follows, for example `vercel` or `netlify`. Null lets the build runner detect it. - `allowUnsupportedPlatformFeatures` boolean required Runs the build even when the source declares platform features Spacefast does not support. Defaults to `false`, which refuses those sources. - `timeoutSeconds` integer required Wall-clock budget for the run, in seconds. Between 60 and 7200; defaults to 900. - `target` object required Where a successful build's version goes. - `channel` string | any required Channel the produced version is promoted to when the build succeeds. Null publishes the version without promoting it. - `preview` boolean required Marks the run as a preview build. The build environment is exported as a preview, and a preview build only supersedes other preview builds on the same branch. - `retryOfBuildId` string | any required Build this run retries. Null when it is not a retry. - `producedVersionId` string | any required Version (`ver_` prefix) this build minted. Null until a build succeeds and mints one. - `reusedVersionId` string | any required Version the build reused because the output was unchanged. Null otherwise. - `diagnostics` object[] required Array of `object` - `code` string required Stable snake_case code for this diagnostic. - `severity` string required How serious the diagnostic is. Allowed: `info`, `warning`, `error` - `message` string required What happened, in a sentence a person can act on. - `path` string | any File or artifact path the diagnostic refers to, with a line number when known, for example `_headers:12`. Absent when it applies to the whole resource. - `provider` string | any Upstream system that raised the diagnostic. Absent when Spacefast raised it. - `details` object | any Machine-readable context keyed by the diagnostic code. - `fix` string | any What to change to clear the diagnostic. Absent when there is no known fix. - `retryable` boolean | any True when repeating the same operation unchanged can clear the diagnostic. - `createdAt` string required ISO 8601 timestamp when the build was created. - `startedAt` string | any required ISO 8601 timestamp when the build runner started the run. Null until it does. - `finishedAt` string | any required ISO 8601 timestamp when the build reached a terminal state. Null while it is still in flight. - `pagination` object required - `nextCursor` string | any required Cursor for the next page. Null on the last page. - `hasMore` boolean required True when another page exists. ### Error `$schema` string Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header. - `type` string required URL of the documentation page for this error. Derived from `code`. - `title` string required Human-readable name of the error type. Derived from `code`. - `status` integer required HTTP status of the response, repeated in the body. - `detail` string required What went wrong in this request. - `code` string required Stable snake_case error code. Match on this, not on `detail`. - `pointer` string RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures. - `details` object Machine-readable context keyed by the error code. - `suggestions` string[] Recovery steps safe to show to a person. - `next` string[] Commands or API requests to run next, usable as written. - `requestId` string required ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.