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

# Analyze a query for optimization insights

> Reports the optimization opportunities SELECT can find in a single query execution, by examining the query alongside the execution profile Snowflake recorded for it. An empty list means the query was examined and nothing was found.



## OpenAPI

````yaml https://api.select.dev/v2/openapi.json post /insights/actions/analyze-query
openapi: 3.1.0
info:
  title: SELECT API (v2)
  version: 0.1.0
servers:
  - url: https://api.select.dev/v2
    description: SELECT API v2
security: []
paths:
  /insights/actions/analyze-query:
    post:
      tags:
        - insights
      summary: Analyze a query for optimization insights
      description: >-
        Reports the optimization opportunities SELECT can find in a single query
        execution, by examining the query alongside the execution profile
        Snowflake recorded for it. An empty list means the query was examined
        and nothing was found.
      operationId: analyze_query_route_insights_actions_analyze_query_post
      parameters:
        - name: x-tenant-id
          in: header
          required: true
          schema:
            type: string
            description: The organization ID the request is scoped to.
            title: X-Tenant-Id
          description: The organization ID the request is scoped to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeQueryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_QueryInsightV2_'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - HTTPBearer: []
components:
  schemas:
    AnalyzeQueryRequest:
      properties:
        query_id:
          type: string
          title: Query Id
          description: >-
            The Snowflake query id of the query to analyze. The query must have
            run in the last 14 days for its execution profile to still be
            available.
      additionalProperties: false
      type: object
      required:
        - query_id
      title: AnalyzeQueryRequest
      description: Identifies the query execution to analyze.
    ListResponse_QueryInsightV2_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/QueryInsightV2'
          type: array
          title: Items
        page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Page Token
          description: Opaque cursor for the next page; empty/absent on the last page.
        row_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Row Count
          description: >-
            Best-effort total for the filtered result set; may be null when
            expensive.
      type: object
      required:
        - items
      title: ListResponse[QueryInsightV2]
    QueryInsightV2:
      properties:
        id:
          type: string
          title: Id
          description: Identifier of this finding, stable for this query execution.
          readOnly: true
          x-terraform-computed: true
        insight_type:
          type: string
          enum:
            - excessive_data_spillage
            - exploding_joins
            - inappropriate_warehouse_size
            - incrementalize_dbt_model
            - incrementalize_query
            - ineffective_query_pruning
            - inefficient_cortex_function_usage
            - redundant_operations
            - scanning_many_columns
            - subminute_query_on_large_warehouse
          title: Insight Type
          description: The kind of optimization opportunity that was found.
          readOnly: true
          x-terraform-computed: true
        effort:
          type: string
          enum:
            - low
            - medium
            - high
          title: Effort
          description: Estimated effort required to act on the recommendation.
          readOnly: true
          x-terraform-computed: true
        potential_savings:
          anyOf:
            - type: number
            - type: 'null'
          title: Potential Savings
          description: >-
            Estimated saving if the recommendation is applied, expressed in
            `potential_savings_unit`. Null when no estimate is available for
            this insight type.
          readOnly: true
          x-terraform-computed: true
        potential_savings_unit:
          anyOf:
            - type: string
              enum:
                - usd
                - gigabytes
                - fraction_of_runtime
                - fraction_of_billed_time
            - type: 'null'
          title: Potential Savings Unit
          description: >-
            Unit of `potential_savings`. `usd` is the cost of this single
            execution and is not annualized; `gigabytes` is data scanned; the
            `fraction_` units are proportions, normally between 0 and 1.
          readOnly: true
          x-terraform-computed: true
        recommendation:
          anyOf:
            - type: string
            - type: 'null'
          title: Recommendation
          description: What to change, in plain language.
          readOnly: true
          x-terraform-computed: true
        code_change_available:
          type: boolean
          title: Code Change Available
          description: >-
            Whether a suggested rewrite of the query can be generated for this
            finding.
          readOnly: true
          x-terraform-computed: true
        code_change_type:
          anyOf:
            - type: string
              enum:
                - query-pruning
                - incremental-query-pruning
                - incrementalize-dbt-query
                - incrementalize-ctas-query
                - inefficient-cortex-function-usage
            - type: 'null'
          title: Code Change Type
          description: >-
            The optimization discriminator to send when generating a code
            change. Null when this finding does not support that action.
          readOnly: true
          x-terraform-computed: true
      type: object
      required:
        - id
        - insight_type
        - effort
        - code_change_available
      title: QueryInsight
      description: |-
        An optimization opportunity found in a single query execution.

        Query insights come from the query's execution profile, so they are only
        available while Snowflake still retains that profile.
    ProblemDetail:
      additionalProperties: true
      description: >-
        RFC 9457-style error payload, served as ``application/problem+json``.


        ``code`` is the stable, machine-readable identifier — consumers branch
        on it,

        never on ``title``. ``type`` stays ``about:blank``: we keep no per-error

        documentation pages. There is no ``instance``/request-id member (we
        don't run

        access logs). See the flat error-code catalogue in §4 of the standards
        doc.
      properties:
        type:
          default: about:blank
          title: Type
          type: string
        title:
          type: string
          title: Title
        status:
          title: Status
          type: integer
        detail:
          title: Detail
          type: string
        code:
          title: Code
          type: string
        retryable:
          title: Retryable
          type: boolean
        details:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          default: null
          title: Details
      required:
        - title
        - status
        - detail
        - code
        - retryable
      title: ProblemDetail
      type: object
  responses:
    BadRequest:
      description: Bad request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        WWW-Authenticate:
          description: Authentication challenge for the requested resource.
          required: true
          schema:
            type: string
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    MethodNotAllowed:
      description: Method not allowed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Allow:
          description: HTTP methods supported by the requested resource.
          required: true
          schema:
            type: string
    RequestTimeout:
      description: Request Timeout
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ValidationFailed:
      description: Validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    RateLimited:
      description: Rate limited
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
    InternalError:
      description: Internal error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ServiceUnavailable:
      description: Service unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          required: true
          schema:
            type: integer
            minimum: 0
  securitySchemes:
    HTTPBearer:
      type: http
      description: Organization API key (sl_…).
      scheme: bearer

````