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

# Preview a build (dry run)

> Run the BuildSpec against a small sample of each source (capped at 100 rows) and present the
output to the caller WITHOUT ingesting it into any dataset. Requires read (QUERY) access to the
sources and destination datasets. The saved code may be overridden with inline code for this preview.
At most one preview may be active per spec. Returns the new run in status `Scheduled`; poll the run and then
fetch its outputs once it reaches `Finished`.




## OpenAPI

````yaml /api-reference/openapi.yml post /build-specs/{buildSpecId}/preview
openapi: 3.0.3
info:
  title: DataLinks
  version: 2.29.0
servers:
  - url: https://api.datalinks.com/api/v1
    description: production server
security:
  - bearerAuth: []
  - openId:
      - implicit
paths:
  /build-specs/{buildSpecId}/preview:
    post:
      tags:
        - buildspecs
      summary: Preview a build (dry run)
      description: >
        Run the BuildSpec against a small sample of each source (capped at 100
        rows) and present the

        output to the caller WITHOUT ingesting it into any dataset. Requires
        read (QUERY) access to the

        sources and destination datasets. The saved code may be overridden with
        inline code for this preview.

        At most one preview may be active per spec. Returns the new run in
        status `Scheduled`; poll the run and then

        fetch its outputs once it reaches `Finished`.
      operationId: previewBuildSpec
      parameters:
        - name: buildSpecId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildSpecPreviewRequest'
        required: false
      responses:
        '201':
          description: The created preview BuildRun.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildRunResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableContent'
components:
  schemas:
    BuildSpecPreviewRequest:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/BuildSpecCode'
        sampleSize:
          type: integer
          description: >-
            Rows to sample from each dataset source. Omit for the default (100).
            A negative value previews the whole dataset. Applies to dataset
            sources only; file sources pass whole.
          example: 100
      description: >-
        Optional overrides for a preview run. When `code` is omitted the
        BuildSpec's saved code is previewed; when present it overrides the saved
        code (validated as base64) for this preview only. `sampleSize` limits
        dataset sources only (file sources always pass whole); omit for the
        default (100 rows), or use a negative value to preview the whole
        dataset. Ignored for GitPipeline specs' `code` field, which is fixed to
        the repo.
    BuildRunResponse:
      required:
        - buildSpecId
        - createdAt
        - id
        - kind
        - retries
        - specVersion
        - status
        - updatedAt
      type: object
      properties:
        id:
          type: string
          format: uuid
        buildSpecId:
          type: string
          format: uuid
        specVersion:
          type: integer
          description: >-
            The BuildSpec version this run executes (snapshotted at schedule
            time).
        status:
          type: string
          enum:
            - Scheduled
            - Exporting
            - Claimable
            - Running
            - Produced
            - Ingesting
            - Finished
            - Failed
        kind:
          type: string
          description: >-
            Whether this run ingests its output (Build) or presents it to the
            user (Preview).
          enum:
            - Build
            - Preview
        retries:
          type: integer
        errorMessage:
          type: string
        createdAt:
          type: string
          description: Timestamp of the BuildRun creation.
          format: date-time
          example: '2005-04-02T19:37:00.000Z'
        updatedAt:
          type: string
          description: Timestamp of the BuildRun last update.
          format: date-time
          example: '2005-04-02T19:37:00.000Z'
    BuildSpecCode:
      required:
        - payload
      type: object
      properties:
        payload:
          type: string
          description: >-
            Code payload, base64-encoded by the client. Only Python code is
            supported.
          example: cGFzcwo=
    ErrorResponse:
      required:
        - error_code
        - message
      type: object
      properties:
        error_code:
          type: string
          example: UNAUTHORIZED
        error_message:
          type: string
          example: ''
        message:
          type: string
          example: Missing authentication token
        sub_errors:
          type: array
          items:
            required:
              - code
              - message
            type: object
            properties:
              code:
                type: string
              message:
                type: string
  responses:
    Unauthorized:
      description: >-
        Unauthorized. This error occurs if the authentication token is missing
        or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: >-
        Conflict. The request could not be completed due to a conflict with the
        current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableContent:
      description: The request could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      description: >
        Use a Bearer token for authentication. Submit the token using the
        `Authorization`

        header: `Authorization: Bearer <token>`.
      scheme: bearer
    openId:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: >-
            https://login.datalinks.com/realms/datalinks-realm/protocol/openid-connect/auth
          scopes:
            openid: openid

````