> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Template Builds

> Lists immutable Build attempts in reverse chronological order.



## OpenAPI

````yaml /api-spec/sandbox_api.yaml get /templates/{template_id}/builds
openapi: 3.0.3
info:
  title: GMI Sandbox API
  description: >-
    REST API for GMI Sandbox: create isolated execution environments from
    templates or durable snapshots, manage their lifecycle on the control plane,
    and run commands or transfer files through each sandbox's own data plane.
  contact:
    name: GMI Cloud Support
    email: support@gmicloud.ai
  version: '2.0'
servers:
  - url: https://console.gmicloud.ai/api/v2
    description: Control plane
security:
  - bearerAuth: []
tags:
  - name: Sandbox
    description: |
      Sandbox instance lifecycle management (Sandbox v2, /api/v2/sandboxes)
  - name: SandboxSnapshot
    description: Durable sandbox snapshot management (Sandbox v2, `/api/v2/snapshots`)
  - name: SandboxTemplate
    description: Sandbox template management (Sandbox v2, `/api/v2/templates`)
  - name: Sandbox-Exec
    description: >
      Sandbox execution data plane (accessed via the sandbox host and sandbox
      access token). These endpoints are not under the control plane's `/api/v2`
      path; clients connect directly to `https://{sandbox_key}.{domain}` and
      authenticate with `X-Access-Token`.
  - name: Sandbox-Shell
    description: >
      Sandbox interactive terminal (PTY) data plane. **These endpoints are not
      under `/api/v2`**: clients connect directly to
      `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`.
      `{sandbox_key}`, `{domain}` and the `X-Access-Token` value are the
      `sandbox_key`, `domain` and `sandbox_access_token` returned by the
      control-plane create/connect endpoints; no extra endpoint is needed.


      Each sandbox has exactly **one logical shell session** and at most **one
      active WebSocket connection** at a time (a second concurrent attach is
      refused at handshake with `409`). Disconnecting does not destroy the shell
      — re-attaching resumes the same session; only `POST /shell/control` with
      `action=close` destroys it.
  - name: Sandbox-Files
    description: >
      Sandbox file data plane (`/files`). **These endpoints are not under
      `/api/v2`** and do not use `Authorization: Bearer`: they are served by the
      sandbox's own data-plane entry point — clients connect directly to
      `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`.
      `{sandbox_key}` is the `sandbox_key` returned by the create/connect
      endpoints, used for data-plane host addressing. `{domain}` and
      `X-Access-Token` are the `domain` and `sandbox_access_token` from the same
      responses — no extra endpoint is needed to obtain them.


      This split is not historical baggage but the nature of a data plane: file
      transfer is long-lived, high-volume, and addressed per sandbox, differing
      from the control plane's short requests in both capacity model and failure
      domain, so they do not share an entry point.


      **One unified abstraction.** The same contract is served by two backend
      kinds (an in-sandbox file service / a data-center data-plane proxy);
      clients need not — and cannot — tell them apart. The cost is that the
      contract is their intersection: `Content-Length` on download and resumable
      download (`Range`/`206`) are **optional capabilities** that vary by data
      center, and clients must work correctly when they are absent. See the
      per-operation notes below.
paths:
  /templates/{template_id}/builds:
    parameters:
      - $ref: '#/components/parameters/TemplateBuildTemplateIdPathParam'
    get:
      tags:
        - SandboxTemplate
      summary: List Template Builds
      description: Lists immutable Build attempts in reverse chronological order.
      operationId: listTemplateBuilds
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: Builds were returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildPage'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '499':
          $ref: '#/components/responses/RequestCanceled'
        '500':
          $ref: '#/components/responses/InternalError'
        '504':
          $ref: '#/components/responses/RequestTimeout'
components:
  parameters:
    TemplateBuildTemplateIdPathParam:
      name: template_id
      in: path
      required: true
      description: Owning GMI Template identifier.
      schema:
        type: string
        format: uuid
    PageParam:
      name: page
      in: query
      description: Page number, starting from 1; default 1
      schema:
        type: integer
        minimum: 1
        default: 1
    PageSizeParam:
      name: page_size
      in: query
      description: Items per page; default 20, maximum 100
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  schemas:
    BuildPage:
      type: object
      additionalProperties: false
      required:
        - request_id
        - total
        - page
        - page_size
        - items
      properties:
        request_id:
          type: string
          description: HTTP request correlation identifier.
        total:
          type: integer
          format: int64
          minimum: 0
          description: Total number of Build attempts for the Template.
        page:
          type: integer
          minimum: 1
          description: One-based page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Requested number of Builds per page.
        items:
          type: array
          items:
            $ref: '#/components/schemas/TemplateBuild'
    TemplateBuild:
      type: object
      required:
        - id
        - template_id
        - trigger
        - status
        - artifact_state
        - source_type
        - resources
        - build_timeout_sec
        - created_at
      properties:
        default_user:
          $ref: '#/components/schemas/TemplateDefaultUser'
        id:
          type: string
          description: Immutable GMI Build identifier.
        template_id:
          type: string
          description: Owning GMI Template identifier.
        trigger:
          $ref: '#/components/schemas/BuildTrigger'
        status:
          $ref: '#/components/schemas/BuildStatus'
        artifact_state:
          $ref: '#/components/schemas/ArtifactState'
        source_type:
          $ref: '#/components/schemas/BuildSourceType'
        source:
          type: object
          description: Sanitized Build lineage. Internal IDs and credentials are omitted.
          additionalProperties: true
        registry_authentication:
          nullable: true
          description: >-
            Whether this Build used a registry credential; non-null only when
            `registry_credential` was supplied at create time. Reports only
            whether one was used and of what kind, never the username or
            password.
          type: object
          additionalProperties: false
          required:
            - configured
            - type
          properties:
            configured:
              type: boolean
            type:
              type: string
        resources:
          $ref: '#/components/schemas/EffectiveResources'
        product:
          type: string
          nullable: true
          description: Catalog SKU of the preset the Build was created from.
        product_name:
          allOf:
            - $ref: '#/components/schemas/ResourceSpecName'
          nullable: true
          description: Human-readable label of the preset the Build was created from.
        commands:
          type: array
          description: Build command strings. Empty for snapshot Builds.
          items:
            type: string
        start_cmd:
          type: string
          nullable: true
          description: Persisted launch command for this Build.
        ready_cmd:
          type: string
          nullable: true
          description: Readiness check command, unrelated to any registry credential.
        build_timeout_sec:
          type: integer
          minimum: 0
          description: |
            Effective wall-clock budget for this Build (seconds). 0 while the
            Build has not started, or for Builds that predate this field.
        failure:
          $ref: '#/components/schemas/BuildFailure'
        created_at:
          type: string
          format: date-time
          description: Build creation time in UTC.
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Build start time in UTC.
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: Build terminal time in UTC.
    ErrorResponse:
      type: object
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: Machine-readable business error code
          example: Resource.QuotaExceeded
        message:
          type: string
          description: Human-readable error description
          example: The resource quota is not enough.
        request_id:
          type: string
          description: Tracing ID
          example: req-xxxx
        trace_id:
          type: string
          description: >-
            Server-side trace identifier for this request; quote it when
            reporting a problem.
        details:
          type: object
          description: Field-level error details
          additionalProperties: true
    TemplateDefaultUser:
      type: object
      additionalProperties: false
      required:
        - username
      description: >
        Runtime default identity for Sandboxes launched from this Build.

        Without it, Sandboxes run as `docker run` would: as the Dockerfile's
        final

        USER, else the image's USER, else root, in the final WORKDIR, else the

        image's, else `/`.

        Sandboxes run commands as a named account: an image USER given as a

        numeric uid (or uid:gid) needs a matching /etc/passwd entry in the
        image,

        otherwise the Build fails with a reason that names the USER. The group

        part is ignored.

        It is applied after all build commands and overrides the final
        Dockerfile

        USER at runtime; it does not change the identity of earlier build
        commands.


        Recommended setup for a custom account: create it in the Dockerfile,
        give

        it a working directory it can access, and pass its uid, for example

        `RUN useradd --uid 9999 --create-home --shell /bin/bash app`,

        `WORKDIR /home/app`, and `default_user: {username: app, uid: 9999}`.


        - default_user changes the identity only, not the working directory or
        its
          permissions. If the account cannot enter the final working directory,
          commands cannot start there and the Build may fail; declare an
          accessible WORKDIR to fix it.
        - With uid, the account must already exist with that UID and an existing
          home directory; otherwise the Build fails. The platform does not change
          UID, ownership, groups, or sudo privileges.
        - A non-root username without uid may be rejected with HTTP 422
          (Template.ProviderNotSupported); supply uid to avoid this. root may omit uid.
        - Invalid username, out-of-range uid, or root with a nonzero uid returns
          HTTP 400 (Parameter.Invalid).
        - A Build from a base template keeps the base template's user and
        working
          directory, as Docker FROM does; set default_user on the child Build to
          select another. Changing it requires a new Build.

        When omitted, the template's default runtime identity is used. A Build

        response reports the requested setting; an omitted uid stays omitted.
      properties:
        username:
          type: string
          minLength: 1
          maxLength: 32
          pattern: ^[a-z_][a-z0-9_-]{0,31}$
          example: app
        uid:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: >-
            UID of the account. Recommended for non-root usernames. root only
            accepts 0.
          example: 9999
    BuildTrigger:
      type: string
      enum:
        - initial_build
        - rebuild
        - snapshot
      description: Operation that created the Build.
    BuildStatus:
      type: string
      enum:
        - waiting
        - building
        - ready
        - error
      description: Normalized Template Build status.
    ArtifactState:
      type: string
      enum:
        - absent
        - unknown
        - available
        - reclaimed
        - retained
      description: |
        Build artifact availability independent of Build status.
        `retained` means the Build was logically deleted but the artifact was
        left in place; `reclaimed` means the artifact was hard-deleted.
    BuildSourceType:
      type: string
      enum:
        - image
        - template
        - sandbox
        - dockerfile
      description: Build lineage type.
    EffectiveResources:
      type: object
      additionalProperties: false
      required:
        - cpu_count
        - memory_mb
        - disk_size_mb
        - architecture
      properties:
        cpu_count:
          type: integer
          minimum: 1
          description: Effective integer vCPU count, as configured on the selected preset.
        memory_mb:
          type: integer
          minimum: 1
          description: Effective memory size in MiB, as configured on the selected preset.
        disk_size_mb:
          type: integer
          minimum: 1
          description: >-
            Effective boot disk size in MiB, as configured on the selected
            preset.
        architecture:
          type: string
          enum:
            - x86_64
            - arm64
          description: |
            CPU architecture resolved for the selected IDC.
    ResourceSpecName:
      type: string
      enum:
        - X_SMALL
        - SMALL
        - MEDIUM
        - LARGE
        - X_LARGE
      description: Stable human-readable Sandbox resource specification label.
    BuildFailure:
      type: object
      nullable: true
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Stable GMI failure code. Notable values:
            `TemplateBuild.ProviderBuildFailed`, `TemplateBuild.OutOfMemory`,
            `TemplateBuild.OutOfDisk`, `TemplateBuild.TimedOut` (wall-clock
            budget exceeded), `TemplateBuild.Superseded` (replaced by a newer
            rebuild request).
          example: TemplateBuild.OutOfMemory
        message:
          type: string
          description: Sanitized failure message.
  responses:
    BadRequest:
      description: >-
        Invalid request parameters. Two code families are used:
        `Request.InvalidParameter` for request parsing and format validation
        (unknown or malformed body fields, malformed IDs, invalid enum values,
        out-of-range paging) and `Parameter.Invalid` for business validation
        (for example a template or IDC that cannot be found, or a `timeout` over
        the limit). Unknown or invalid fields inside the `params` of `POST
        /sandboxes/{id}/actions` are reported as `Parameter.Invalid`. Other 400
        codes are specific to an operation, for example `Sandbox.SourceConflict`
        (both or neither of `template_id` and `snapshot_id`) and
        `Sandbox.IdempotentParameterMismatch` (an `Idempotency-Key` reused with
        different parameters). Both code families share the same HTTP status, so
        decide by the `code` value, not the status alone.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: Parameter.Invalid
            message: Invalid request parameters
            request_id: req-xxxx
    Unauthorized:
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: Auth.Unauthorized
            message: Authentication required
            request_id: req-xxxx
    Forbidden:
      description: The caller cannot access the organization-scoped resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: Resource.NotFound
            message: The requested resource was not found
            request_id: req-xxxx
    RequestCanceled:
      description: The caller canceled the current HTTP request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: Request.Canceled
            message: Request canceled
            request_id: req-xxxx
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: System.Internal
            message: An internal server error occurred
            request_id: req-xxxx
    RequestTimeout:
      description: The current HTTP request exceeded the control-plane processing deadline.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: Request.Timeout
            message: Request timed out
            request_id: req-xxxx
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        API Key or Access Token, always sent as `Authorization: Bearer <token>`.
        The gateway recognizes the token type automatically.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.