Conversation

View as Markdown

GenieConversation object

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the conversation
Example: e1ef34712a29169db030324fd0e1df5f

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

titlestring: Conversation title

conversation_idstring: 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 GA

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

Get a list of conversations in a Genie Space.

API scopes: genie

Parameters

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

page_sizeint32query: Maximum number of conversations to return per page
Default: 20
Constraints: <= 100

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_idstring: Example: e1ef34712a29169db030324fd0e1df5f

titlestring: Example: Biggest open opportunities

created_timestampint64

agent_typestringBeta: 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": "string"
    }
  ],
  "next_page_token": "string"
}

Delete GA

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

Delete a conversation.

API scopes: genie

Parameters

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

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

Genie Create Conversation Message GA

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

Create new message in a conversation. The AI response uses all previously created messages in the conversation to respond.

API scopes: genie

Parameters

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

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

Request body

contentstring: User message content.
Example: Biggest open opportunities

enable_visualizationbooleanBeta: Enable visualization generation.
Example: true

Response

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the message

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

statusstring: Values: FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, FAILED, COMPLETED, SUBMITTED, QUERY_RESULT_EXPIRED, CANCELLED
Example: ASKING_AI

contentstring: User message content
Example: Biggest open opportunities

attachmentsarray of object

AI-generated response to the message

Show child attributesHide child attributes

textobjectRequired

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

queryobjectRequired

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_timestampint64: Time when the user updated the query last

parametersarray of object

Show child attributesHide child attributes

keywordstring

valuestring

sql_typestring

idstring

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

query_result_metadataobject

Metadata associated with the query result.

Show child attributesHide child attributes

row_countint64: The number of rows in the result set.

is_truncatedboolean: Indicates whether the result set is truncated.

thoughtsarray of objectPublic Preview

Insights into how Genie came to generate the SQL.

Show child attributesHide child attributes

thought_typestringPublic Preview

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 Preview: The md formatted content for this thought.

suggested_questionsobjectRequired

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of string: The suggested follow-up questions

vizobjectRequiredBeta

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringBeta: Name of the visualization

query_attachment_idstringBeta: The ID of the query attachment the visualization was generated from

attachment_idstring: Attachment ID

query_resultobject

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

errorobject

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring: 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_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobject

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
}

Genie Create Message Comment 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_idstringpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

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

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

Request body

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

Response

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstring: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the comment

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

created_timestampint64: 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
}

Genie Delete 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_idstringpath: The ID associated with the Genie space where the message is located.
Example: e1ef34712a29169db030324fd0e1df5f

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

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

Genie Execute Message Attachment 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

message_idstringpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringpath: 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: 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 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
A presigned 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.
Azure
A SAS 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.
GCP
A signed 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.

expirationstring: 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.

Genie Generate Download Full Query Result 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, URL is generated, which can be used to download the results directly from . As a short-lived is embedded in this URL, you should protect the URL.

Because URLs are already generated with embedded temporary s, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

API scopes: genie

AWS

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, presigned URL is generated, which can be used to download the results directly from Amazon S3. As a short-lived access credential is embedded in this presigned URL, you should protect the URL.

Because presigned URLs are already generated with embedded temporary access credentials, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

Azure

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, SAS URL is generated, which can be used to download the results directly from Azure storage. As a short-lived SAS token is embedded in this SAS URL, you should protect the URL.

Because SAS URLs are already generated with embedded temporary SAS tokens, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

GCP

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, signed URL is generated, which can be used to download the results directly from Google Cloud Storage. As a short-lived access credential is embedded in this signed URL, you should protect the URL.

Because signed URLs are already generated with embedded temporary access credentials, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

Parameters

space_idstringpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringpath: 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

Genie Get Conversation Message GA

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

Get message from conversation.

API scopes: genie

Parameters

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

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

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

Response

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the message

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

statusstring: Values: FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, FAILED, COMPLETED, SUBMITTED, QUERY_RESULT_EXPIRED, CANCELLED
Example: ASKING_AI

contentstring: User message content
Example: Biggest open opportunities

attachmentsarray of object

AI-generated response to the message

Show child attributesHide child attributes

textobjectRequired

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

queryobjectRequired

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_timestampint64: Time when the user updated the query last

parametersarray of object

Show child attributesHide child attributes

keywordstring

valuestring

sql_typestring

idstring

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

query_result_metadataobject

Metadata associated with the query result.

Show child attributesHide child attributes

row_countint64: The number of rows in the result set.

is_truncatedboolean: Indicates whether the result set is truncated.

thoughtsarray of objectPublic Preview

Insights into how Genie came to generate the SQL.

Show child attributesHide child attributes

thought_typestringPublic Preview

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 Preview: The md formatted content for this thought.

suggested_questionsobjectRequired

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of string: The suggested follow-up questions

vizobjectRequiredBeta

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringBeta: Name of the visualization

query_attachment_idstringBeta: The ID of the query attachment the visualization was generated from

attachment_idstring: Attachment ID

query_resultobject

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

errorobject

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring: 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_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobject

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
}

Genie Get Download Full Query Result 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.

Because URLs are already generated with embedded temporary s, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

API scopes: genie

AWS

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

Because presigned URLs are already generated with embedded temporary access credentials, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

Azure

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

Because SAS URLs are already generated with embedded temporary SAS tokens, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

GCP

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

Because signed URLs are already generated with embedded temporary access credentials, you must not set an Authorization header in the download requests.

See Execute Statement for more details.

Parameters

space_idstringpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstringpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringpath: Attachment ID
Example: e1ef34712a29169db030324fd0e1df5f

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

download_id_signaturestringquery: 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: 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 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
A presigned 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.
Azure
A SAS 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.
GCP
A signed 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.

expirationstring: 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.

Genie Get Message Attachment Query 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

message_idstringpath: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

space_idstringpath: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstringpath: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

attachment_idstringpath: 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: 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 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
A presigned 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.
Azure
A SAS 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.
GCP
A signed 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.

expirationstring: 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.

Genie List Conversation Comments 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_idstringpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

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

page_sizeint32query: Maximum number of comments to return per page.
Default: 20
Constraints: <= 100

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_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstring: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the comment

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

created_timestampint64: 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"
}

Genie List Conversation Messages GA

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

List messages in a conversation

API scopes: genie

Parameters

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

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

page_sizeint32query: Maximum number of messages to return per page
Default: 20
Constraints: <= 100

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

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the message

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

statusstring: Values: FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, FAILED, COMPLETED, SUBMITTED, QUERY_RESULT_EXPIRED, CANCELLED
Example: ASKING_AI

contentstring: User message content
Example: Biggest open opportunities

attachmentsarray of object

AI-generated response to the message

Show child attributesHide child attributes

textobjectRequired

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

queryobjectRequired

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_timestampint64: Time when the user updated the query last

parametersarray of object

idstring

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

query_result_metadataobject: Metadata associated with the query result.

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

suggested_questionsobjectRequired

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of string: The suggested follow-up questions

vizobjectRequiredBeta

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringBeta: Name of the visualization

query_attachment_idstringBeta: The ID of the query attachment the visualization was generated from

attachment_idstring: Attachment ID

query_resultobject

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

errorobject

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring: 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_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobject

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"
}

Genie List Message Comments 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_idstringpath: The ID associated with the Genie space.
Example: e1ef34712a29169db030324fd0e1df5f

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

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

page_sizeint32query: Maximum number of comments to return per page.
Default: 20
Constraints: <= 100

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_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

message_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

message_comment_idstring: Comment ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the comment

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

created_timestampint64: 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"
}

Genie Send Message Feedback GA

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

Send feedback for a message.

API scopes: genie

Parameters

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

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

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

Request body

ratingstring: The rating (POSITIVE, NEGATIVE, or NONE).
Values: GENIE_FEEDBACK_RATING_UNSPECIFIED, POSITIVE, NEGATIVE, NONE

commentstringPublic Preview: Optional text feedback that will be stored as a comment.
Constraints: <= 5000 characters

Genie Start Conversation GA

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

Start a new conversation.

API scopes: genie

Parameters

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

Request body

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

enable_visualizationbooleanBeta: Enable visualization generation.
Example: true

Response

message_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

messageobject

Show child attributesHide child attributes

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

conversation_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the message

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

statusstring: Values: FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, FAILED, COMPLETED, SUBMITTED, QUERY_RESULT_EXPIRED, CANCELLED
Example: ASKING_AI

contentstring: User message content
Example: Biggest open opportunities

attachmentsarray of object

AI-generated response to the message

Show child attributesHide child attributes

textobjectRequired

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

queryobjectRequired

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_timestampint64: Time when the user updated the query last

parametersarray of object

idstring

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

query_result_metadataobject: Metadata associated with the query result.

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

suggested_questionsobjectRequired

Follow-up questions suggested by Genie

Show child attributesHide child attributes

questionsarray of string: The suggested follow-up questions

vizobjectRequiredBeta

Visualization generated by Genie, if requested via enable_visualization

Show child attributesHide child attributes

titlestringBeta: Name of the visualization

query_attachment_idstringBeta: The ID of the query attachment the visualization was generated from

attachment_idstring: Attachment ID

query_resultobject

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

errorobject

Error message if Genie failed to respond to the message

Show child attributesHide child attributes

errorstring

typestring: 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_idstring: Message ID
Example: e1ef34712a29169db030324fd0e1df5f

feedbackobject

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_idstring: Conversation ID
Example: e1ef34712a29169db030324fd0e1df5f

conversationobject

Show child attributesHide child attributes

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

space_idstring: Genie space ID
Example: e1ef34712a29169db030324fd0e1df5f

user_idint64: ID of the user who created the conversation
Example: e1ef34712a29169db030324fd0e1df5f

created_timestampint64: Timestamp when the message was created

last_updated_timestampint64: Timestamp when the message was last updated

titlestring: Conversation title

conversation_idstring: 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 GA​

Parameters​

Response​

Delete GA​

Parameters​

Genie Create Conversation Message GA​

Parameters​

Request body​

Response​

Genie Create Message Comment Public Preview​

Parameters​

Request body​

Response​

Genie Delete Conversation Message GA​

Parameters​

Genie Execute Message Attachment Query GA​

Parameters​

Response​

Genie Generate Download Full Query Result GA​

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

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

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

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

Parameters​

Response​

Genie Get Conversation Message GA​

Parameters​

Response​

Genie Get Download Full Query Result GA​

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

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

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

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

Parameters​

Response​

Genie Get Message Attachment Query Result GA​

Parameters​

Response​

Genie List Conversation Comments Public Preview​

Parameters​

Response​

Genie List Conversation Messages GA​

Parameters​

Response​

Genie List Message Comments Public Preview​

Parameters​

Response​

Genie Send Message Feedback GA​

Parameters​

Request body​

Genie Start Conversation GA​

Parameters​

Request body​

Response​

GenieConversation object

List GA

Parameters

Response

Delete GA

Parameters

Genie Create Conversation Message GA

Parameters

Request body

Response

Genie Create Message Comment Public Preview

Parameters

Request body

Response

Genie Delete Conversation Message GA

Parameters

Genie Execute Message Attachment Query GA

Parameters

Response

Genie Generate Download Full Query Result GA

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

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

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

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

Parameters

Response

Genie Get Conversation Message GA

Parameters

Response

Genie Get Download Full Query Result GA

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

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

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

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

Parameters

Response

Genie Get Message Attachment Query Result GA

Parameters

Response

Genie List Conversation Comments Public Preview

Parameters

Response

Genie List Conversation Messages GA

Parameters

Response

Genie List Message Comments Public Preview

Parameters

Response

Genie Send Message Feedback GA

Parameters

Request body

Genie Start Conversation GA

Parameters

Request body

Response