Cortex Analyst REST API

Use this API to answer questions about your data with natural language queries.

Send message

POST /api/v2/cortex/analyst/message

Generates a SQL query for the given question using the semantic model provided in the request. You can have multi-turn conversations where you can ask follow-up questions that build upon previous queries. For more information, see Multi-turn conversation in Cortex Analyst.

The request includes a user question and the response includes the user question and the analyst response. Each message in a response can have multiple content blocks of different types. Three values that are currently supported for the type field of the content object are: text, suggestions, and sql.

Request Headers

Header

Description

Authorization

(Required) Authorization token. For more information, see Authenticating to the server.

X-Snowflake-Authorization-Token-Type

Authorization token type. Defaults to OAuth; required if using any other type of token. For more information, see Authenticating to the server.

Content-Type

(Required) application/json

Request Body

The request body contains the role of the speaker which must be user, the user’s question and a path to the semantic model YAML file. The user question is contained in a content object which has two fields, type and text. text is also the only allowed value of the field type.

Field

Description

messages[].role

(Required) The role of the entity that is creating the message. Currently only supports user.

Type: string:enum

Example: user

messages[].content[]

(Required) The content object that is part of a message.

Type: object

Example:

{
  "type": "text",
  "text":  "Which company had the most revenue?"
}
Copy

messages[].content[].type

(Required) The content type. Currently only text is supported.

Type: string:enum

Example: text

messages[].content[].text

(Required) The user’s question.

Type: string

Example: Which company had the most revenue?

semantic_model_file

Path to the semantic model YAML file. Must be a fully qualified stage URL including the database and schema. You can instead provide the complete semantic model YAML in the semantic_model field.

Type: string

Example: @my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

A string containing the entire semantic model YAML. You can instead pass the semantic model YAML as a staged file by providing its URL in the semantic_model_file field.

Type: string

Important

You must provide either semantic_model_file or semantic_model in the request body.

Example

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        }
    ],
    "semantic_model_file": "@my_stage/my_semantic_model.yaml"
}
Copy

Response

This operation can return the response codes listed below. The response always has the following structure. Currently, three content types are supported for the response, text, suggestion, and sql. The content types suggestion and sql are mutually exclusive so that if the response contains a sql content type, it won’t contain a suggestion content type. The suggestion content type is only included in a response if the user question was ambiguous and Cortex Analyst could not return a SQL statement for that query.

To ensure forward compatibility, make sure your implementation takes the content type into account and handles types.

Code

Description

200

The statement was executed successfully.

The body of the response contains a message object that contains the following fields:

  • message: Messages of the conversation between the user and analyst.

  • message (object): Represents a message within a chat.

  • message.role (string:enum): The entity that produced the message. One of user or analyst.

  • message.content[] (object): The content object that is part of a message.

  • message.content[].type (string:enum): The content type of the message. One of text, suggestion, or sql.

  • message.content[].text (string): The text of the content. Only returned for content type text.

  • message.content[].statement (string): A SQL statement. Only returned for content type sql.

  • message.content[].confidence (object): Contains confidence-related information. Only returned for the sql content type.

  • message.content[].confidence.verified_query_used (object): Represents the verified query from Verified Query Repository used in SQL response generation. If no verified query used, the field value is null.

  • message.content[].confidence.verified_query_used.name (string): The name of the verified query used, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.question (string): The question that is answered by the verified query, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.sql (string): The SQL statement of the verified query used, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.verified_at (integer): The numeric representation of the timestamp when the query is verified, extracted from the Verified Query Repository.

  • message.content[].confidence.verified_query_used.verified_by (string): The person who verified the query, extracted from the Verified Query Repository.

  • message.content[].suggestions (string): If SQL cannot be generated, a list of questions the semantic model can generate SQL for. Only returned for content type suggestion.

  • message.content[].warnings: List of warnings from the analyst about the user’s request.

  • message.content[].warnings (list): Represents a collection of warnings regarding user requests and semantic models.

  • message.content[].warnings[].message (string): Contains a detailed description of one individual warning.

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ]
}
Copy

Send feedback

POST /api/v2/cortex/analyst/feedback

Provides qualitative end user feedback. Within Snowsight, the feedback is shown in Semantic Model Admins under Monitoring.

Request Headers

Header

Description

Authorization

(Required) Authorization token. For more information, see Authenticating to the server.

Content-Type

(Required) application/json

Request Body

Field

Description

request_id

(Required) The id of the request that you’ve made to send a message. Returned in the request_id field of /api/v2/cortex/analyst/message. For more information, see Response.

Type: string

Example: 75d343ee-699c-483f-83a1-e314609fb563

positive

(Required) Whether the feedback is positive or negative. true for positive or “thumbs up”, false for negative or “thumbs down”.

Type: boolean

Example:

true

feedback_message

(Optional) The feedback message from the user.

Example: This is the best answer I've ever seen!

Response

Empty response body with status code 200.

Access control requirements

For information on the required privileges, see Access control requirements.

For details about authenticating to the API, see Authenticating Snowflake REST APIs with Snowflake.

Language: English