Use cases and templates: Databricks integration for AI agents
Use Databricks to run parameterized SQL against SQL warehouses with Unity Catalog support, list and trigger jobs, monitor runs, inspect clusters, and retrieve notebook outputs, errors, and logs. Connect with a personal access token and workspace host URL.
Genie operations ask a space questions in natural language and return answers, generated SQL, result rows, and charts when available. Reuse a conversation for follow-up questions, or choose Genie agent mode for a research report. For job workflows, check run status before retrieving completed output.
Run SQL against Databricks warehouses, trigger and monitor job runs, inspect clusters, and retrieve run output. Ask questions of a Genie space, continue a conversation, or run Genie agent research. Supply a personal access token and workspace host URL.
Execute a SQL statement against a Databricks SQL warehouse and return results inline. Supports parameterized queries and Unity Catalog.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
warehouseId | string | Yes | The ID of the SQL warehouse to execute against |
statement | string | Yes | The SQL statement to execute (max 16 MiB) |
catalog | string | No | Unity Catalog name (equivalent to USE CATALOG) |
schema | string | No | Schema name (equivalent to USE SCHEMA) |
rowLimit | number | No | Maximum number of rows to return |
waitTimeout | string | No | How long to wait for results (e.g., "50s"). Range: "0s" or "5s" to "50s". Default: "50s" |
| Parameter | Type | Description |
|---|
statementId | string | Unique identifier for the executed statement |
status | string | Execution status (SUCCEEDED, PENDING, RUNNING, FAILED, CANCELED, CLOSED) |
columns | array | Column schema of the result set |
↳ name | string | Column name |
↳ position | number | Column position (0-based) |
↳ typeName | string | Column type (STRING, INT, LONG, DOUBLE, BOOLEAN, TIMESTAMP, DATE, DECIMAL, etc.) |
data | array | Result rows as a 2D array of strings where each inner array is a row of column values |
totalRows | number | Total number of rows in the result |
truncated | boolean | Whether the result set was truncated due to row_limit or byte_limit |
Poll a SQL statement by its ID to retrieve status and results. Use this after Execute SQL when a query runs longer than the wait timeout.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
statementId | string | Yes | The ID of the statement to fetch (returned by Execute SQL) |
| Parameter | Type | Description |
|---|
statementId | string | Unique identifier for the statement |
status | string | Execution status (SUCCEEDED, PENDING, RUNNING, FAILED, CANCELED, CLOSED) |
columns | array | Column schema of the result set |
↳ name | string | Column name |
↳ position | number | Column position (0-based) |
↳ typeName | string | Column type (STRING, INT, LONG, DOUBLE, BOOLEAN, TIMESTAMP, DATE, DECIMAL, etc.) |
data | array | Result rows as a 2D array of strings where each inner array is a row of column values |
totalRows | number | Total number of rows in the result |
truncated | boolean | Whether the result set was truncated due to row_limit or byte_limit |
List all SQL warehouses in a Databricks workspace including their size, state, and type. Use this to discover the warehouse ID needed for Execute SQL.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
| Parameter | Type | Description |
|---|
warehouses | array | List of SQL warehouses in the workspace |
↳ warehouseId | string | Unique warehouse identifier |
↳ name | string | Warehouse display name |
↳ clusterSize | string | Warehouse size (e.g., 2X-Small, Small, Medium, Large) |
↳ state | string | Current state (STARTING, RUNNING, STOPPING, STOPPED, DELETING, DELETED) |
↳ warehouseType | string | Warehouse type (CLASSIC, PRO) |
↳ creatorName | string | Email of the warehouse creator |
↳ autoStopMinutes | number | Minutes of inactivity before auto-stop (0 = disabled) |
↳ numClusters | number | Current number of running clusters |
↳ minNumClusters | number | Minimum cluster count for scaling |
↳ maxNumClusters | number | Maximum cluster count for scaling |
↳ numActiveSessions | number | Number of active sessions |
↳ enableServerlessCompute | boolean | Whether serverless compute is enabled |
List all jobs in a Databricks workspace with optional filtering by name.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
limit | number | No | Maximum number of jobs to return (range 1-100, default 20) |
offset | number | No | Offset for pagination |
name | string | No | Filter jobs by exact name (case-insensitive) |
expandTasks | boolean | No | Include task and cluster details in the response (max 100 elements) |
| Parameter | Type | Description |
|---|
jobs | array | List of jobs in the workspace |
↳ jobId | number | Unique job identifier |
↳ name | string | Job name |
↳ createdTime | number | Job creation timestamp (epoch ms) |
↳ creatorUserName | string | Email of the job creator |
↳ maxConcurrentRuns | number | Maximum number of concurrent runs |
↳ format | string | Job format (SINGLE_TASK or MULTI_TASK) |
hasMore | boolean | Whether more jobs are available for pagination |
nextPageToken | string | Token for fetching the next page of results |
Get the full definition and settings of a single Databricks job by its job ID.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
jobId | number | Yes | The canonical identifier of the job to retrieve |
| Parameter | Type | Description |
|---|
jobId | number | The job ID |
name | string | Job name |
creatorUserName | string | Email of the job creator |
runAsUserName | string | User the job runs as |
createdTime | number | Job creation timestamp (epoch ms) |
format | string | Job format (SINGLE_TASK or MULTI_TASK) |
maxConcurrentRuns | number | Maximum number of concurrent runs |
timeoutSeconds | number | Job-level timeout in seconds (0 or null means no timeout) |
schedule | object | Cron schedule configuration (quartz_cron_expression, timezone_id, pause_status) |
tags | object | Key-value tags applied to the job |
tasks | array | Task definitions for the job (empty for single-task jobs) |
Trigger an existing Databricks job to run immediately with optional job-level or notebook parameters.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
jobId | number | Yes | The ID of the job to trigger |
jobParameters | string | No | Job-level parameter overrides as a JSON object (e.g., {"key": "value"}) |
notebookParams | string | No | Notebook task parameters as a JSON object (e.g., {"param1": "value1"}) |
idempotencyToken | string | No | Idempotency token to prevent duplicate runs (max 64 characters) |
| Parameter | Type | Description |
|---|
runId | number | The globally unique ID of the triggered run |
numberInJob | number | The sequence number of this run among all runs of the job |
Get the status, timing, and details of a Databricks job run by its run ID.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
runId | number | Yes | The canonical identifier of the run |
includeHistory | boolean | No | Include repair history in the response |
includeResolvedValues | boolean | No | Include resolved parameter values in the response |
| Parameter | Type | Description |
|---|
runId | number | The run ID |
jobId | number | The job ID this run belongs to |
runName | string | Name of the run |
runType | string | Type of run (JOB_RUN, WORKFLOW_RUN, SUBMIT_RUN) |
attemptNumber | number | Retry attempt number (0 for initial attempt) |
state | object | Run state information |
↳ lifeCycleState | string | Lifecycle state (QUEUED, PENDING, RUNNING, TERMINATING, TERMINATED, SKIPPED, INTERNAL_ERROR, BLOCKED, WAITING_FOR_RETRY) |
↳ resultState | string | Result state (SUCCESS, FAILED, TIMEDOUT, CANCELED, SUCCESS_WITH_FAILURES, UPSTREAM_FAILED, UPSTREAM_CANCELED, EXCLUDED) |
↳ stateMessage | string | Descriptive message for the current state |
↳ userCancelledOrTimedout | boolean | Whether the run was cancelled by user or timed out |
startTime | number | Run start timestamp (epoch ms) |
endTime | number | Run end timestamp (epoch ms, 0 if still running) |
setupDuration | number | Cluster setup duration (ms) |
executionDuration | number | Execution duration (ms) |
cleanupDuration | number | Cleanup duration (ms) |
queueDuration | number | Time spent in queue before execution (ms) |
runPageUrl | string | URL to the run detail page in Databricks UI |
creatorUserName | string | Email of the user who triggered the run |
List job runs in a Databricks workspace with optional filtering by job, status, and time range.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
jobId | number | No | Filter runs by job ID. Omit to list runs across all jobs |
activeOnly | boolean | No | Only include active runs (PENDING, RUNNING, or TERMINATING) |
completedOnly | boolean | No | Only include completed runs |
limit | number | No | Maximum number of runs to return (range 1-24, default 20) |
offset | number | No | Offset for pagination |
runType | string | No | Filter by run type (JOB_RUN, WORKFLOW_RUN, SUBMIT_RUN) |
startTimeFrom | number | No | Filter runs started at or after this timestamp (epoch ms) |
startTimeTo | number | No | Filter runs started at or before this timestamp (epoch ms) |
| Parameter | Type | Description |
|---|
runs | array | List of job runs |
↳ runId | number | Unique run identifier |
↳ jobId | number | Job this run belongs to |
↳ runName | string | Run name |
↳ runType | string | Run type (JOB_RUN, WORKFLOW_RUN, SUBMIT_RUN) |
↳ state | object | Run state information |
↳ lifeCycleState | string | Lifecycle state (QUEUED, PENDING, RUNNING, TERMINATING, TERMINATED, SKIPPED, INTERNAL_ERROR, BLOCKED, WAITING_FOR_RETRY) |
↳ resultState | string | Result state (SUCCESS, FAILED, TIMEDOUT, CANCELED, SUCCESS_WITH_FAILURES, UPSTREAM_FAILED, UPSTREAM_CANCELED, EXCLUDED) |
↳ stateMessage | string | Descriptive state message |
↳ userCancelledOrTimedout | boolean | Whether the run was cancelled by user or timed out |
↳ startTime | number | Run start timestamp (epoch ms) |
↳ endTime | number | Run end timestamp (epoch ms) |
hasMore | boolean | Whether more runs are available for pagination |
nextPageToken | string | Token for fetching the next page of results |
Cancel a running or pending Databricks job run. Cancellation is asynchronous; poll the run status to confirm termination.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
runId | number | Yes | The canonical identifier of the run to cancel |
| Parameter | Type | Description |
|---|
success | boolean | Whether the cancel request was accepted |
Get the output of a completed Databricks job run, including notebook results, error messages, and logs. For multi-task jobs, use the task run ID (not the parent run ID).
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
runId | number | Yes | The run ID to get output for. For multi-task jobs, use the task run ID |
| Parameter | Type | Description |
|---|
notebookOutput | object | Notebook task output (from dbutils.notebook.exit()) |
↳ result | string | Value passed to dbutils.notebook.exit() (max 5 MB) |
↳ truncated | boolean | Whether the result was truncated |
error | string | Error message if the run failed or output is unavailable |
errorTrace | string | Error stack trace if available |
logs | string | Log output (last 5 MB) from spark_jar, spark_python, or python_wheel tasks |
logsTruncated | boolean | Whether the log output was truncated |
List all clusters in a Databricks workspace including their state, configuration, and resource details.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
| Parameter | Type | Description |
|---|
clusters | array | List of clusters in the workspace |
↳ clusterId | string | Unique cluster identifier |
↳ clusterName | string | Cluster display name |
↳ state | string | Current state (PENDING, RUNNING, RESTARTING, RESIZING, TERMINATING, TERMINATED, ERROR, UNKNOWN) |
↳ stateMessage | string | Human-readable state description |
↳ creatorUserName | string | Email of the cluster creator |
↳ sparkVersion | string | Spark runtime version (e.g., 13.3.x-scala2.12) |
↳ nodeTypeId | string | Worker node type identifier |
↳ driverNodeTypeId | string | Driver node type identifier |
↳ numWorkers | number | Number of worker nodes (for fixed-size clusters) |
↳ autoscale | object | Autoscaling configuration (null for fixed-size clusters) |
↳ minWorkers | number | Minimum number of workers |
↳ maxWorkers | number | Maximum number of workers |
↳ clusterSource | string | Origin (API, UI, JOB, MODELS, PIPELINE, PIPELINE_MAINTENANCE, SQL) |
↳ autoterminationMinutes | number | Minutes of inactivity before auto-termination (0 = disabled) |
↳ startTime | number | Cluster start timestamp (epoch ms) |
Get the state, configuration, and resource details of a single Databricks cluster by its cluster ID.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
clusterId | string | Yes | The ID of the cluster to retrieve |
| Parameter | Type | Description |
|---|
cluster | object | Cluster detail |
↳ clusterId | string | Unique cluster identifier |
↳ clusterName | string | Cluster display name |
↳ state | string | Current state (PENDING, RUNNING, RESTARTING, RESIZING, TERMINATING, TERMINATED, ERROR, UNKNOWN) |
↳ stateMessage | string | Human-readable state description |
↳ creatorUserName | string | Email of the cluster creator |
↳ sparkVersion | string | Spark runtime version (e.g., 13.3.x-scala2.12) |
↳ nodeTypeId | string | Worker node type identifier |
↳ driverNodeTypeId | string | Driver node type identifier |
↳ numWorkers | number | Number of worker nodes (for fixed-size clusters) |
↳ autoscale | object | Autoscaling configuration (null for fixed-size clusters) |
↳ minWorkers | number | Minimum number of workers |
↳ maxWorkers | number | Maximum number of workers |
↳ clusterSource | string | Origin (API, UI, JOB, MODELS, PIPELINE, PIPELINE_MAINTENANCE, SQL) |
↳ autoterminationMinutes | number | Minutes of inactivity before auto-termination (0 = disabled) |
↳ startTime | number | Cluster start timestamp (epoch ms) |
Ask a Databricks Genie space a question in natural language and wait for the answer. Starts a new conversation, or continues an existing one when a conversation ID is given. Returns the text answer, the SQL Genie generated, and the query result rows.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
content | string | Yes | The question to ask Genie |
conversationId | string | No | Continue this conversation so Genie uses its earlier messages as context. Omit to start a new conversation. |
enableVisualization | boolean | No | Ask Genie to also generate a chart when one fits the answer |
| Parameter | Type | Description |
|---|
conversationId | string | Genie conversation ID |
messageId | string | Genie message ID |
status | string | Message status (SUBMITTED, FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, COMPLETED, FAILED, CANCELLED, QUERY_RESULT_EXPIRED) |
content | string | The question that was asked |
answer | string | Genie's text answer or summary |
followUpQuestion | string | Clarifying question Genie asked instead of, or alongside, an answer |
queryTitle | string | Title of the generated query |
sql | string | SQL query Genie generated |
queryDescription | string | Plain-language description of the generated SQL |
queryAttachmentId | string | Attachment ID of the generated query, used to fetch or re-run its result |
statementId | string | SQL statement ID of the generated query |
rowCount | number | Number of rows the generated query returned |
thoughts | array | How Genie interpreted the question and built the SQL (Public Preview) |
↳ type | string | Thought category (THOUGHT_TYPE_DESCRIPTION, THOUGHT_TYPE_UNDERSTANDING, THOUGHT_TYPE_DATA_SOURCING, THOUGHT_TYPE_INSTRUCTIONS, THOUGHT_TYPE_STEPS) |
↳ content | string | Markdown-formatted thought |
suggestedQuestions | array | Follow-up questions suggested by Genie |
visualizations | array | Charts Genie generated (only when visualization was requested) |
↳ attachmentId | string | Visualization attachment ID, used to download the chart |
↳ title | string | Chart title |
↳ queryAttachmentId | string | Query attachment the chart was built from |
error | string | Why Genie failed to answer |
errorType | string | Genie error type |
createdTimestamp | number | When the message was created |
columns | array | Column schema of the query result |
↳ name | string | Column name |
↳ position | number | Column position (0-based) |
↳ typeName | string | Column type (STRING, INT, LONG, DOUBLE, BOOLEAN, TIMESTAMP, DATE, DECIMAL, etc.) |
data | array | Result rows as a 2D array; each non-null value is a string and null values stay null |
totalRows | number | Total number of rows in the result |
truncated | boolean | Whether the result set was truncated |
Get a Genie message's status and answer, including the generated SQL, visualizations, and suggested follow-up questions.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
| Parameter | Type | Description |
|---|
conversationId | string | Genie conversation ID |
messageId | string | Genie message ID |
status | string | Message status (SUBMITTED, FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, COMPLETED, FAILED, CANCELLED, QUERY_RESULT_EXPIRED) |
content | string | The question that was asked |
answer | string | Genie's text answer or summary |
followUpQuestion | string | Clarifying question Genie asked instead of, or alongside, an answer |
queryTitle | string | Title of the generated query |
sql | string | SQL query Genie generated |
queryDescription | string | Plain-language description of the generated SQL |
queryAttachmentId | string | Attachment ID of the generated query, used to fetch or re-run its result |
statementId | string | SQL statement ID of the generated query |
rowCount | number | Number of rows the generated query returned |
thoughts | array | How Genie interpreted the question and built the SQL (Public Preview) |
↳ type | string | Thought category (THOUGHT_TYPE_DESCRIPTION, THOUGHT_TYPE_UNDERSTANDING, THOUGHT_TYPE_DATA_SOURCING, THOUGHT_TYPE_INSTRUCTIONS, THOUGHT_TYPE_STEPS) |
↳ content | string | Markdown-formatted thought |
suggestedQuestions | array | Follow-up questions suggested by Genie |
visualizations | array | Charts Genie generated (only when visualization was requested) |
↳ attachmentId | string | Visualization attachment ID, used to download the chart |
↳ title | string | Chart title |
↳ queryAttachmentId | string | Query attachment the chart was built from |
error | string | Why Genie failed to answer |
errorType | string | Genie error type |
createdTimestamp | number | When the message was created |
List the messages in a Genie conversation with their answers and generated SQL, for example to replay a conversation history.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
pageSize | number | No | Maximum number of messages to return per page (default 20, max 100) |
pageToken | string | No | Pagination token from a previous response |
| Parameter | Type | Description |
|---|
messages | array | Messages in the conversation |
↳ conversationId | string | Genie conversation ID |
↳ messageId | string | Genie message ID |
↳ status | string | Message status (SUBMITTED, FETCHING_METADATA, FILTERING_CONTEXT, ASKING_AI, PENDING_WAREHOUSE, EXECUTING_QUERY, COMPLETED, FAILED, CANCELLED, QUERY_RESULT_EXPIRED) |
↳ content | string | The question that was asked |
↳ answer | string | Genie's text answer or summary |
↳ followUpQuestion | string | Clarifying question Genie asked instead of, or alongside, an answer |
↳ queryTitle | string | Title of the generated query |
↳ sql | string | SQL query Genie generated |
↳ queryDescription | string | Plain-language description of the generated SQL |
↳ queryAttachmentId | string | Attachment ID of the generated query, used to fetch or re-run its result |
↳ statementId | string | SQL statement ID of the generated query |
↳ rowCount | number | Number of rows the generated query returned |
↳ thoughts | array | How Genie interpreted the question and built the SQL (Public Preview) |
↳ type | string | Thought category (THOUGHT_TYPE_DESCRIPTION, THOUGHT_TYPE_UNDERSTANDING, THOUGHT_TYPE_DATA_SOURCING, THOUGHT_TYPE_INSTRUCTIONS, THOUGHT_TYPE_STEPS) |
↳ content | string | Markdown-formatted thought |
↳ suggestedQuestions | array | Follow-up questions suggested by Genie |
↳ visualizations | array | Charts Genie generated (only when visualization was requested) |
↳ attachmentId | string | Visualization attachment ID, used to download the chart |
↳ title | string | Chart title |
↳ queryAttachmentId | string | Query attachment the chart was built from |
↳ error | string | Why Genie failed to answer |
↳ errorType | string | Genie error type |
↳ createdTimestamp | number | When the message was created |
nextPageToken | string | Token for the next page of results |
Get the rows returned by the SQL query Genie generated for a message. Available once the message is EXECUTING_QUERY or COMPLETED.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
attachmentId | string | Yes | The query attachment ID (queryAttachmentId from Ask Genie or Get Genie Message) |
| Parameter | Type | Description |
|---|
columns | array | Column schema of the query result |
↳ name | string | Column name |
↳ position | number | Column position (0-based) |
↳ typeName | string | Column type (STRING, INT, LONG, DOUBLE, BOOLEAN, TIMESTAMP, DATE, DECIMAL, etc.) |
data | array | Result rows as a 2D array; each non-null value is a string and null values stay null |
totalRows | number | Total number of rows in the result |
truncated | boolean | Whether the result set was truncated |
statementId | string | SQL statement ID of the query |
status | string | Statement status (PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, CLOSED) |
Re-run the SQL query Genie generated for a message. Use this when the message's query result has expired (status QUERY_RESULT_EXPIRED). If the returned status is PENDING or RUNNING, fetch the rows afterwards with Get Genie Query Result.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
attachmentId | string | Yes | The query attachment ID (queryAttachmentId from Ask Genie or Get Genie Message) |
| Parameter | Type | Description |
|---|
columns | array | Column schema of the query result |
↳ name | string | Column name |
↳ position | number | Column position (0-based) |
↳ typeName | string | Column type (STRING, INT, LONG, DOUBLE, BOOLEAN, TIMESTAMP, DATE, DECIMAL, etc.) |
data | array | Result rows as a 2D array; each non-null value is a string and null values stay null |
totalRows | number | Total number of rows in the result |
truncated | boolean | Whether the result set was truncated |
statementId | string | SQL statement ID of the query |
status | string | Statement status (PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, CLOSED) |
Download a chart Genie generated as a PNG image, for example to post it to Slack. The message must be COMPLETED and asked with visualization enabled. Not supported on Private Link workspaces.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
attachmentId | string | Yes | The visualization attachment ID (visualizations[].attachmentId) |
| Parameter | Type | Description |
|---|
file | file | Rendered chart image (PNG) stored in execution files |
Rate a Genie answer as positive or negative, with an optional comment. Space authors use this feedback to improve the space's instructions.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
rating | string | Yes | Feedback rating: POSITIVE, NEGATIVE, or NONE (clears a previous rating) |
comment | string | No | Optional feedback comment (max 5000 characters) |
| Parameter | Type | Description |
|---|
success | boolean | Whether the feedback was recorded |
Delete a message from a Genie conversation.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation |
messageId | string | Yes | The ID of the Genie message |
| Parameter | Type | Description |
|---|
success | boolean | Whether the message was deleted |
List conversations in a Genie space, including whether each is a chat-mode or agent-mode conversation. By default only your own conversations are returned.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
includeAll | boolean | No | Include every user's conversations in the space (requires CAN MANAGE on the space) |
pageSize | number | No | Maximum number of conversations to return per page (default 20, max 100) |
pageToken | string | No | Pagination token from a previous response |
| Parameter | Type | Description |
|---|
conversations | array | Conversations in the Genie space |
↳ conversationId | string | Conversation ID |
↳ title | string | Conversation title |
↳ createdTimestamp | number | When the conversation was created |
↳ agentType | string | Conversation mode (GENIE_CONVERSATION_TYPE_CHAT or GENIE_CONVERSATION_TYPE_AGENT) |
nextPageToken | string | Token for the next page of results |
Delete a Genie conversation you no longer need.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
conversationId | string | Yes | The ID of the Genie conversation to delete |
| Parameter | Type | Description |
|---|
success | boolean | Whether the conversation was deleted |
List the Genie spaces (Genie agents) you can access. Use this to find the space ID needed to ask Genie a question.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
pageSize | number | No | Maximum number of spaces to return per page (default 20, max 100) |
pageToken | string | No | Pagination token from a previous response |
| Parameter | Type | Description |
|---|
spaces | array | Genie spaces |
↳ spaceId | string | Genie space ID |
↳ title | string | Space title |
↳ description | string | Space description |
↳ warehouseId | string | SQL warehouse the space runs queries on |
↳ parentPath | string | Workspace folder containing the space |
↳ createTime | string | When the space was created (ISO 8601) |
↳ updateTime | string | When the space was last modified (ISO 8601) |
nextPageToken | string | Token for the next page of results |
Get a Genie space's title, description, and SQL warehouse, optionally with its full configuration export (tables, instructions, sample questions).
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space |
includeSerializedSpace | boolean | No | Include the space's serialized configuration export (requires CAN EDIT on the space) |
| Parameter | Type | Description |
|---|
spaceId | string | Genie space ID |
title | string | Space title |
description | string | Space description |
warehouseId | string | SQL warehouse the space runs queries on |
parentPath | string | Workspace folder containing the space |
createTime | string | When the space was created (ISO 8601) |
updateTime | string | When the space was last modified (ISO 8601) |
serializedSpace | string | Serialized space configuration as a JSON string (data sources, instructions, sample questions) |
Ask a Genie agent a question in agent mode, where Genie plans multi-step research, runs several SQL queries, and writes a report with citations. Waits for the final report. Starts a new agent-mode conversation, or continues one when a conversation ID is given. Agent mode is in preview and must be enabled on the workspace.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space (the Genie agent ID) |
content | string | Yes | The question to ask the Genie agent |
conversationId | string | No | Continue this agent-mode conversation. Omit to start a new conversation. |
enableVisualization | boolean | No | Ask the agent to also generate charts where they fit |
| Parameter | Type | Description |
|---|
responseId | string | Agent response ID |
conversationId | string | Agent-mode conversation ID; pass it back to ask a follow-up |
status | string | Response status (completed) |
report | string | The agent's final report, with citation links |
queries | array | SQL queries the agent ran |
↳ callId | string | Function call ID |
↳ title | string | Query title |
↳ sql | string | SQL the agent ran |
items | array | Every output item: reasoning, SQL calls, query results, and messages |
↳ type | string | Item type (message, reasoning, function_call, function_call_output) |
↳ id | string | Item ID |
↳ status | string | Item status |
↳ role | string | Message role (user, assistant, or system) for message items |
↳ text | string | Text of a message or reasoning item |
↳ callId | string | Pairs a function_call with its function_call_output |
↳ name | string | Function name (execute_sql) |
↳ arguments | string | Function call arguments as a JSON string (title and sql) |
↳ output | string | Query result: the query title followed by a Markdown table |
createdAt | number | When the response was created (Unix epoch seconds) |
error | string | System error message the agent reported alongside its report |
List an agent-mode conversation's full history in order: questions, reasoning, SQL calls, query results, and reports. Agent mode is in preview and must be enabled on the workspace.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
spaceId | string | Yes | The ID of the Genie space (the Genie agent ID) |
conversationId | string | Yes | The ID of the agent-mode conversation |
limit | number | No | Maximum number of items to return (1-100, default 100) |
after | string | No | Pagination cursor: the lastId from a previous response |
order | string | No | Sort order: asc (oldest first, default) or desc (newest first) |
| Parameter | Type | Description |
|---|
items | array | Conversation items in order; user questions are message items whose ID ends in _input |
↳ type | string | Item type (message, reasoning, function_call, function_call_output) |
↳ id | string | Item ID |
↳ status | string | Item status |
↳ role | string | Message role (user, assistant, or system) for message items |
↳ text | string | Text of a message or reasoning item |
↳ callId | string | Pairs a function_call with its function_call_output |
↳ name | string | Function name (execute_sql) |
↳ arguments | string | Function call arguments as a JSON string (title and sql) |
↳ output | string | Query result: the query title followed by a Markdown table |
firstId | string | ID of the first item in the page |
lastId | string | ID of the last item in the page; pass it as After for the next page |
hasMore | boolean | Whether more items follow this page |
status | string | Status of the latest response in the conversation |