> ## 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.

# List Builds

> List all builds for your organization with optional filters

## Filtering Builds

Use query parameters to filter and paginate your build list:

```bash theme={null}
# List all successful builds
curl "https://api.pipecat.daily.co/v1/builds?status=success" \
  -H "Authorization: Bearer $PIPECAT_API_KEY"

# List builds in a specific region
curl "https://api.pipecat.daily.co/v1/builds?region=us-west&limit=10" \
  -H "Authorization: Bearer $PIPECAT_API_KEY"

# Find builds with a specific context hash
curl "https://api.pipecat.daily.co/v1/builds?contextHash=a1b2c3d4e5f6a7b8" \
  -H "Authorization: Bearer $PIPECAT_API_KEY"
```

## Pagination

Results are paginated with `limit` and `offset` parameters:

```bash theme={null}
# Get page 2 (items 21-40)
curl "https://api.pipecat.daily.co/v1/builds?limit=20&offset=20" \
  -H "Authorization: Bearer $PIPECAT_API_KEY"
```

The response includes `total` to help calculate pagination:

```json theme={null}
{
  "builds": [...],
  "total": 142,
  "limit": 20,
  "offset": 20
}
```


## OpenAPI

````yaml GET /builds
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:
    get:
      summary: List builds
      description: List all builds for your organization with optional filters.
      operationId: listBuilds
      parameters:
        - name: status
          in: query
          description: Filter by build status.
          schema:
            type: string
            enum:
              - pending
              - building
              - success
              - failed
              - timeout
        - name: region
          in: query
          description: Filter by region.
          schema:
            type: string
          example: us-west
        - name: contextHash
          in: query
          description: Filter by context hash.
          schema:
            type: string
          example: a1b2c3d4e5f6a7b8
        - name: limit
          in: query
          description: Maximum number of builds to return.
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Number of builds to skip for pagination.
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        '200':
          description: List of builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuildsResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    ListBuildsResponse:
      type: object
      properties:
        builds:
          type: array
          items:
            $ref: '#/components/schemas/Build'
          description: Array of build objects.
        total:
          type: integer
          description: Total number of builds matching the filters.
          example: 42
        limit:
          type: integer
          description: Maximum number of builds returned.
          example: 20
        offset:
          type: integer
          description: Number of builds skipped.
          example: 0
    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 (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.
        errorMessage:
          type: string
          description: Error message if the build failed.
        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: Build duration in seconds (only present when build is complete).
          example: 120
        startedAt:
          type: string
          format: date-time
          description: When the build started.
        completedAt:
          type: string
          format: date-time
          description: When the build completed.
        createdAt:
          type: string
          format: date-time
          description: When the build record was created.
        updatedAt:
          type: string
          format: date-time
          description: When the build record was last updated.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authentication using a Pipecat Cloud API token.

````