Reference
AI API

AI API reference

The AI API provides the following endpoints.

/query/completions

Generate a Cube query that can be used to answer a user's question, and (optionally) run the query and return its results.

ParameterRequiredDescription
messages✅ YesAn array of messages in the format: { "role": "user" | "assistant", "content": "string" }
viewsAn array of view names (used to limit the views that the AI API can use to generate its answer)
runQueryBoolean (true or false) whether to run the query and return its results
optionsAn object in the format { "chart": true | false }

Response

  • message - A message from the AI assistant describing the query, how it was chosen, why it could not generate the requested query, etc.
  • cube_query - A Cube Query that could be used to answer the given question
  • chart - If the chart option is set to true, an object containing a chart spec for the generated query in the following format: 
    {
    "type": "bar" | "line" | "pie" | "table" | "area" | "scatter",
    "x": string,
    "y": string[],
    "pivot": string // optional; the field to pivot by, if any
}

Examples

Without runQuery

Example request:

curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 --data '{ "messages": [{ "role": "user", "content": "What cities have the highest aov this year?", "views": ["orders_view"] }]}' \
 https://YOUR_CUBE_API/cubejs-api/v1/ai/query/completions

Example response:

{
  "message": "To find the cities with the highest Average Order Value (AOV) this year, we can use the Orders View. This query will aggregate data to calculate the average order value per city for the current year.",
  "cube_query": {
    "measures": ["orders_view.average_order_value"],
    "dimensions": ["orders_view.users_city"],
    "timeDimensions": [
      {
        "dimension": "orders_view.created_at",
        "granularity": "year",
        "dateRange": "this year"
      }
    ],
    "order": {
      "orders_view.average_order_value": "desc"
    },
    "limit": 10
  }
}

With runQuery

curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 --data '{ "messages": [{ "role": "user", "content": "What cities had the highest aov last year?" }], "runQuery": true}' \
 https://YOUR_CUBE_API/cubejs-api/v1/ai/query/completions

Example response:

{
    "message": "To find the city with the highest average order value for last year, we'll analyze the data by city and calculate the average order value for each. The query will group the results by users' city and sort them to identify the city with the highest average order value.",
    "cube_query": {
        "measures": [
            "orders_view.average_order_value"
        ],
        "dimensions": [
            "orders_view.users_city"
        ],
        "timeDimensions": [
            {
                "dimension": "orders_view.created_at",
                "dateRange": "last year",
                "granularity": "year"
            }
        ],
        "order": {
            "orders_view.average_order_value": "desc"
        },
        "limit": 1
    }
}
{
    "query": {
        "measures": [
            "orders_view.average_order_value"
        ],
        "dimensions": [
            "orders_view.users_city"
        ],
        "timeDimensions": [
            {
                "dimension": "orders_view.created_at",
                "dateRange": [
                    "2023-01-01T00:00:00.000",
                    "2023-12-31T23:59:59.999"
                ],
                "granularity": "year"
            }
        ],
        "order": [
            {
                "id": "orders_view.average_order_value",
                "desc": true
            }
        ],
        "limit": 1,
        "timezone": "UTC",
        "filters": [],
        "rowLimit": 1
    },
    "data": [
        {
            "orders_view.users_city": "San Francisco",
            "orders_view.created_at.year": "2023-01-01T00:00:00.000",
            "orders_view.created_at": "2023-01-01T00:00:00.000",
            "orders_view.average_order_value": "322.619048"
        }
    ],
    "lastRefreshTime": "2024-05-08T18:24:14.623Z",
    "annotation": {
        "measures": {
            "orders_view.average_order_value": {
                "title": "Orders View Average Order Value",
                "shortTitle": "Average Order Value",
                "type": "number",
                "drillMembers": [],
                "drillMembersGrouped": {
                    "measures": [],
                    "dimensions": []
                }
            }
        },
        "dimensions": {
            "orders_view.users_city": {
                "title": "Orders View Users City",
                "shortTitle": "Users City",
                "type": "string"
            }
        },
        "segments": {},
        "timeDimensions": {
            "orders_view.created_at.year": {
                "title": "Orders View Created at",
                "shortTitle": "Created at",
                "type": "time"
            },
            "orders_view.created_at": {
                "title": "Orders View Created at",
                "shortTitle": "Created at",
                "type": "time"
            }
        }
    },
    "dataSource": "default",
    "dbType": "snowflake",
    "extDbType": "cubestore",
    "external": false,
    "slowQuery": false,
    "total": null
}
GraphQL APIcore