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

# Get Build

> Get the current status of a build

## Status Reconciliation

When you poll a build that's in progress (`pending` or `building`), Pipecat Cloud automatically reconciles the status with the underlying build system. This means you always get the latest status without any delay.

## Polling for Completion

After creating a build, poll this endpoint until the build completes:

```bash theme={null}
BUILD_ID="123e4567-e89b-12d3-a456-426614174000"

while true; do
  RESPONSE=$(curl -s "https://api.pipecat.daily.co/v1/builds/$BUILD_ID" \
    -H "Authorization: Bearer $PIPECAT_API_KEY")

  STATUS=$(echo $RESPONSE | jq -r '.build.status')

  case $STATUS in
    "success")
      IMAGE_URI=$(echo $RESPONSE | jq -r '.build.imageUri')
      echo "Build complete! Image: $IMAGE_URI"
      break
      ;;
    "failed"|"timeout")
      ERROR=$(echo $RESPONSE | jq -r '.build.errorMessage')
      echo "Build failed: $ERROR"
      exit 1
      ;;
    *)
      echo "Status: $STATUS - waiting..."
      sleep 10
      ;;
  esac
done
```

<Note>
  Once your build succeeds, use the Pipecat CLI to deploy your agent. The CLI will automatically use the built image.
</Note>


## OpenAPI

````yaml GET /builds/{buildId}
openapi: 3.0.0
info:
  title: Pipecat Cloud
  version: 1.0.0
  description: Public API for Pipecat Cloud services
servers:
  - url: https://api.pipecat.daily.co/v1
    description: API server
security:
  - BearerAuth: []
paths:
  /builds/{buildId}:
    get:
      summary: Get build status
      description: >-
        Get the current status of a build. For builds in progress, this endpoint
        automatically reconciles the status with the underlying build system to
        provide the latest information.
      operationId: getBuild
      parameters:
        - name: buildId
          in: path
          required: true
          description: Unique identifier of the build.
          schema:
            type: string
            format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Build details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBuildResponse'
        '400':
          description: Invalid build ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Build not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    GetBuildResponse:
      type: object
      properties:
        build:
          $ref: '#/components/schemas/Build'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    Build:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the build.
          example: 123e4567-e89b-12d3-a456-426614174000
        organizationId:
          type: string
          description: Organization that owns this build.
          example: org_abc123
        status:
          type: string
          enum:
            - pending
            - building
            - success
            - failed
            - timeout
          description: Current status of the build.
          example: success
        region:
          type: string
          description: Region where the build ran.
          example: us-west
        contextHash:
          type: string
          description: Hash of the build context.
          example: a1b2c3d4e5f6a7b8
        dockerfilePath:
          type: string
          description: Path to the Dockerfile used for this build.
          example: Dockerfile
        imageUri:
          type: string
          description: >-
            URI of the built image. Use this value when deploying an agent. Only
            present when status is 'success'.
          example: >-
            123456789.dkr.ecr.us-west-2.amazonaws.com/pipecat-cloud/org_abc123:a1b2c3d4e5f6a7b8
        logsUrl:
          type: string
          format: uri
          description: URL to view build logs in the cloud console.
          example: https://console.aws.amazon.com/codebuild/...
        errorMessage:
          type: string
          description: >-
            Detailed error message if the build failed. Includes information
            from the build phases to help diagnose issues.
          example: 'Docker build failed: COPY failed - file not found: requirements.txt'
        contextSizeBytes:
          type: integer
          description: Size of the uploaded context in bytes.
          example: 10485760
        imageSizeBytes:
          type: integer
          description: >-
            Size of the built Docker image in bytes. Only present for successful
            builds.
          example: 524288000
        buildDurationSeconds:
          type: integer
          description: >-
            Total build duration in seconds. Only present when build is
            complete.
          example: 120
        startedAt:
          type: string
          format: date-time
          description: When the build started executing.
          example: '2026-02-20T12:00:00.000Z'
        completedAt:
          type: string
          format: date-time
          description: When the build completed (success, failed, or timeout).
          example: '2026-02-20T12:02:00.000Z'
        createdAt:
          type: string
          format: date-time
          description: When the build record was created.
          example: '2026-02-20T12:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: When the build record was last updated.
          example: '2026-02-20T12:02:00.000Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentication using a Pipecat Cloud API token.

````