---
title: "Get a template build: state, timestamps, bounds, provenance, results, failure, log tail and builder availability"
method: GET
path: "/v1/organizations/{organization_id}/template-builds/{build_id}"
tags: ["Template builds"]
---

# Get a template build: state, timestamps, bounds, provenance, results, failure, log tail and builder availability

`GET /v1/organizations/{organization_id}/template-builds/{build_id}`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/organizations/{organization_id}/template-builds/{build_id}`
- Auth: HTTP bearer

Bounded wait: with `Prefer: wait=<seconds>` (at most 20) and a build that is not settled (settled = failed, canceled, legacy succeeded, or published with registration registered/failed), the response is held until `state` or `registration.state` changes or the wait elapses, then carries the fresh build and `Preference-Applied: wait=<seconds>`. Without `Preference-Applied` the server did not wait: poll with backoff.

## Path parameters

- `organization_id` string, uuid, required
- `build_id` string, uuid, required

## Headers

- `prefer` string

## Response `200`

Default Response

- object
  - `id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `organization_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `template` object, required
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `slug` string, required
    - `name` string, required
  - `state` 'queued' | 'building' | 'testing' | 'publishing' | 'published' | 'succeeded' | 'failed' | 'canceled', required: queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds.
  - `target_version` integer, nullable, required: Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds.
  - `auto_publish` boolean, required: Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route.
  - `published_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `registration` object, required: Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why).
    - `state` 'not_applicable' | 'pending' | 'registered' | 'failed', required
    - `registered_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
  - `template_version` object, nullable, required: The template version this build produced (once registered).
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `version` integer, required
    - `published` boolean, required
  - `cancel_requested_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `created_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `updated_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `started_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `completed_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `requested_by` object, required
    - `type` 'user' | 'api_key', required
    - `id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `base` object, required: The base template version, pinned at request time.
    - `ref` string, required
    - `template_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `template_version_id` string, uuid, required: UUIDv7, lowercase canonical form.
    - `slug` string, required
    - `version` integer, required
    - `artifact_sha256` string, required
  - `architecture` string, required
  - `bounds` object, required
    - `cpu_millis` integer, required
    - `memory_mib` integer, required
    - `disk_gib` integer, required
    - `timeout_seconds` integer, required
  - `requested_bounds` object, required
    - `cpu_millis` integer, nullable, required
    - `memory_mib` integer, nullable, required
    - `disk_gib` integer, nullable, required
    - `timeout_seconds` integer, nullable, required
  - `bound_sources` object, required: request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum.
    - `cpu_millis` 'request' | 'plan' | 'platform', required
    - `memory_mib` 'request' | 'plan' | 'platform', required
    - `disk_gib` 'request' | 'plan' | 'platform', required
    - `timeout_seconds` 'request' | 'plan' | 'platform', required
  - `network` object, required: The build network (recipe v2: compiled.network, derived from the recipe for `auto`).
    - `mode` 'none' | 'egress_allowlist', required
    - `allow_hosts` string[], required
  - `denied_hosts` string[], required: Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it.
  - `provenance` object, required
    - `recipe_schema` string, nullable, required: Null for workspace-source builds.
    - `recipe_sha256` string, nullable, required: SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds.
    - `base_artifact_sha256` string, required
    - `builder_id` string, nullable, required
    - `attempt` integer, required
  - `recipe` union: Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document).
    - object
      - `dockerfile` string, required
    - object
      - `schema` 'shardflux.template-recipe.v2', required
      - `build` object, required
        - `languages` object[], required: Resolved languages in compile order (implied ones included); source base = the base already has it.
          - `id` string, required
          - `version` string, required
          - `source` 'install' | 'base', required
          - `url` string, nullable, required
          - `sha256` string, nullable, required
        - `packages` object, required
          - `apt` string[], required
          - `pip` object, required
            - `packages` string[], required
            - `requirements` string[], required
          - `npm` string[], required
        - `files` object[], required
          - `upload` string, required
          - `kind` 'file' | 'tar', required
          - `to` string, required
          - `owner` string, required
          - `mode` string, nullable, required
          - `size` integer, required
        - `steps` object[], required
          - `name` string, required
          - `run` string, required
          - `user` string, required
          - `cwd` string, nullable, required
          - `env` object, required
        - `network` object, required
          - `build` 'auto' | 'none' | 'allowlist', required
          - `extra_hosts` string[], required
          - `allow_hosts` string[], required
      - `settings` TemplateSettings, required: What a workspace of the version gets when it opens, every key present. `env` is the effective template env (a recipe v2 version: its languages’ build env, then its own env).
        - `env` object, required
        - `inputs` object, required
        - `start` TemplateStartCommand[], required
          - `name` string, required
          - `when` 'create' | 'boot' | 'resume', required
          - `run` string, required
          - `user` string, nullable, required: null: the template’s default user.
          - `cwd` string, nullable, required
          - `timeout_seconds` integer, required
        - `services` object, required
        - `defaults` TemplateDefaults, required: Manifest v2 `defaults`. Versions without them report the T1 defaults.
          - `lifetime` 'persistent' | 'session', required: persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;).
          - `idle_timeout_seconds` integer, nullable, required
          - `limits` object, nullable, required: Ceilings of every admission of a workspace of the version (clamped, never refused;).
            - `cpu_millis_ceiling` integer, required
            - `memory_mib_ceiling` integer, required
            - `disk_gib` integer, required
          - `egress` TemplateEgressDefault, required: The template’s workspace network ceiling: the cell intersects it with the effective egress policy.
            - `mode` 'allowlist' | 'none', required
            - `allow_hosts` string[], required: Normalized (lowercase, sorted); empty for none.
          - `agent_tools` unknown, required
      - `compiled` object, required
        - `compiler` string, required
        - `language_table_sha256` string, required
        - `build_env` object, required
        - `steps` object[], required
        - `tools` object[], required
          - `name` string, required
          - `argv` string[], required
        - `network` object, required
          - `mode` 'none' | 'egress_allowlist', required
          - `allow_hosts` string[], required
        - `objects` object[], required
          - `sha256` string, required
          - `size` integer, required
          - `kind` 'file' | 'tar', required
      - `immutable` string[], required: The effective immutable paths (: the recipe’s, else inherited), in byte order; empty for none.
  - `result` object, required
    - `artifact_sha256` string, nullable, required
    - `scan` object, nullable, required: Scanner result recorded by the builder ({passed, scanner, scanner_version, summary}).
    - `compatibility` object, nullable, required: Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks}).
    - `produced_version` object, nullable, required
      - `id` string, uuid, required: UUIDv7, lowercase canonical form.
      - `version` integer, required
      - `state` 'unpublished' | 'published' | 'archived', required
      - `published_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
      - `archived_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `failure` object, nullable, required
    - `code` string, required: build_error, timeout, resource_limit, scan_failed, compatibility_failed, base_unavailable, network_denied, internal_error, publish_failed, source_unavailable, immutable_path_missing (an immutable path is not a directory in the built filesystem: details.path), immutable_image_too_large (the immutable image exceeds 16 GiB).
    - `message` string, required
    - `details` object: Code-specific details (immutable_path_missing: {path}).
  - `log` object, required: Build log: the tail inline, the full log through a short-lived signed URL (log-url).
    - `state` 'none' | 'available' | 'expired', required
    - `bytes` integer, nullable, required
    - `sha256` string, nullable, required: SHA-256 of the full log object, when the builder recorded it.
    - `expires_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
    - `downloadable` boolean, required: The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL).
    - `tail` string, nullable: Last <= 64 KiB of the build log (GET of one build; until expires_at).
  - `publishable` boolean, required
  - `builder_availability` object, required: From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs.
    - `state` 'available' | 'unavailable', required
    - `reason` 'no_builder_registered' | 'no_recent_heartbeat', nullable, required
    - `active_builders` integer, required
    - `last_heartbeat_at` string, date-time, nullable, required: RFC 3339 UTC timestamp with Z.
  - `queue` object: Present while the build waits for one of the plan’s build slots (all are in use): it starts as one frees.
    - `position` integer, required: Builds of the organization ahead of this one for a slot (1 = next).
    - `slots` integer, required: Builds the plan runs at once (concurrent_template_builds).
    - `expected_wait_seconds` integer, required: Estimate from the organization’s recent build times.
  - `progress` object: Present while the build runs (building, testing, publishing, or published before registration), or the last reported phase and counters after failure. Missing counters are unknown.
    - `phase` 'preparing' | 'copying' | 'sealing' | 'indexing' | 'packaging' | 'testing' | 'publishing' | 'registering' | 'building', required: preparing (fetching the source, starting the builder), copying (a save: the files go into the new layer) or building (a recipe runs), sealing (cleanup and platform files), indexing (the file list), packaging (the layer is compacted for storage), testing (the version boots), publishing (stored), registering (becomes a version).
    - `step` integer, required: The phase’s place in the list (1-based).
    - `steps` integer, required: How many phases the build has.
    - `files_done` integer
    - `files_total` integer: Files the phase handles (an estimate from the source filesystem while copying).
    - `bytes_done` integer
    - `bytes_total` integer
    - `phase_started_at` string, date-time
    - `updated_at` string, date-time, required: When the builder last reported.
  - `source_kind` 'recipe' | 'workspace', required: recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish).
  - `source_workspace_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `source_checkpoint_id` string, nullable, required: The saved checkpoint (filled when the capture finished and the cell claimed the build).
  - `scrub_result` object, nullable, required: sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents.
  - `files` object, nullable, required: The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes}).
  - `produced_layer_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
  - `squashed` boolean, nullable, required: The base chain already had 4 org layers: this build squashed them into its one layer.
  - `org_bytes` integer, nullable, required: The produced chain’s org bytes (limited by the plan’s workspace disk limit).
  - `immutable_paths` string[], required: The immutable paths the produced version declares, in byte order: the recipe’s `immutable`, else the list of the template’s open version (a save from a workspace: the target template’s open version’s list, else the workspace’s version’s). Empty for none.

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)