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

# Get query plan and timings

> Get the query plan and timings for a statement.



## OpenAPI

````yaml /openapi/query-sql.yaml get /api/v2/sql/statements/{id}/explain-analyze
openapi: 3.1.0
info:
  title: Query Engine SQL REST API (v2)
  version: '2.0'
  description: >
    The HTTP REST v2 API runs SQL on e6data over HTTPS. It is a
    language-agnostic, firewall-friendly

    alternative to the other connection protocols.


    It is a two-step flow: authenticate once for a short-lived session token,
    then submit statements

    and read results. Submission is asynchronous: you get a `statement_id`, poll
    for completion, then

    fetch result chunks.


    **HTTP/2 is required.** Use an HTTP/2-capable client and don't force curl's
    `--http2` flag; ALPN

    negotiates HTTP/2 automatically. In Python, use `httpx` with HTTP/2 support
    (`pip install "httpx[http2]"`)

    rather than `requests`.


    Use the v2 path (`/api/v2/sql/statements`), not the older `/api/v1/query`
    path.


    Statement states: `PENDING` → `RUNNING` → `SUCCEEDED` (or `FAILED` /
    `CANCELLED`).


    Suspended clusters auto-resume on the first statement. The request waits
    while the cluster resumes (about 30–90 seconds).


    ## Errors


    Errors follow a consistent format with an `error` object containing `code`,
    `message`, and `details`.

    Besides the HTTP-status-mapped codes listed on each operation, the API can
    return these query

    lifecycle codes:


    | Code | Meaning |

    | --- | --- |

    | `QUERY_CANCELLED` | Query was cancelled. |

    | `QUERY_TIMEOUT` | Query exceeded the configured timeout. Tune the query or
    raise the timeout. |

    | `QUERY_FAILED` | Query failed during execution. Read `details` for the
    underlying error. |

    | `RESULT_EXPIRED` | Query results are no longer available. Results
    retention is typically 24 hours; rerun the query. |

    | `RESULT_TOO_LARGE` | Result set exceeds the maximum response size. Use
    pagination. |
servers:
  - url: https://{host}
    description: Your e6data cluster endpoint.
    variables:
      host:
        default: your-host
        description: >-
          The host of your e6data REST endpoint (the `<HOST>` in
          `https://<HOST>/api/v2/sql/statements`).
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Exchange credentials for a session token.
  - name: Statements
    description: >-
      Submit SQL statements, poll their status, page through results, and cancel
      or clean up.
paths:
  /api/v2/sql/statements/{id}/explain-analyze:
    get:
      tags:
        - Statements
      summary: Get query plan and timings
      description: Get the query plan and timings for a statement.
      operationId: explainAnalyzeStatement
      parameters:
        - $ref: '#/components/parameters/StatementId'
        - $ref: '#/components/parameters/ClusterName'
        - $ref: '#/components/parameters/SessionId'
      responses:
        '200':
          description: Query plan and timings.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AuthError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ClusterUnavailable'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
        - {}
components:
  parameters:
    StatementId:
      name: id
      in: path
      required: true
      description: The `statement_id` returned when you submitted the statement.
      schema:
        type: string
    ClusterName:
      name: cluster-name
      in: header
      required: true
      description: The target cluster. Required on all requests.
      schema:
        type: string
    SessionId:
      name: X-Session-Id
      in: header
      required: false
      description: >-
        The `session_id` returned when you submitted the statement. Reuse it
        while polling and paging to skip re-authentication.
      schema:
        type: string
  responses:
    BadRequest:
      description: >
        Request error. Possible codes:

        `INVALID_REQUEST` (malformed JSON or missing required fields),

        `INVALID_QUERY` (SQL syntax error),

        `CLUSTER_NOT_FOUND` (named cluster doesn't exist),

        `CATALOG_NOT_FOUND` (catalog doesn't exist or isn't attached to the
        cluster),

        `SCHEMA_NOT_FOUND` (schema isn't in the catalog),

        `TABLE_NOT_FOUND` (table doesn't exist in the schema),

        `INVALID_PARAMETER` (query parameter binding failed).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AuthError:
      description: >
        Authentication or authorization error (HTTP 401 or 403). Possible codes:

        `UNAUTHENTICATED` (no or invalid token; check the `Authorization`
        header),

        `TOKEN_EXPIRED` (token has expired; generate a new token),

        `TOKEN_REVOKED` (token was revoked; generate a new token),

        `PERMISSION_DENIED` (the token can't perform this action; check its role
        or scope).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >
        Rate limited. Possible codes:

        `RATE_LIMITED` (too many requests; honor the `Retry-After` header and
        reduce the request rate),

        `CONCURRENT_LIMIT` (too many concurrent queries on this cluster; wait or
        increase cluster size).
      headers:
        Retry-After:
          description: How long to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClusterUnavailable:
      description: >
        Resource error. Possible codes:

        `CLUSTER_SUSPENDED` (cluster is suspended; it auto-resumes if
        configured, otherwise resume it manually),

        `CLUSTER_PROVISIONING` (cluster is being created; wait for it to become
        Running),

        `CLUSTER_UNAVAILABLE` (cluster has an error preventing queries; check
        the cluster status).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >
        Server error. Possible codes:

        `INTERNAL_ERROR` (unexpected server error; retry, and if it persists
        contact support with the query ID),

        `SERVICE_UNAVAILABLE` (backend temporarily unavailable; retry with
        backoff).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable description of the error.
            details:
              type: object
              description: Additional information about the error.
      example:
        error:
          code: QUERY_TIMEOUT
          message: Query exceeded the configured timeout
          details: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Send `Authorization: Bearer <session>` using the `sessionId` returned by
        `POST /api/v1/authenticate`.

        You can also send a personal access token or service account key
        directly as the bearer token,

        or use an SSO/OIDC JWT.

````

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