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

# SQL query

> Run a SQL query against the Cube [SQL API](/reference/core-data-apis/sql-api) and stream the results. The response is newline-delimited JSON: the first line carries the `schema` (column names and types) and optionally `lastRefreshTime`; each subsequent line carries a `data` chunk with one or more result rows.



## OpenAPI

````yaml /api-reference/core-data.yaml post /v1/cubesql
openapi: 3.0.0
info:
  title: Cube Core Data REST (JSON) API
  version: 1.0.0
  description: |-
    Deliver data from Cube over HTTP. Run queries with `POST /v1/load` and
    retrieve the data model with `GET /v1/meta`. The `{base_path}` segment
    (`/cubejs-api` by default) is configurable.
servers:
  - url: https://{deployment}.{region}.cubecloudapp.dev/cubejs-api
    description: >-
      Cube Cloud deployment REST API. The host includes your deployment slug and
      region; copy the exact URL from your deployment's API settings. The
      /cubejs-api base path is configurable.
    variables:
      deployment:
        default: your-deployment
        description: Your Cube Cloud deployment slug
      region:
        default: aws-us-east-1
        description: >-
          Cloud region of your deployment, e.g. aws-us-east-1, aws-eu-central-1,
          gcp-us-central1
  - url: http://localhost:4000/cubejs-api
    description: Self-hosted Cube (default port and base path).
security:
  - apiToken: []
tags:
  - name: Data
paths:
  /v1/cubesql:
    post:
      tags:
        - Data
      summary: SQL query
      description: >-
        Run a SQL query against the Cube [SQL
        API](/reference/core-data-apis/sql-api) and stream the results. The
        response is newline-delimited JSON: the first line carries the `schema`
        (column names and types) and optionally `lastRefreshTime`; each
        subsequent line carries a `data` chunk with one or more result rows.
      operationId: cubesqlV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: The SQL query to run.
                timezone:
                  type: string
                  description: >-
                    Time zone for the query in TZ database name format, e.g.
                    America/Los_Angeles.
                cache:
                  type: string
                  enum:
                    - stale-if-slow
                    - stale-while-revalidate
                    - must-revalidate
                    - no-cache
                  default: stale-if-slow
                  description: >-
                    In-memory cache strategy (see [Cache
                    control](/reference/core-data-apis/rest-api#cache-control)):


                    - `stale-if-slow` (default): if refresh keys are up to date,
                    return the cached value; if expired, fetch fresh data but
                    fall back to the stale value when the source query is slow.

                    - `stale-while-revalidate`: if expired, return stale data
                    immediately and refresh the cache in the background.

                    - `must-revalidate`: if expired, always wait for fresh data
                    from the source, even if slow.

                    - `no-cache`: skip refresh-key checks and always query the
                    data source.
      responses:
        '200':
          description: >-
            Newline-delimited JSON stream. The first line carries `schema` (and
            optionally `lastRefreshTime`); subsequent lines carry `data` chunks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        column_type:
                          type: string
                  lastRefreshTime:
                    type: string
                    format: date-time
                  data:
                    type: array
                    items:
                      type: array
                      items: {}
              examples:
                schemaLine:
                  summary: First line (schema)
                  value:
                    schema:
                      - name: value
                        column_type: Int64
                    lastRefreshTime: '2025-01-13T12:00:00.000Z'
                dataLine:
                  summary: Data chunk
                  value:
                    data:
                      - - '123'
      security:
        - apiToken: []
components:
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Cube API token (a JWT). Sent directly in the Authorization header, e.g.
        `Authorization: <CUBE_API_TOKEN>` (no "Bearer" prefix).

````