Conversation

View as Markdown

A Genie conversation. Use chat-mode message endpoints for classic chats and agent-mode response and item endpoints for agent conversations. Conversation management, feedback, comments, and attachment operations support both modes.

GenieConversation object

idstringuuidDeprecatedOutput only: Conversation ID. Legacy identifier, use conversation_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuid: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64uuidOutput only: ID of the user who created the conversation
Example: e1ef34712a29169db030324fd0e1df5f

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

titlestring: Conversation title

conversation_idstringuuid: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

View as Markdown

The GenieConversation object

{
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "e1ef34712a29169db030324fd0e1df5f",
  "user_id": "e1ef34712a29169db030324fd0e1df5f",
  "created_timestamp": 0,
  "last_updated_timestamp": 0,
  "title": "string",
  "conversation_id": "e1ef34712a29169db030324fd0e1df5f"
}

List conversations GA

GET /api/2.0/genie/spaces/{space_id}/conversations

Get a list of conversations in a Genie Space.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID of the Genie space to retrieve conversations from.
Example: e1ef34712a29169db030324fd0e1df5f

page_sizeint32<= 100query: Maximum number of conversations to return per page
Default: 20

page_tokenstringquery: Token to get the next page of results

include_allbooleanquery: Include all conversations in the space across all users. Requires at least CAN MANAGE permission on the space.
Default: false

Response

conversationsarray of object

List of conversations in the Genie space

Show child attributesHide child attributes

conversation_idstringuuidRequired: Example: e1ef34712a29169db030324fd0e1df5f

titlestringOutput only: Example: Biggest open opportunities

created_timestampint64Output only

agent_typestringOutput only

Whether this is a classic chat or an agent-mode conversation. Allows callers to route message retrieval (chat vs. agent endpoint) without an extra lookup.

Values:

GENIE_CONVERSATION_TYPE_UNSPECIFIED
GENIE_CONVERSATION_TYPE_CHAT
GENIE_CONVERSATION_TYPE_AGENT

next_page_tokenstring: Token to get the next page of results

View as Markdown

Response

{
  "conversations": [
    {
      "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
      "title": "Biggest open opportunities",
      "created_timestamp": 0,
      "agent_type": "GENIE_CONVERSATION_TYPE_CHAT"
    }
  ],
  "next_page_token": "string"
}

Delete a conversation GA

DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}

Delete a conversation.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the conversation is located.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID of the conversation to delete.
Example: e1ef34712a29169db030324fd0e1df5f

Chat mode: Send a message GA

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages

Sends a new message in a chat-mode conversation. The AI response uses all previously created messages in the conversation to respond.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the conversation is started.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

Request body

contentstringRequired: User message content.
Example: Biggest open opportunities

enable_visualizationboolean: Enable visualization generation.
Example: true

Response

idstringuuidDeprecatedOutput only: Message ID. Legacy identifier, use message_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the message

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

statusstringOutput only

MessageStatus. The possible values are:

FETCHING_METADATA: Fetching metadata from the data sources.
FILTERING_CONTEXT: Running smart context step to determine relevant context.
ASKING_AI: Waiting for the LLM to respond to the user's question.
PENDING_WAREHOUSE: Waiting for warehouse before the SQL query can start executing.
EXECUTING_QUERY: Executing a generated SQL query. Get the SQL query result by calling getMessageAttachmentQueryResult API.
FAILED: The response generation or query execution failed. See error field.
COMPLETED: Message processing is completed. Results are in the attachments field. Get the SQL query result by calling getMessageAttachmentQueryResult API.
SUBMITTED: Message has been submitted.
QUERY_RESULT_EXPIRED: SQL result is not available anymore. The user needs to rerun the query. Rerun the SQL query result by calling executeMessageAttachmentQuery API.
CANCELLED: Message has been cancelled.

Values:

FETCHING_METADATA
FILTERING_CONTEXT
ASKING_AI
PENDING_WAREHOUSE
EXECUTING_QUERY
FAILED
COMPLETED
SUBMITTED
QUERY_RESULT_EXPIRED
CANCELLED

Example: ASKING_AI

contentstringRequired: User message content
Example: Biggest open opportunities

attachmentsarray of objectOutput only

AI-generated response to the message

Show child attributesHide child attributes

textobjectOutput only

Text Attachment if Genie responds with text This also contains the final summary when available.

Show child attributesHide child attributes

contentstring: AI generated message

idstring

purposestring

Purpose of this text attachment. A completed message may contain more than one text attachment (for example a clarifying follow-up question alongside the final answer); use this field to tell them apart. TEXT_ATTACHMENT_PURPOSE_ANSWER marks the final answer/summary and FOLLOW_UP_QUESTION marks a clarifying question.

Values:

TEXT_ATTACHMENT_PURPOSE_UNSPECIFIED
FOLLOW_UP_QUESTION
TEXT_ATTACHMENT_PURPOSE_ANSWER

queryobjectOutput only

Query Attachment if Genie responds with a SQL query

Show child attributesHide child attributes

titlestring: Name of the query

querystring: AI generated SQL query

descriptionstring: Description of the query

last_updated_timestampint64Output only: Time when the user updated the query last

parametersarray of object

Show child attributesHide child attributes

keywordstring

valuestring

sql_typestring

idstringDeprecatedOutput only

statement_idstringOutput only: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

query_result_metadataobjectOutput only

Metadata associated with the query result.

Show child attributesHide child attributes

row_countint64Output only: The number of rows in the result set.

is_truncatedbooleanOutput only: Indicates whether the result set is truncated.

thoughtsarray of objectPublic PreviewOutput only

Insights into how Genie came to generate the SQL.

Show child attributesHide child attributes

thought_typestringPublic PreviewOutput only

The category of this thought. The possible values are:

THOUGHT_TYPE_DESCRIPTION: A high-level description of how the question was interpreted.
THOUGHT_TYPE_UNDERSTANDING: How ambiguous parts of the question were resolved.
THOUGHT_TYPE_DATA_SOURCING: Which tables or datasets were identified as relevant.
THOUGHT_TYPE_INSTRUCTIONS: Which author-defined instructions were referenced.
THOUGHT_TYPE_STEPS: The logical steps taken to compute the answer.

Values:

THOUGHT_TYPE_UNSPECIFIED
THOUGHT_TYPE_DESCRIPTION
THOUGHT_TYPE_UNDERSTANDING
THOUGHT_TYPE_DATA_SOURCING
THOUGHT_TYPE_INSTRUCTIONS
THOUGHT_TYPE_STEPS

contentstringPublic PreviewOutput only: The md formatted content for this thought.

suggested_questionsobjectOutput only

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of stringOutput only: The suggested follow-up questions

vizobjectOutput only

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringOutput only: Name of the visualization

query_attachment_idstringOutput only: The ID of the query attachment the visualization was generated from

attachment_idstringOutput only: Attachment ID

query_resultobjectDeprecatedOutput only

The result of SQL query if the message includes a query attachment. Deprecated. Use query_result_metadata in GenieQueryAttachment instead.

Show child attributesHide child attributes

statement_idstring: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

row_countint64: Row count of the result

is_truncatedboolean: If result is truncated

statement_id_signaturestring: JWT corresponding to the statement contained in this result

errorobjectOutput only

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring

Values:

Show 62 possible values

TYPE_UNSPECIFIED
UNEXPECTED_REPLY_PROCESS_EXCEPTION
GENERIC_CHAT_COMPLETION_EXCEPTION
CONTEXT_EXCEEDED_EXCEPTION
DEPLOYMENT_NOT_FOUND_EXCEPTION
FUNCTIONS_NOT_AVAILABLE_EXCEPTION
INVALID_COMPLETION_REQUEST_EXCEPTION
CONTENT_FILTER_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION
RETRYABLE_PROCESSING_EXCEPTION
INVALID_FUNCTION_CALL_EXCEPTION
LOCAL_CONTEXT_EXCEEDED_EXCEPTION
CHAT_COMPLETION_NETWORK_EXCEPTION
INVALID_CHAT_COMPLETION_JSON_EXCEPTION
GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION
WAREHOUSE_ACCESS_MISSING_EXCEPTION
WAREHOUSE_NOT_FOUND_EXCEPTION
NO_TABLES_TO_QUERY_EXCEPTION
SQL_EXECUTION_EXCEPTION
REPLY_PROCESS_TIMEOUT_EXCEPTION
COULD_NOT_GET_UC_SCHEMA_EXCEPTION
INVALID_TABLE_IDENTIFIER_EXCEPTION
TOO_MANY_TABLES_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_EXCEPTION
GENERIC_SQL_EXEC_API_CALL_EXCEPTION
CHAT_COMPLETION_CLIENT_EXCEPTION
CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION
UNKNOWN_AI_MODEL
TABLES_MISSING_EXCEPTION
MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION
MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION
BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION
INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION
TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION
RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION
RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION
FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION
INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION
ILLEGAL_PARAMETER_DEFINITION_EXCEPTION
NO_QUERY_TO_VISUALIZE_EXCEPTION
NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE
STOP_PROCESS_DUE_TO_AUTO_REGENERATE
FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION
MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION
COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION
GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION
MISSING_SQL_QUERY_EXCEPTION
DESCRIBE_QUERY_UNEXPECTED_FAILURE
DESCRIBE_QUERY_TIMEOUT
DESCRIBE_QUERY_INVALID_SQL_ERROR
INVALID_SQL_UNKNOWN_TABLE_EXCEPTION
INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION
INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION
MESSAGE_ATTACHMENT_TOO_LONG_ERROR
INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION
INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION
EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION
UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION
COULD_NOT_GET_DASHBOARD_SCHEMA_EXCEPTION

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobjectOutput only

User feedback for the message if provided

Show child attributesHide child attributes

ratingstring

The feedback rating

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstringPublic Preview: Optional feedback comment text

View as Markdown

Request

{
  "content": "Give me top sales for last month"
}

Response

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

{
  "attachments": [
    {
      "attachment_id": "b3c4d5e6f708901234567890abcdef01",
      "text": {
        "content": "Your top sales last month came from the West region with $1.2M in revenue across 340 deals."
      }
    },
    {
      "attachment_id": "c4d5e6f70890123456789012abcdef02",
      "query": {
        "description": "Retrieves top performing sales region for last month by revenue",
        "last_updated_timestamp": 1719769718,
        "query": "SELECT r.region_name, SUM(s.revenue) AS total_revenue, COUNT(s.deal_id) AS deal_count FROM catalog.schema.sales_2024 s JOIN catalog.schema.regions r ON s.region_id = r.region_id WHERE s.sale_date BETWEEN '2024-06-01' AND '2024-06-30' GROUP BY r.region_name ORDER BY total_revenue DESC LIMIT 1",
        "query_result_metadata": {
          "row_count": 1
        },
        "statement_id": "9d8836fc1bdb4729a27fcc07614b52c4",
        "thoughts": [
          {
            "content": "The user wants to know which region had the highest sales last month. The query aggregates revenue from the sales table, grouped by region.",
            "thought_type": "THOUGHT_TYPE_DESCRIPTION"
          },
          {
            "content": "- Definition of 'top sales': Interpreted as the region with the highest total revenue for the month of June 2024.",
            "thought_type": "THOUGHT_TYPE_UNDERSTANDING"
          },
          {
            "content": "- catalog.schema.sales_2024\n- catalog.schema.regions",
            "thought_type": "THOUGHT_TYPE_DATA_SOURCING"
          },
          {
            "content": "- Filter the sales table to June 2024.\n- Join with the regions table on region_id.\n- Aggregate revenue and deal count by region.\n- Order by total revenue descending and return the top result.",
            "thought_type": "THOUGHT_TYPE_STEPS"
          },
          {
            "content": "- The Genie space is configured to always include deal count alongside revenue in sales queries.",
            "thought_type": "THOUGHT_TYPE_INSTRUCTIONS"
          }
        ],
        "title": "Top sales last month"
      }
    },
    {
      "attachment_id": "d5e6f708901234567890123456abcdef",
      "suggested_questions": {
        "questions": [
          "Can you filter to last quarter?",
          "Show top 5 by revenue",
          "What is the month-over-month trend?"
        ]
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "COMPLETED",
  "user_id": 12345
}

{
  "attachments": [
    {
      "attachment_id": "01f0838b7adc123e86447829f57b9572",
      "query": {
        "description": "Retrieves the top sales region for last month by joining sales and regions tables, aggregating revenue and deal count, and returning the highest-revenue region",
        "last_updated_timestamp": 1719769718,
        "query": "SELECT r.region_name, SUM(s.revenue) AS total_revenue, COUNT(s.deal_id) AS deal_count FROM catalog.schema.sales_2024 s JOIN catalog.schema.regions r ON s.region_id = r.region_id WHERE s.sale_date BETWEEN '2024-06-01' AND '2024-06-30' GROUP BY r.region_name ORDER BY total_revenue DESC LIMIT 1",
        "query_result_metadata": {
          "row_count": 1
        },
        "statement_id": "9d8836fc1bdb4729a27fcc07614b52c4",
        "thoughts": [
          {
            "content": "The user is asking about top sales performance for the previous month. The result shows the region, total revenue, and deal count, ordered by revenue descending and limited to the top result.",
            "thought_type": "THOUGHT_TYPE_DESCRIPTION"
          },
          {
            "content": "- Definition of 'top sales': The query assumes 'top sales' means the region with the highest total revenue. Alternative interpretations could consider deal count or average deal size.",
            "thought_type": "THOUGHT_TYPE_UNDERSTANDING"
          },
          {
            "content": "- catalog.schema.sales_2024\n- catalog.schema.regions",
            "thought_type": "THOUGHT_TYPE_DATA_SOURCING"
          },
          {
            "content": "- Filter the sales table to last month's date range.\n- Join with the regions table to get region names.\n- Aggregate revenue and deal count by region.\n- Order by total revenue descending.\n- Limit to the top result.",
            "thought_type": "THOUGHT_TYPE_STEPS"
          }
        ],
        "title": "Top sales by region last month"
      }
    },
    {
      "attachment_id": "a2b3c4d5e6f7089012345678abcdef90",
      "suggested_questions": {
        "questions": [
          "Can you filter to last quarter?",
          "Show top 5 by revenue",
          "What is the month-over-month trend?"
        ]
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "EXECUTING_QUERY",
  "user_id": 12345
}

{
  "attachments": [
    {
      "text": {
        "content": "Based on the data, your top sales last month were from the West region, totaling $1.2M in revenue across 340 deals."
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "COMPLETED",
  "user_id": 12345
}

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": {
    "error": "Human readable error message",
    "type": "TABLES_MISSING_EXCEPTION"
  },
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "EXECUTING_QUERY",
  "user_id": 12345
}

Add a comment to a message Public Preview

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments

Create a comment on a conversation message.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: The ID associated with the message.
Example: e1ef34712a29169db030324fd0e1df5f

Request body

contentstring<= 5000 charactersRequired: Comment text content.
Example: This query could be optimized by adding an index on the date column.

Response

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstringuuidRequired: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the comment

contentstring<= 5000 charactersRequired: Comment text content
Example: This query result looks correct.

created_timestampint64Output only: Timestamp when the comment was created

View as Markdown

Request

{
  "content": "This query could be optimized by adding an index on the date column."
}

Response

{
  "space_id": "e1ef34712a29169db030324fd0e1df5f",
  "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "message_comment_id": "e1ef34712a29169db030324fd0e1df5f",
  "user_id": 0,
  "content": "This query result looks correct.",
  "created_timestamp": 0
}

Agent mode: Cancel a response GA

POST /api/2.0/genie/agents/{agent_id}/conversations/{conversation_id}/responses/{response_id}/cancel

Cancels an in-flight agent-mode response. response_id is the id returned in the response.created event from the agent-mode responses endpoint. The response stops at the next agent boundary and its terminal state is returned.

API scopes: genie

Parameters

agent_idstringuuidRequiredpath: The ID of the Genie agent (synonymous with the Genie space ID).
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID of the conversation containing the response.
Example: e1ef34712a29169db030324fd0e1df5f

response_idstringuuidRequiredpath: The ID of the response to cancel (the id from the response.created event).
Example: e1ef34712a29169db030324fd0e1df5f

Response

idstringuuidDeprecatedOutput only: Message ID. Legacy identifier, use message_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the message

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

statusstringOutput only

MessageStatus. The possible values are:

FETCHING_METADATA: Fetching metadata from the data sources.
FILTERING_CONTEXT: Running smart context step to determine relevant context.
ASKING_AI: Waiting for the LLM to respond to the user's question.
PENDING_WAREHOUSE: Waiting for warehouse before the SQL query can start executing.
EXECUTING_QUERY: Executing a generated SQL query. Get the SQL query result by calling getMessageAttachmentQueryResult API.
FAILED: The response generation or query execution failed. See error field.
COMPLETED: Message processing is completed. Results are in the attachments field. Get the SQL query result by calling getMessageAttachmentQueryResult API.
SUBMITTED: Message has been submitted.
QUERY_RESULT_EXPIRED: SQL result is not available anymore. The user needs to rerun the query. Rerun the SQL query result by calling executeMessageAttachmentQuery API.
CANCELLED: Message has been cancelled.

Values:

FETCHING_METADATA
FILTERING_CONTEXT
ASKING_AI
PENDING_WAREHOUSE
EXECUTING_QUERY
FAILED
COMPLETED
SUBMITTED
QUERY_RESULT_EXPIRED
CANCELLED

Example: ASKING_AI

contentstringRequired: User message content
Example: Biggest open opportunities

attachmentsarray of objectOutput only

AI-generated response to the message

Show child attributesHide child attributes

textobjectOutput only

Text Attachment if Genie responds with text This also contains the final summary when available.

Show child attributesHide child attributes

contentstring: AI generated message

idstring

purposestring

Values:

TEXT_ATTACHMENT_PURPOSE_UNSPECIFIED
FOLLOW_UP_QUESTION
TEXT_ATTACHMENT_PURPOSE_ANSWER

queryobjectOutput only

Query Attachment if Genie responds with a SQL query

Show child attributesHide child attributes

titlestring: Name of the query

querystring: AI generated SQL query

descriptionstring: Description of the query

last_updated_timestampint64Output only: Time when the user updated the query last

parametersarray of object

Show child attributesHide child attributes

keywordstring

valuestring

sql_typestring

idstringDeprecatedOutput only

statement_idstringOutput only: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

query_result_metadataobjectOutput only

Metadata associated with the query result.

Show child attributesHide child attributes

row_countint64Output only: The number of rows in the result set.

is_truncatedbooleanOutput only: Indicates whether the result set is truncated.

thoughtsarray of objectPublic PreviewOutput only

Insights into how Genie came to generate the SQL.

Show child attributesHide child attributes

thought_typestringPublic PreviewOutput only

The category of this thought. The possible values are:

THOUGHT_TYPE_DESCRIPTION: A high-level description of how the question was interpreted.
THOUGHT_TYPE_UNDERSTANDING: How ambiguous parts of the question were resolved.
THOUGHT_TYPE_DATA_SOURCING: Which tables or datasets were identified as relevant.
THOUGHT_TYPE_INSTRUCTIONS: Which author-defined instructions were referenced.
THOUGHT_TYPE_STEPS: The logical steps taken to compute the answer.

Values:

THOUGHT_TYPE_UNSPECIFIED
THOUGHT_TYPE_DESCRIPTION
THOUGHT_TYPE_UNDERSTANDING
THOUGHT_TYPE_DATA_SOURCING
THOUGHT_TYPE_INSTRUCTIONS
THOUGHT_TYPE_STEPS

contentstringPublic PreviewOutput only: The md formatted content for this thought.

suggested_questionsobjectOutput only

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of stringOutput only: The suggested follow-up questions

vizobjectOutput only

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringOutput only: Name of the visualization

query_attachment_idstringOutput only: The ID of the query attachment the visualization was generated from

attachment_idstringOutput only: Attachment ID

query_resultobjectDeprecatedOutput only

The result of SQL query if the message includes a query attachment. Deprecated. Use query_result_metadata in GenieQueryAttachment instead.

Show child attributesHide child attributes

statement_idstring: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

row_countint64: Row count of the result

is_truncatedboolean: If result is truncated

statement_id_signaturestring: JWT corresponding to the statement contained in this result

errorobjectOutput only

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring

Values:

Show 62 possible values

TYPE_UNSPECIFIED
UNEXPECTED_REPLY_PROCESS_EXCEPTION
GENERIC_CHAT_COMPLETION_EXCEPTION
CONTEXT_EXCEEDED_EXCEPTION
DEPLOYMENT_NOT_FOUND_EXCEPTION
FUNCTIONS_NOT_AVAILABLE_EXCEPTION
INVALID_COMPLETION_REQUEST_EXCEPTION
CONTENT_FILTER_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION
RETRYABLE_PROCESSING_EXCEPTION
INVALID_FUNCTION_CALL_EXCEPTION
LOCAL_CONTEXT_EXCEEDED_EXCEPTION
CHAT_COMPLETION_NETWORK_EXCEPTION
INVALID_CHAT_COMPLETION_JSON_EXCEPTION
GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION
WAREHOUSE_ACCESS_MISSING_EXCEPTION
WAREHOUSE_NOT_FOUND_EXCEPTION
NO_TABLES_TO_QUERY_EXCEPTION
SQL_EXECUTION_EXCEPTION
REPLY_PROCESS_TIMEOUT_EXCEPTION
COULD_NOT_GET_UC_SCHEMA_EXCEPTION
INVALID_TABLE_IDENTIFIER_EXCEPTION
TOO_MANY_TABLES_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_EXCEPTION
GENERIC_SQL_EXEC_API_CALL_EXCEPTION
CHAT_COMPLETION_CLIENT_EXCEPTION
CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION
UNKNOWN_AI_MODEL
TABLES_MISSING_EXCEPTION
MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION
MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION
BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION
INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION
TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION
RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION
RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION
FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION
INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION
ILLEGAL_PARAMETER_DEFINITION_EXCEPTION
NO_QUERY_TO_VISUALIZE_EXCEPTION
NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE
STOP_PROCESS_DUE_TO_AUTO_REGENERATE
FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION
MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION
COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION
GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION
MISSING_SQL_QUERY_EXCEPTION
DESCRIBE_QUERY_UNEXPECTED_FAILURE
DESCRIBE_QUERY_TIMEOUT
DESCRIBE_QUERY_INVALID_SQL_ERROR
INVALID_SQL_UNKNOWN_TABLE_EXCEPTION
INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION
INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION
MESSAGE_ATTACHMENT_TOO_LONG_ERROR
INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION
INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION
EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION
UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION
COULD_NOT_GET_DASHBOARD_SCHEMA_EXCEPTION

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobjectOutput only

User feedback for the message if provided

Show child attributesHide child attributes

ratingstring

The feedback rating

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstringPublic Preview: Optional feedback comment text

View as Markdown

Response

{
  "id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "e1ef34712a29169db030324fd0e1df5f",
  "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
  "user_id": 0,
  "created_timestamp": 0,
  "last_updated_timestamp": 0,
  "status": "ASKING_AI",
  "content": "Biggest open opportunities",
  "attachments": [
    {
      "text": {},
      "query": {},
      "suggested_questions": {},
      "viz": {},
      "attachment_id": "string"
    }
  ],
  "query_result": {
    "statement_id": "string",
    "row_count": 0,
    "is_truncated": true,
    "statement_id_signature": "string"
  },
  "error": {
    "error": "string",
    "type": "UNEXPECTED_REPLY_PROCESS_EXCEPTION"
  },
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "feedback": {
    "rating": "POSITIVE",
    "comment": "string"
  }
}

Delete a conversation message GA

DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}

Delete a conversation message.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the message is located.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: The ID associated with the message to delete.
Example: e1ef34712a29169db030324fd0e1df5f

Execute an attachment SQL query GA

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/execute-query

Execute the SQL for a message query attachment. Use this API when the query attachment has expired and needs to be re-executed.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringuuidRequiredpath: Attachment ID
Example: e1ef34712a29169db030324fd0e1df5f

Response

statement_responseobject

SQL Statement Execution response. See Get status, manifest, and result first chunk for more details.

Show child attributesHide child attributes

statement_idstring: The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls.

statusobject

Show child attributesHide child attributes

statestring

Statement execution state:

PENDING: waiting for warehouse
RUNNING: running
SUCCEEDED: execution was successful, result data available for fetch
FAILED: execution failed; reason for failure described in accompanying error message
CANCELED: user canceled; can come from explicit cancel call, or timeout with on_wait_timeout=CANCEL
CLOSED: execution successful, and statement closed; result no longer available for fetch

Values:

STATE_UNSPECIFIED
PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
CLOSED

errorobject

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

sql_statestring: SQLSTATE error code returned when the statement execution fails. Only populated when the statement status is FAILED.

manifestobject

Show child attributesHide child attributes

formatstring

Values:

FORMAT_UNSPECIFIED
JSON_ARRAY
ARROW_STREAM
CSV

schemaobject

Show child attributesHide child attributes

column_countint32

columnsarray of object

total_chunk_countint32: The total number of chunks that the result set has been divided into.

chunksarray of object

Array of result set chunk metadata.

Show child attributesHide child attributes

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

total_row_countint64: The total number of rows in the result set.

total_byte_countint64: The total number of bytes in the result set. This field is not available when using INLINE disposition.

truncatedboolean: Indicates whether the result is truncated due to row_limit or byte_limit.

resultobject

Show child attributesHide child attributes

external_linksarray of object

Show child attributesHide child attributes

external_linkstring: A short-lived cloud-storage URL pointing to a chunk of result data, hosted by an external service, with a short expiration time (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive and the client should not expose this URL in a log.
AWS
On AWS, this is a presigned URL.
Azure
On Azure, this is a SAS URL.
GCP
On GCP, this is a signed URL.

expirationstringdate-time: Indicates the date-time that the given external link will expire and becomes invalid, after which point a new external_link must be requested.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

data_arrayarray of object

The JSON_ARRAY format is an array of arrays of values, where each non-null value is formatted as a string. Null values are encoded as JSON null.

Show child attributesHide child attributes

valuesarray of object: Repeated field of dynamically typed values.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

Start a full query-result download GA

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/downloads

Initiates a new SQL execution and returns a download_id and download_id_signature that you can use to track the progress of the download. The query result is stored in an external link and can be retrieved using the Get Download Full Query Result API. Both download_id and download_id_signature must be provided when calling the Get endpoint.

Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.

When you use the EXTERNAL_LINKS disposition, a short-lived cloud-storage URL is generated to download the results. The URL contains temporary access credentials, so protect it and do not set an Authorization header in the download request.

See Execute Statement for more details.

API scopes: genie

AWS

On AWS, the external link is a presigned URL for Amazon S3.

Azure

On Azure, the external link is a SAS URL for Azure Storage.

GCP

On GCP, the external link is a signed URL for Google Cloud Storage.

Parameters

space_idstringuuidRequiredpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringuuidRequiredpath: Attachment ID
Example: e1ef34712a29169db030324fd0e1df5f

Response

download_idstring: Download ID. Use this ID to track the download request in subsequent polling calls
Example: 01eda0e7-e315-1846-84e2-79a963ffad44

download_id_signaturestring: JWT signature for the download_id to ensure secure access to query results

Get a conversation message GA

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}

Gets a message from a chat-mode or agent-mode conversation. For a complete agent-mode transcript, use the List conversation items endpoint.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the target conversation is located.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the target conversation.
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: The ID associated with the target message from the identified conversation.
Example: e1ef34712a29169db030324fd0e1df5f

Response

idstringuuidDeprecatedOutput only: Message ID. Legacy identifier, use message_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the message

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

statusstringOutput only

MessageStatus. The possible values are:

FETCHING_METADATA: Fetching metadata from the data sources.
FILTERING_CONTEXT: Running smart context step to determine relevant context.
ASKING_AI: Waiting for the LLM to respond to the user's question.
PENDING_WAREHOUSE: Waiting for warehouse before the SQL query can start executing.
EXECUTING_QUERY: Executing a generated SQL query. Get the SQL query result by calling getMessageAttachmentQueryResult API.
FAILED: The response generation or query execution failed. See error field.
COMPLETED: Message processing is completed. Results are in the attachments field. Get the SQL query result by calling getMessageAttachmentQueryResult API.
SUBMITTED: Message has been submitted.
QUERY_RESULT_EXPIRED: SQL result is not available anymore. The user needs to rerun the query. Rerun the SQL query result by calling executeMessageAttachmentQuery API.
CANCELLED: Message has been cancelled.

Values:

FETCHING_METADATA
FILTERING_CONTEXT
ASKING_AI
PENDING_WAREHOUSE
EXECUTING_QUERY
FAILED
COMPLETED
SUBMITTED
QUERY_RESULT_EXPIRED
CANCELLED

Example: ASKING_AI

contentstringRequired: User message content
Example: Biggest open opportunities

attachmentsarray of objectOutput only

AI-generated response to the message

Show child attributesHide child attributes

textobjectOutput only

Text Attachment if Genie responds with text This also contains the final summary when available.

Show child attributesHide child attributes

contentstring: AI generated message

idstring

purposestring

Values:

TEXT_ATTACHMENT_PURPOSE_UNSPECIFIED
FOLLOW_UP_QUESTION
TEXT_ATTACHMENT_PURPOSE_ANSWER

queryobjectOutput only

Query Attachment if Genie responds with a SQL query

Show child attributesHide child attributes

titlestring: Name of the query

querystring: AI generated SQL query

descriptionstring: Description of the query

last_updated_timestampint64Output only: Time when the user updated the query last

parametersarray of object

Show child attributesHide child attributes

keywordstring

valuestring

sql_typestring

idstringDeprecatedOutput only

statement_idstringOutput only: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

query_result_metadataobjectOutput only

Metadata associated with the query result.

Show child attributesHide child attributes

row_countint64Output only: The number of rows in the result set.

is_truncatedbooleanOutput only: Indicates whether the result set is truncated.

thoughtsarray of objectPublic PreviewOutput only

Insights into how Genie came to generate the SQL.

Show child attributesHide child attributes

thought_typestringPublic PreviewOutput only

The category of this thought. The possible values are:

THOUGHT_TYPE_DESCRIPTION: A high-level description of how the question was interpreted.
THOUGHT_TYPE_UNDERSTANDING: How ambiguous parts of the question were resolved.
THOUGHT_TYPE_DATA_SOURCING: Which tables or datasets were identified as relevant.
THOUGHT_TYPE_INSTRUCTIONS: Which author-defined instructions were referenced.
THOUGHT_TYPE_STEPS: The logical steps taken to compute the answer.

Values:

THOUGHT_TYPE_UNSPECIFIED
THOUGHT_TYPE_DESCRIPTION
THOUGHT_TYPE_UNDERSTANDING
THOUGHT_TYPE_DATA_SOURCING
THOUGHT_TYPE_INSTRUCTIONS
THOUGHT_TYPE_STEPS

contentstringPublic PreviewOutput only: The md formatted content for this thought.

suggested_questionsobjectOutput only

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of stringOutput only: The suggested follow-up questions

vizobjectOutput only

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringOutput only: Name of the visualization

query_attachment_idstringOutput only: The ID of the query attachment the visualization was generated from

attachment_idstringOutput only: Attachment ID

query_resultobjectDeprecatedOutput only

The result of SQL query if the message includes a query attachment. Deprecated. Use query_result_metadata in GenieQueryAttachment instead.

Show child attributesHide child attributes

statement_idstring: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

row_countint64: Row count of the result

is_truncatedboolean: If result is truncated

statement_id_signaturestring: JWT corresponding to the statement contained in this result

errorobjectOutput only

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring

Values:

Show 62 possible values

TYPE_UNSPECIFIED
UNEXPECTED_REPLY_PROCESS_EXCEPTION
GENERIC_CHAT_COMPLETION_EXCEPTION
CONTEXT_EXCEEDED_EXCEPTION
DEPLOYMENT_NOT_FOUND_EXCEPTION
FUNCTIONS_NOT_AVAILABLE_EXCEPTION
INVALID_COMPLETION_REQUEST_EXCEPTION
CONTENT_FILTER_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION
RETRYABLE_PROCESSING_EXCEPTION
INVALID_FUNCTION_CALL_EXCEPTION
LOCAL_CONTEXT_EXCEEDED_EXCEPTION
CHAT_COMPLETION_NETWORK_EXCEPTION
INVALID_CHAT_COMPLETION_JSON_EXCEPTION
GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION
WAREHOUSE_ACCESS_MISSING_EXCEPTION
WAREHOUSE_NOT_FOUND_EXCEPTION
NO_TABLES_TO_QUERY_EXCEPTION
SQL_EXECUTION_EXCEPTION
REPLY_PROCESS_TIMEOUT_EXCEPTION
COULD_NOT_GET_UC_SCHEMA_EXCEPTION
INVALID_TABLE_IDENTIFIER_EXCEPTION
TOO_MANY_TABLES_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_EXCEPTION
GENERIC_SQL_EXEC_API_CALL_EXCEPTION
CHAT_COMPLETION_CLIENT_EXCEPTION
CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION
UNKNOWN_AI_MODEL
TABLES_MISSING_EXCEPTION
MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION
MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION
BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION
INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION
TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION
RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION
RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION
FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION
INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION
ILLEGAL_PARAMETER_DEFINITION_EXCEPTION
NO_QUERY_TO_VISUALIZE_EXCEPTION
NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE
STOP_PROCESS_DUE_TO_AUTO_REGENERATE
FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION
MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION
COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION
GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION
MISSING_SQL_QUERY_EXCEPTION
DESCRIBE_QUERY_UNEXPECTED_FAILURE
DESCRIBE_QUERY_TIMEOUT
DESCRIBE_QUERY_INVALID_SQL_ERROR
INVALID_SQL_UNKNOWN_TABLE_EXCEPTION
INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION
INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION
MESSAGE_ATTACHMENT_TOO_LONG_ERROR
INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION
INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION
EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION
UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION
COULD_NOT_GET_DASHBOARD_SCHEMA_EXCEPTION

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobjectOutput only

User feedback for the message if provided

Show child attributesHide child attributes

ratingstring

The feedback rating

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstringPublic Preview: Optional feedback comment text

View as Markdown

Response

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "IN_PROGRESS",
  "user_id": 12345
}

{
  "attachments": [
    {
      "attachment_id": "b3c4d5e6f708901234567890abcdef01",
      "text": {
        "content": "Your top sales last month came from the West region with $1.2M in revenue across 340 deals."
      }
    },
    {
      "attachment_id": "c4d5e6f70890123456789012abcdef02",
      "query": {
        "description": "Retrieves top performing sales region for last month by revenue",
        "last_updated_timestamp": 1719769718,
        "query": "SELECT r.region_name, SUM(s.revenue) AS total_revenue, COUNT(s.deal_id) AS deal_count FROM catalog.schema.sales_2024 s JOIN catalog.schema.regions r ON s.region_id = r.region_id WHERE s.sale_date BETWEEN '2024-06-01' AND '2024-06-30' GROUP BY r.region_name ORDER BY total_revenue DESC LIMIT 1",
        "query_result_metadata": {
          "row_count": 1
        },
        "statement_id": "9d8836fc1bdb4729a27fcc07614b52c4",
        "thoughts": [
          {
            "content": "The user wants to know which region had the highest sales last month. The query aggregates revenue from the sales table, grouped by region.",
            "thought_type": "THOUGHT_TYPE_DESCRIPTION"
          },
          {
            "content": "- Definition of 'top sales': Interpreted as the region with the highest total revenue for the month of June 2024.",
            "thought_type": "THOUGHT_TYPE_UNDERSTANDING"
          },
          {
            "content": "- catalog.schema.sales_2024\n- catalog.schema.regions",
            "thought_type": "THOUGHT_TYPE_DATA_SOURCING"
          },
          {
            "content": "- Filter the sales table to June 2024.\n- Join with the regions table on region_id.\n- Aggregate revenue and deal count by region.\n- Order by total revenue descending and return the top result.",
            "thought_type": "THOUGHT_TYPE_STEPS"
          },
          {
            "content": "- The Genie space is configured to always include deal count alongside revenue in sales queries.",
            "thought_type": "THOUGHT_TYPE_INSTRUCTIONS"
          }
        ],
        "title": "Top sales last month"
      }
    },
    {
      "attachment_id": "d5e6f708901234567890123456abcdef",
      "suggested_questions": {
        "questions": [
          "Can you filter to last quarter?",
          "Show top 5 by revenue",
          "What is the month-over-month trend?"
        ]
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "COMPLETED",
  "user_id": 12345
}

{
  "attachments": [
    {
      "attachment_id": "01f0838b7adc123e86447829f57b9572",
      "query": {
        "description": "Retrieves the top sales region for last month by joining sales and regions tables, aggregating revenue and deal count, and returning the highest-revenue region",
        "last_updated_timestamp": 1719769718,
        "query": "SELECT r.region_name, SUM(s.revenue) AS total_revenue, COUNT(s.deal_id) AS deal_count FROM catalog.schema.sales_2024 s JOIN catalog.schema.regions r ON s.region_id = r.region_id WHERE s.sale_date BETWEEN '2024-06-01' AND '2024-06-30' GROUP BY r.region_name ORDER BY total_revenue DESC LIMIT 1",
        "query_result_metadata": {
          "row_count": 1
        },
        "statement_id": "9d8836fc1bdb4729a27fcc07614b52c4",
        "thoughts": [
          {
            "content": "The user is asking about top sales performance for the previous month. The result shows the region, total revenue, and deal count, ordered by revenue descending and limited to the top result.",
            "thought_type": "THOUGHT_TYPE_DESCRIPTION"
          },
          {
            "content": "- Definition of 'top sales': The query assumes 'top sales' means the region with the highest total revenue. Alternative interpretations could consider deal count or average deal size.",
            "thought_type": "THOUGHT_TYPE_UNDERSTANDING"
          },
          {
            "content": "- catalog.schema.sales_2024\n- catalog.schema.regions",
            "thought_type": "THOUGHT_TYPE_DATA_SOURCING"
          },
          {
            "content": "- Filter the sales table to last month's date range.\n- Join with the regions table to get region names.\n- Aggregate revenue and deal count by region.\n- Order by total revenue descending.\n- Limit to the top result.",
            "thought_type": "THOUGHT_TYPE_STEPS"
          }
        ],
        "title": "Top sales by region last month"
      }
    },
    {
      "attachment_id": "a2b3c4d5e6f7089012345678abcdef90",
      "suggested_questions": {
        "questions": [
          "Can you filter to last quarter?",
          "Show top 5 by revenue",
          "What is the month-over-month trend?"
        ]
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "EXECUTING_QUERY",
  "user_id": 12345
}

{
  "attachments": [
    {
      "text": {
        "content": "Based on the data, your top sales last month were from the West region, totaling $1.2M in revenue across 340 deals."
      }
    }
  ],
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": null,
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "COMPLETED",
  "user_id": 12345
}

{
  "attachments": null,
  "content": "Give me top sales for last month",
  "conversation_id": "6a64adad2e664ee58de08488f986af3e",
  "created_timestamp": 1719769718,
  "error": {
    "error": "Human readable error message",
    "type": "TABLES_MISSING_EXCEPTION"
  },
  "last_updated_timestamp": 1719769718,
  "message_id": "e1ef34712a29169db030324fd0e1df5f",
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "status": "EXECUTING_QUERY",
  "user_id": 12345
}

Get full query-result download status GA

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/downloads/{download_id}

After Generating a Full Query Result Download and successfully receiving a download_id and download_id_signature, use this API to poll the download progress. Both download_id and download_id_signature are required to call this endpoint. When the download is complete, the API returns the result in the EXTERNAL_LINKS disposition, containing one or more external links to the query result files.

Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.

See Execute Statement for more details.

API scopes: genie

AWS

On AWS, the external link is a presigned URL for Amazon S3.

Azure

On Azure, the external link is a SAS URL for Azure Storage.

GCP

On GCP, the external link is a signed URL for Google Cloud Storage.

Parameters

space_idstringuuidRequiredpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringuuidRequiredpath: Attachment ID
Example: e1ef34712a29169db030324fd0e1df5f

download_idstringuuidRequiredpath: Download ID. This ID is provided by the Generate Download endpoint
Example: 01eda0e7-e315-1846-84e2-79a963ffad44

download_id_signaturestringRequiredquery: JWT signature for the download_id to ensure secure access to query results

Response

statement_responseobject

SQL Statement Execution response. See Get status, manifest, and result first chunk for more details.

Show child attributesHide child attributes

statement_idstring: The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls.

statusobject

Show child attributesHide child attributes

statestring

Statement execution state:

PENDING: waiting for warehouse
RUNNING: running
SUCCEEDED: execution was successful, result data available for fetch
FAILED: execution failed; reason for failure described in accompanying error message
CANCELED: user canceled; can come from explicit cancel call, or timeout with on_wait_timeout=CANCEL
CLOSED: execution successful, and statement closed; result no longer available for fetch

Values:

STATE_UNSPECIFIED
PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
CLOSED

errorobject

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

sql_statestring: SQLSTATE error code returned when the statement execution fails. Only populated when the statement status is FAILED.

manifestobject

Show child attributesHide child attributes

formatstring

Values:

FORMAT_UNSPECIFIED
JSON_ARRAY
ARROW_STREAM
CSV

schemaobject

Show child attributesHide child attributes

column_countint32

columnsarray of object

total_chunk_countint32: The total number of chunks that the result set has been divided into.

chunksarray of object

Array of result set chunk metadata.

Show child attributesHide child attributes

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

total_row_countint64: The total number of rows in the result set.

total_byte_countint64: The total number of bytes in the result set. This field is not available when using INLINE disposition.

truncatedboolean: Indicates whether the result is truncated due to row_limit or byte_limit.

resultobject

Show child attributesHide child attributes

external_linksarray of object

Show child attributesHide child attributes

external_linkstring: A short-lived cloud-storage URL pointing to a chunk of result data, hosted by an external service, with a short expiration time (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive and the client should not expose this URL in a log.
AWS
On AWS, this is a presigned URL.
Azure
On Azure, this is a SAS URL.
GCP
On GCP, this is a signed URL.

expirationstringdate-time: Indicates the date-time that the given external link will expire and becomes invalid, after which point a new external_link must be requested.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

data_arrayarray of object

The JSON_ARRAY format is an array of arrays of values, where each non-null value is formatted as a string. Null values are encoded as JSON null.

Show child attributesHide child attributes

valuesarray of object: Repeated field of dynamically typed values.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

Get an attachment SQL result GA

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result

Get the result of SQL query if the message has a query attachment. This is only available if a message has a query attachment and the message status is EXECUTING_QUERY OR COMPLETED.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringuuidRequiredpath: Attachment ID
Example: e1ef34712a29169db030324fd0e1df5f

Response

statement_responseobject

SQL Statement Execution response. See Get status, manifest, and result first chunk for more details.

Show child attributesHide child attributes

statement_idstring: The statement ID is returned upon successfully submitting a SQL statement, and is a required reference for all subsequent calls.

statusobject

Show child attributesHide child attributes

statestring

Statement execution state:

PENDING: waiting for warehouse
RUNNING: running
SUCCEEDED: execution was successful, result data available for fetch
FAILED: execution failed; reason for failure described in accompanying error message
CANCELED: user canceled; can come from explicit cancel call, or timeout with on_wait_timeout=CANCEL
CLOSED: execution successful, and statement closed; result no longer available for fetch

Values:

STATE_UNSPECIFIED
PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
CLOSED

errorobject

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

sql_statestring: SQLSTATE error code returned when the statement execution fails. Only populated when the statement status is FAILED.

manifestobject

Show child attributesHide child attributes

formatstring

Values:

FORMAT_UNSPECIFIED
JSON_ARRAY
ARROW_STREAM
CSV

schemaobject

Show child attributesHide child attributes

column_countint32

columnsarray of object

total_chunk_countint32: The total number of chunks that the result set has been divided into.

chunksarray of object

Array of result set chunk metadata.

Show child attributesHide child attributes

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

total_row_countint64: The total number of rows in the result set.

total_byte_countint64: The total number of bytes in the result set. This field is not available when using INLINE disposition.

truncatedboolean: Indicates whether the result is truncated due to row_limit or byte_limit.

resultobject

Show child attributesHide child attributes

external_linksarray of object

Show child attributesHide child attributes

external_linkstring: A short-lived cloud-storage URL pointing to a chunk of result data, hosted by an external service, with a short expiration time (<= 15 minutes). As this URL contains a temporary credential, it should be considered sensitive and the client should not expose this URL in a log.
AWS
On AWS, this is a presigned URL.
Azure
On Azure, this is a SAS URL.
GCP
On GCP, this is a signed URL.

expirationstringdate-time: Indicates the date-time that the given external link will expire and becomes invalid, after which point a new external_link must be requested.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

data_arrayarray of object

The JSON_ARRAY format is an array of arrays of values, where each non-null value is formatted as a string. Null values are encoded as JSON null.

Show child attributesHide child attributes

valuesarray of object: Repeated field of dynamically typed values.

chunk_indexint32: The position within the sequence of result set chunks.

row_offsetint64: The starting row offset within the result set.

row_countint64: The number of rows within the result chunk.

byte_countint64: The number of bytes in the result chunk. This field is not available when using INLINE disposition.

next_chunk_indexint32: When fetching, provides the chunk_index for the next chunk. If absent, indicates there are no more chunks. The next chunk can be fetched with a statementexecution/getstatementresultchunkn request.

next_chunk_internal_linkstring: When fetching, provides a link to fetch the next chunk. If absent, indicates there are no more chunks. This link is an absolute path to be joined with your $DATABRICKS_HOST, and should be treated as an opaque link. This is an alternative to using next_chunk_index.

List all comments in a conversation Public Preview

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/list-comments

List all comments across all messages in a conversation.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

page_sizeint32<= 100query: Maximum number of comments to return per page.
Default: 20

page_tokenstringquery: Pagination token for getting the next page of results.

Response

commentsarray of object

List of comments in the conversation.

Show child attributesHide child attributes

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstringuuidRequired: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the comment

contentstring<= 5000 charactersRequired: Comment text content
Example: This query result looks correct.

created_timestampint64Output only: Timestamp when the comment was created

next_page_tokenstring: Token to get the next page of results.

View as Markdown

Response

{
  "comments": [
    {
      "space_id": "e1ef34712a29169db030324fd0e1df5f",
      "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
      "message_id": "e1ef34712a29169db030324fd0e1df5f",
      "message_comment_id": "e1ef34712a29169db030324fd0e1df5f",
      "user_id": 0,
      "content": "This query result looks correct.",
      "created_timestamp": 0
    }
  ],
  "next_page_token": "string"
}

List conversation messages GA

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages

Lists messages in a chat-mode or agent-mode conversation. Agent-mode messages are returned as GenieMessage projections. Use the List conversation items endpoint for the complete reasoning and tool-call history.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the conversation is located
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID of the conversation to list messages from
Example: e1ef34712a29169db030324fd0e1df5f

page_sizeint32<= 100query: Maximum number of messages to return per page
Default: 20

page_tokenstringquery: Token to get the next page of results

Response

messagesarray of object

List of messages in the conversation.

Show child attributesHide child attributes

idstringuuidDeprecatedOutput only: Message ID. Legacy identifier, use message_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the message

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

statusstringOutput only

MessageStatus. The possible values are:

FETCHING_METADATA: Fetching metadata from the data sources.
FILTERING_CONTEXT: Running smart context step to determine relevant context.
ASKING_AI: Waiting for the LLM to respond to the user's question.
PENDING_WAREHOUSE: Waiting for warehouse before the SQL query can start executing.
EXECUTING_QUERY: Executing a generated SQL query. Get the SQL query result by calling getMessageAttachmentQueryResult API.
FAILED: The response generation or query execution failed. See error field.
COMPLETED: Message processing is completed. Results are in the attachments field. Get the SQL query result by calling getMessageAttachmentQueryResult API.
SUBMITTED: Message has been submitted.
QUERY_RESULT_EXPIRED: SQL result is not available anymore. The user needs to rerun the query. Rerun the SQL query result by calling executeMessageAttachmentQuery API.
CANCELLED: Message has been cancelled.

Values:

FETCHING_METADATA
FILTERING_CONTEXT
ASKING_AI
PENDING_WAREHOUSE
EXECUTING_QUERY
FAILED
COMPLETED
SUBMITTED
QUERY_RESULT_EXPIRED
CANCELLED

Example: ASKING_AI

contentstringRequired: User message content
Example: Biggest open opportunities

attachmentsarray of objectOutput only

AI-generated response to the message

Show child attributesHide child attributes

textobjectOutput only

Text Attachment if Genie responds with text This also contains the final summary when available.

Show child attributesHide child attributes

contentstring: AI generated message

idstring

purposestring

Values:

TEXT_ATTACHMENT_PURPOSE_UNSPECIFIED
FOLLOW_UP_QUESTION
TEXT_ATTACHMENT_PURPOSE_ANSWER

queryobjectOutput only

Query Attachment if Genie responds with a SQL query

Show child attributesHide child attributes

titlestring: Name of the query

querystring: AI generated SQL query

descriptionstring: Description of the query

last_updated_timestampint64Output only: Time when the user updated the query last

parametersarray of object

idstringDeprecatedOutput only

statement_idstringOutput only: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

query_result_metadataobjectOutput only: Metadata associated with the query result.

thoughtsarray of objectPublic PreviewOutput only: Insights into how Genie came to generate the SQL.

suggested_questionsobjectOutput only

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of stringOutput only: The suggested follow-up questions

vizobjectOutput only

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringOutput only: Name of the visualization

query_attachment_idstringOutput only: The ID of the query attachment the visualization was generated from

attachment_idstringOutput only: Attachment ID

query_resultobjectDeprecatedOutput only

The result of SQL query if the message includes a query attachment. Deprecated. Use query_result_metadata in GenieQueryAttachment instead.

Show child attributesHide child attributes

statement_idstring: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

row_countint64: Row count of the result

is_truncatedboolean: If result is truncated

statement_id_signaturestring: JWT corresponding to the statement contained in this result

errorobjectOutput only

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring

Values:

Show 62 possible values

TYPE_UNSPECIFIED
UNEXPECTED_REPLY_PROCESS_EXCEPTION
GENERIC_CHAT_COMPLETION_EXCEPTION
CONTEXT_EXCEEDED_EXCEPTION
DEPLOYMENT_NOT_FOUND_EXCEPTION
FUNCTIONS_NOT_AVAILABLE_EXCEPTION
INVALID_COMPLETION_REQUEST_EXCEPTION
CONTENT_FILTER_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION
RETRYABLE_PROCESSING_EXCEPTION
INVALID_FUNCTION_CALL_EXCEPTION
LOCAL_CONTEXT_EXCEEDED_EXCEPTION
CHAT_COMPLETION_NETWORK_EXCEPTION
INVALID_CHAT_COMPLETION_JSON_EXCEPTION
GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION
WAREHOUSE_ACCESS_MISSING_EXCEPTION
WAREHOUSE_NOT_FOUND_EXCEPTION
NO_TABLES_TO_QUERY_EXCEPTION
SQL_EXECUTION_EXCEPTION
REPLY_PROCESS_TIMEOUT_EXCEPTION
COULD_NOT_GET_UC_SCHEMA_EXCEPTION
INVALID_TABLE_IDENTIFIER_EXCEPTION
TOO_MANY_TABLES_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_EXCEPTION
GENERIC_SQL_EXEC_API_CALL_EXCEPTION
CHAT_COMPLETION_CLIENT_EXCEPTION
CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION
UNKNOWN_AI_MODEL
TABLES_MISSING_EXCEPTION
MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION
MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION
BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION
INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION
TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION
RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION
RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION
FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION
INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION
ILLEGAL_PARAMETER_DEFINITION_EXCEPTION
NO_QUERY_TO_VISUALIZE_EXCEPTION
NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE
STOP_PROCESS_DUE_TO_AUTO_REGENERATE
FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION
MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION
COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION
GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION
MISSING_SQL_QUERY_EXCEPTION
DESCRIBE_QUERY_UNEXPECTED_FAILURE
DESCRIBE_QUERY_TIMEOUT
DESCRIBE_QUERY_INVALID_SQL_ERROR
INVALID_SQL_UNKNOWN_TABLE_EXCEPTION
INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION
INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION
MESSAGE_ATTACHMENT_TOO_LONG_ERROR
INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION
INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION
EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION
UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION
COULD_NOT_GET_DASHBOARD_SCHEMA_EXCEPTION

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobjectOutput only

User feedback for the message if provided

Show child attributesHide child attributes

ratingstring

The feedback rating

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstringPublic Preview: Optional feedback comment text

next_page_tokenstring: The token to use for retrieving the next page of results.

View as Markdown

Response

{
  "messages": [
    {
      "id": "e1ef34712a29169db030324fd0e1df5f",
      "space_id": "e1ef34712a29169db030324fd0e1df5f",
      "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
      "user_id": 0,
      "created_timestamp": 0,
      "last_updated_timestamp": 0,
      "status": "ASKING_AI",
      "content": "Biggest open opportunities",
      "attachments": [
        {}
      ],
      "query_result": {},
      "error": {},
      "message_id": "e1ef34712a29169db030324fd0e1df5f",
      "feedback": {}
    }
  ],
  "next_page_token": "string"
}

List comments on a message Public Preview

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments

List comments on a specific conversation message.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: The ID associated with the message.
Example: e1ef34712a29169db030324fd0e1df5f

page_sizeint32<= 100query: Maximum number of comments to return per page.
Default: 20

page_tokenstringquery: Pagination token for getting the next page of results.

Response

commentsarray of object

List of comments on the message.

Show child attributesHide child attributes

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstringuuidRequired: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the comment

contentstring<= 5000 charactersRequired: Comment text content
Example: This query result looks correct.

created_timestampint64Output only: Timestamp when the comment was created

next_page_tokenstring: Token to get the next page of results.

View as Markdown

Response

{
  "comments": [
    {
      "space_id": "e1ef34712a29169db030324fd0e1df5f",
      "conversation_id": "e1ef34712a29169db030324fd0e1df5f",
      "message_id": "e1ef34712a29169db030324fd0e1df5f",
      "message_comment_id": "e1ef34712a29169db030324fd0e1df5f",
      "user_id": 0,
      "content": "This query result looks correct.",
      "created_timestamp": 0
    }
  ],
  "next_page_token": "string"
}

Send feedback on a message GA

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/feedback

Sends feedback for a message in a chat-mode or agent-mode conversation.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where the message is located.
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequiredpath: The ID associated with the conversation.
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringuuidRequiredpath: The ID associated with the message to provide feedback for.
Example: e1ef34712a29169db030324fd0e1df5f

Request body

ratingstringRequired

The rating (POSITIVE, NEGATIVE, or NONE).

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstring<= 5000 charactersPublic Preview: Optional text feedback that will be stored as a comment.

Chat mode: Start a conversation GA

POST /api/2.0/genie/spaces/{space_id}/start-conversation

Starts a new chat-mode conversation and sends its first message.

API scopes: genie

Parameters

space_idstringuuidRequiredpath: The ID associated with the Genie space where you want to start a conversation.
Example: e1ef34712a29169db030324fd0e1df5f

Request body

contentstringRequired: The text of the message that starts the conversation.
Example: Biggest open opportunities

enable_visualizationboolean: Enable visualization generation.
Example: true

Response

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

messageobject

Show child attributesHide child attributes

idstringuuidDeprecatedOutput only: Message ID. Legacy identifier, use message_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64Output only: ID of the user who created the message

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

statusstringOutput only

MessageStatus. The possible values are:

FETCHING_METADATA: Fetching metadata from the data sources.
FILTERING_CONTEXT: Running smart context step to determine relevant context.
ASKING_AI: Waiting for the LLM to respond to the user's question.
PENDING_WAREHOUSE: Waiting for warehouse before the SQL query can start executing.
EXECUTING_QUERY: Executing a generated SQL query. Get the SQL query result by calling getMessageAttachmentQueryResult API.
FAILED: The response generation or query execution failed. See error field.
COMPLETED: Message processing is completed. Results are in the attachments field. Get the SQL query result by calling getMessageAttachmentQueryResult API.
SUBMITTED: Message has been submitted.
QUERY_RESULT_EXPIRED: SQL result is not available anymore. The user needs to rerun the query. Rerun the SQL query result by calling executeMessageAttachmentQuery API.
CANCELLED: Message has been cancelled.

Values:

FETCHING_METADATA
FILTERING_CONTEXT
ASKING_AI
PENDING_WAREHOUSE
EXECUTING_QUERY
FAILED
COMPLETED
SUBMITTED
QUERY_RESULT_EXPIRED
CANCELLED

Example: ASKING_AI

contentstringRequired: User message content
Example: Biggest open opportunities

attachmentsarray of objectOutput only

AI-generated response to the message

Show child attributesHide child attributes

textobjectOutput only

Text Attachment if Genie responds with text This also contains the final summary when available.

Show child attributesHide child attributes

contentstring: AI generated message

idstring

purposestring

Values:

TEXT_ATTACHMENT_PURPOSE_UNSPECIFIED
FOLLOW_UP_QUESTION
TEXT_ATTACHMENT_PURPOSE_ANSWER

queryobjectOutput only

Query Attachment if Genie responds with a SQL query

Show child attributesHide child attributes

titlestring: Name of the query

querystring: AI generated SQL query

descriptionstring: Description of the query

last_updated_timestampint64Output only: Time when the user updated the query last

parametersarray of object

idstringDeprecatedOutput only

statement_idstringOutput only: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

query_result_metadataobjectOutput only: Metadata associated with the query result.

thoughtsarray of objectPublic PreviewOutput only: Insights into how Genie came to generate the SQL.

suggested_questionsobjectOutput only

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of stringOutput only: The suggested follow-up questions

vizobjectOutput only

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringOutput only: Name of the visualization

query_attachment_idstringOutput only: The ID of the query attachment the visualization was generated from

attachment_idstringOutput only: Attachment ID

query_resultobjectDeprecatedOutput only

The result of SQL query if the message includes a query attachment. Deprecated. Use query_result_metadata in GenieQueryAttachment instead.

Show child attributesHide child attributes

statement_idstring: Statement Execution API statement id. Use Get status, manifest, and result first chunk to get the full result data.

row_countint64: Row count of the result

is_truncatedboolean: If result is truncated

statement_id_signaturestring: JWT corresponding to the statement contained in this result

errorobjectOutput only

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring

Values:

Show 62 possible values

TYPE_UNSPECIFIED
UNEXPECTED_REPLY_PROCESS_EXCEPTION
GENERIC_CHAT_COMPLETION_EXCEPTION
CONTEXT_EXCEEDED_EXCEPTION
DEPLOYMENT_NOT_FOUND_EXCEPTION
FUNCTIONS_NOT_AVAILABLE_EXCEPTION
INVALID_COMPLETION_REQUEST_EXCEPTION
CONTENT_FILTER_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_JSON_EXCEPTION
RETRYABLE_PROCESSING_EXCEPTION
INVALID_FUNCTION_CALL_EXCEPTION
LOCAL_CONTEXT_EXCEEDED_EXCEPTION
CHAT_COMPLETION_NETWORK_EXCEPTION
INVALID_CHAT_COMPLETION_JSON_EXCEPTION
GENERIC_CHAT_COMPLETION_SERVICE_EXCEPTION
WAREHOUSE_ACCESS_MISSING_EXCEPTION
WAREHOUSE_NOT_FOUND_EXCEPTION
NO_TABLES_TO_QUERY_EXCEPTION
SQL_EXECUTION_EXCEPTION
REPLY_PROCESS_TIMEOUT_EXCEPTION
COULD_NOT_GET_UC_SCHEMA_EXCEPTION
INVALID_TABLE_IDENTIFIER_EXCEPTION
TOO_MANY_TABLES_EXCEPTION
FUNCTION_ARGUMENTS_INVALID_EXCEPTION
GENERIC_SQL_EXEC_API_CALL_EXCEPTION
CHAT_COMPLETION_CLIENT_EXCEPTION
CHAT_COMPLETION_CLIENT_TIMEOUT_EXCEPTION
UNKNOWN_AI_MODEL
TABLES_MISSING_EXCEPTION
MESSAGE_DELETED_WHILE_EXECUTING_EXCEPTION
MESSAGE_UPDATED_WHILE_EXECUTING_EXCEPTION
BLOCK_MULTIPLE_EXECUTIONS_EXCEPTION
INVALID_CERTIFIED_ANSWER_IDENTIFIER_EXCEPTION
TOO_MANY_CERTIFIED_ANSWERS_EXCEPTION
RATE_LIMIT_EXCEEDED_GENERIC_EXCEPTION
RATE_LIMIT_EXCEEDED_SPECIFIED_WAIT_EXCEPTION
FUNCTION_CALL_MISSING_PARAMETER_EXCEPTION
INVALID_CERTIFIED_ANSWER_FUNCTION_EXCEPTION
ILLEGAL_PARAMETER_DEFINITION_EXCEPTION
NO_QUERY_TO_VISUALIZE_EXCEPTION
NO_DEPLOYMENTS_AVAILABLE_TO_WORKSPACE
STOP_PROCESS_DUE_TO_AUTO_REGENERATE
FUNCTION_ARGUMENTS_INVALID_TYPE_EXCEPTION
MESSAGE_CANCELLED_WHILE_EXECUTING_EXCEPTION
COULD_NOT_GET_MODEL_DEPLOYMENTS_EXCEPTION
GENERATED_SQL_QUERY_TOO_LONG_EXCEPTION
MISSING_SQL_QUERY_EXCEPTION
DESCRIBE_QUERY_UNEXPECTED_FAILURE
DESCRIBE_QUERY_TIMEOUT
DESCRIBE_QUERY_INVALID_SQL_ERROR
INVALID_SQL_UNKNOWN_TABLE_EXCEPTION
INVALID_SQL_MULTIPLE_STATEMENTS_EXCEPTION
INVALID_SQL_MULTIPLE_DATASET_REFERENCES_EXCEPTION
MESSAGE_ATTACHMENT_TOO_LONG_ERROR
INTERNAL_CATALOG_PATH_OVERLAP_EXCEPTION
INTERNAL_CATALOG_MISSING_UC_PATH_EXCEPTION
EXCEEDED_MAX_TOKEN_LENGTH_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_ONGOING_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_FAILED_EXCEPTION
INTERNAL_CATALOG_ASSET_CREATION_UNSUPPORTED_EXCEPTION
UNSUPPORTED_CONVERSATION_TYPE_EXCEPTION
COULD_NOT_GET_DASHBOARD_SCHEMA_EXCEPTION

message_idstringuuidRequired: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobjectOutput only

User feedback for the message if provided

Show child attributesHide child attributes

ratingstring

The feedback rating

Values:

GENIE_FEEDBACK_RATING_UNSPECIFIED
POSITIVE
NEGATIVE
NONE

commentstringPublic Preview: Optional feedback comment text

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

conversationobject

Show child attributesHide child attributes

idstringuuidDeprecatedOutput only: Conversation ID. Legacy identifier, use conversation_id instead
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringuuidRequired: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64uuidOutput only: ID of the user who created the conversation
Example: e1ef34712a29169db030324fd0e1df5f

created_timestampint64Output only: Timestamp when the message was created

last_updated_timestampint64Output only: Timestamp when the message was last updated

titlestringRequired: Conversation title

conversation_idstringuuidRequired: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

View as Markdown

Request

{
  "content": "Give me top sales for last month"
}

Response

New conversation

{
  "conversation": {
    "created_timestamp": 1719769718,
    "id": "6a64adad2e664ee58de08488f986af3e",
    "last_updated_timestamp": 1719769718,
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "title": "Give me top sales for last month",
    "user_id": 12345
  },
  "message": {
    "attachments": null,
    "content": "Give me top sales for last month",
    "conversation_id": "6a64adad2e664ee58de08488f986af3e",
    "created_timestamp": 1719769718,
    "error": null,
    "last_updated_timestamp": 1719769718,
    "message_id": "e1ef34712a29169db030324fd0e1df5f",
    "space_id": "3c409c00b54a44c79f79da06b82460e2",
    "status": "IN_PROGRESS",
    "user_id": 12345
  }
}

GenieConversation object​

List conversations GA​

Parameters​

Response​

Delete a conversation GA​

Parameters​

Chat mode: Send a message GA​

Parameters​

Request body​

Response​

Add a comment to a message Public Preview​

Parameters​

Request body​

Response​

Agent mode: Cancel a response GA​

Parameters​

Response​

Delete a conversation message GA​

Parameters​

Execute an attachment SQL query GA​

Parameters​

Response​

Start a full query-result download GA​

Warning: Databricks strongly recommends that you protect the URLs that are returned by the EXTERNAL_LINKS disposition.​

Parameters​

Response​

Get a conversation message GA​

Parameters​

Response​

Get full query-result download status GA​

Warning: Databricks strongly recommends that you protect the URLs that are returned by the EXTERNAL_LINKS disposition.​

Parameters​

Response​

Get an attachment SQL result GA​

Parameters​

Response​

List all comments in a conversation Public Preview​

Parameters​

Response​

List conversation messages GA​

Parameters​

Response​

List comments on a message Public Preview​

Parameters​

Response​

Send feedback on a message GA​

Parameters​

Request body​

Chat mode: Start a conversation GA​

Parameters​

Request body​

Response​

GenieConversation object

List conversations GA

Parameters

Response

Delete a conversation GA

Parameters

Chat mode: Send a message GA

Parameters

Request body

Response

Add a comment to a message Public Preview

Parameters

Request body

Response

Agent mode: Cancel a response GA

Parameters

Response

Delete a conversation message GA

Parameters

Execute an attachment SQL query GA

Parameters

Response

Start a full query-result download GA

Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.

Parameters

Response

Get a conversation message GA

Parameters

Response

Get full query-result download status GA

Warning: Databricks strongly recommends that you protect the URLs that are returned by the `EXTERNAL_LINKS` disposition.

Parameters

Response

Get an attachment SQL result GA

Parameters

Response

List all comments in a conversation Public Preview

Parameters

Response

List conversation messages GA

Parameters

Response

List comments on a message Public Preview

Parameters

Response

Send feedback on a message GA

Parameters

Request body

Chat mode: Start a conversation GA

Parameters

Request body

Response