Databricks is a unified data analytics platform built on Apache Spark, providing a collaborative environment for data engineering, data science, and machine learning. Databricks combines data warehousing, ETL, and AI workloads into a single lakehouse architecture, with support for SQL analytics, job orchestration, and cluster management across major cloud providers.
With the Databricks integration in Agent Serve, you can:
- Execute SQL queries: Run SQL statements against Databricks SQL warehouses with support for parameterized queries and Unity Catalog
- Manage jobs: List, trigger, and monitor Databricks job runs programmatically
- Track run status: Get detailed run information including timing, state, and output results
- Control clusters: List and inspect cluster configurations, states, and resource details
- Retrieve run outputs: Access notebook results, error messages, and logs from completed job runs
In Agent Serve, the Databricks integration enables your agents to interact with your data lakehouse as part of automated workflows. Agents can query large-scale datasets, orchestrate ETL pipelines by triggering jobs, monitor job execution, and retrieve results—all without leaving the workflow canvas. This is ideal for automated reporting, data pipeline management, scheduled analytics, and building AI-driven data workflows that react to query results or job outcomes.
Execute parameterized SQL and retrieve result chunks, create and manage jobs, submit and repair runs, manage compute clusters and SQL warehouses, and create or update Genie spaces. Ask Genie questions or run agent research, inspect conversations, and retrieve query results and charts. Connect with 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 |
sqlParameters | json | No | Named parameters as [{name, value, type}]; null or omitted value represents SQL NULL |
byteLimit | number | No | Maximum result size in bytes; truncation is reported in the output |
onWaitTimeout | string | No | CONTINUE (default) or CANCEL execution when the wait timeout expires |
waitTimeout | string | No | How long the warehouse waits before answering (e.g., "50s"). Range: "0s" or "5s" to "50s". Default: "50s". A statement still PENDING/RUNNING after that is polled for up to 4 more minutes before the result is returned. |
| Parameter | Type | Description |
|---|
totalChunks | number | Number of result chunks |
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
rowCount | number | Number of rows in this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
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) |
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 |
warehouseId | string | No | SQL warehouse identifier, when required by the statement endpoint |
statementId | string | Yes | The ID of the statement to fetch (returned by Execute SQL) |
| Parameter | Type | Description |
|---|
totalChunks | number | Number of result chunks |
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
rowCount | number | Number of rows in this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
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) |
Retrieve one chunk of an INLINE SQL result using nextChunkIndex from Execute SQL or Get Statement.
| 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 | SQL statement identifier |
chunkIndex | number | Yes | Zero-based result chunk index |
warehouseId | string | No | SQL warehouse identifier, when required by the statement endpoint |
| Parameter | Type | Description |
|---|
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
rowCount | number | Number of rows in this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
data | array | Result rows as a 2D array; each non-null value is a string and null values stay null |
Request cancellation of an executing SQL statement; poll Get Statement to confirm its final status.
| 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 | SQL statement identifier |
warehouseId | string | No | SQL warehouse identifier, when required by the statement endpoint |
| Parameter | Type | Description |
|---|
success | boolean | Whether the cancellation request was accepted |
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) |
pageToken | string | No | Token for the next or previous page; takes precedence over legacy offset |
offset | number | No | Legacy Jobs 2.1 offset; prefer pageToken |
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 |
|---|
prevPageToken | string | Token for the previous page |
jobs | array | List of jobs in the workspace |
↳ tasks | array | Task definitions and task run IDs; nested keys use Databricks API names |
↳ task_key | string | Task key |
↳ run_id | number | Task run ID for Get Run Output |
↳ description | string | Task description |
↳ depends_on | array | depends_on output from the tool |
↳ task_key | string | Upstream task key |
↳ outcome | string | Required outcome of a condition task |
↳ existing_cluster_id | string | Existing compute cluster |
↳ job_cluster_key | string | Shared job cluster key |
↳ notebook_task | object | notebook_task output from the tool |
↳ notebook_path | string | Notebook path |
↳ source | string | WORKSPACE or GIT |
↳ base_parameters | object | Notebook parameter map |
↳ spark_python_task | object | spark_python_task output from the tool |
↳ python_file | string | Python file path or cloud URI |
↳ source | string | WORKSPACE or GIT |
↳ parameters | array | parameters output from the tool |
↳ spark_jar_task | object | spark_jar_task output from the tool |
↳ main_class_name | string | JAR entry point class |
↳ parameters | array | parameters output from the tool |
↳ jar_uri | string | Legacy JAR URI |
↳ spark_submit_task | object | Legacy spark-submit task |
↳ parameters | array | parameters output from the tool |
↳ python_wheel_task | object | python_wheel_task output from the tool |
↳ package_name | string | Python package name |
↳ entry_point | string | Package entry point |
↳ parameters | array | parameters output from the tool |
↳ named_parameters | object | Named wheel parameters |
↳ sql_task | object | sql_task output from the tool |
↳ warehouse_id | string | SQL warehouse identifier |
↳ parameters | object | SQL parameters |
↳ query | object | query output from the tool |
↳ query_id | string | Saved query identifier |
↳ file | object | file output from the tool |
↳ path | string | SQL file path |
↳ source | string | WORKSPACE or GIT |
↳ alert | object | alert output from the tool |
↳ alert_id | string | SQL alert identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ dashboard | object | dashboard output from the tool |
↳ dashboard_id | string | Legacy SQL dashboard identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ custom_subject | string | custom_subject output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ run_job_task | object | run_job_task output from the tool |
↳ job_id | number | Nested job identifier |
↳ job_parameters | object | Nested job parameters |
↳ pipeline_params | object | Pipeline refresh settings |
↳ pipeline_task | object | pipeline_task output from the tool |
↳ pipeline_id | string | Pipeline identifier |
↳ parameters | object | parameters output from the tool |
↳ full_refresh | boolean | full_refresh output from the tool |
↳ refresh_selection | array | refresh_selection output from the tool |
↳ full_refresh_selection | array | full_refresh_selection output from the tool |
↳ reset_checkpoint_selection | array | reset_checkpoint_selection output from the tool |
↳ refresh_flow_selection | array | refresh_flow_selection output from the tool |
↳ dbt_task | object | dbt_task output from the tool |
↳ commands | array | dbt commands |
↳ project_directory | string | project_directory output from the tool |
↳ profiles_directory | string | profiles_directory output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ catalog | string | catalog output from the tool |
↳ schema | string | schema output from the tool |
↳ source | string | WORKSPACE or GIT |
↳ condition_task | object | condition_task output from the tool |
↳ op | string | Comparison operator |
↳ left | string | Left operand |
↳ right | string | Right operand |
↳ outcome | string | Evaluation result: true or false |
↳ for_each_task | object | for_each_task output from the tool |
↳ inputs | string | JSON array or parameter reference to iterate over |
↳ concurrency | number | concurrency output from the tool |
↳ task | object | Nested task definition |
↳ clean_rooms_notebook_task | object | clean_rooms_notebook_task output from the tool |
↳ clean_room_name | string | clean_room_name output from the tool |
↳ notebook_name | string | notebook_name output from the tool |
↳ etag | string | etag output from the tool |
↳ notebook_base_parameters | object | notebook_base_parameters output from the tool |
↳ dashboard_task | object | dashboard_task output from the tool |
↳ dashboard_id | string | dashboard_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ subscription | object | subscription output from the tool |
↳ filters | object | filters output from the tool |
↳ alert_task | object | alert_task output from the tool |
↳ alert_id | string | alert_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ workspace_path | string | workspace_path output from the tool |
↳ subscribers | array | subscribers output from the tool |
↳ power_bi_task | object | power_bi_task output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ connection_resource_name | string | connection_resource_name output from the tool |
↳ refresh_after_update | boolean | refresh_after_update output from the tool |
↳ power_bi_model | object | power_bi_model output from the tool |
↳ tables | array | tables output from the tool |
↳ state | object | state output from the tool |
↳ life_cycle_state | string | life_cycle_state output from the tool |
↳ result_state | string | result_state output from the tool |
↳ state_message | string | state_message output from the tool |
↳ resolved_values | object | Resolved task parameters keyed by task type (notebook_task, spark_python_task, sql_task, and other task variants) |
↳ start_time | number | Task start in epoch milliseconds |
↳ end_time | number | Task end in epoch milliseconds |
↳ run_page_url | string | Task run URL |
↳ jobClusters | array | Shared job compute definitions |
↳ job_cluster_key | string | Cluster reference key |
↳ new_cluster | object | Cloud-dependent compute configuration |
↳ spark_version | string | spark_version output from the tool |
↳ node_type_id | string | node_type_id output from the tool |
↳ num_workers | number | num_workers output from the tool |
↳ autoscale | object | autoscale output from the tool |
↳ min_workers | number | min_workers output from the tool |
↳ max_workers | number | max_workers output from the tool |
↳ hasMore | boolean | Whether tasks or job clusters have additional pages |
↳ 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 |
|---|
includeTriggerState | boolean | No | Include current job trigger state |
pageToken | string | No | Token for the next page of tasks and job clusters |
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 |
|---|
tasks | array | Task definitions and task run IDs; nested keys use Databricks API names |
↳ task_key | string | Task key |
↳ run_id | number | Task run ID for Get Run Output |
↳ description | string | Task description |
↳ depends_on | array | depends_on output from the tool |
↳ task_key | string | Upstream task key |
↳ outcome | string | Required outcome of a condition task |
↳ existing_cluster_id | string | Existing compute cluster |
↳ job_cluster_key | string | Shared job cluster key |
↳ notebook_task | object | notebook_task output from the tool |
↳ notebook_path | string | Notebook path |
↳ source | string | WORKSPACE or GIT |
↳ base_parameters | object | Notebook parameter map |
↳ spark_python_task | object | spark_python_task output from the tool |
↳ python_file | string | Python file path or cloud URI |
↳ source | string | WORKSPACE or GIT |
↳ parameters | array | parameters output from the tool |
↳ spark_jar_task | object | spark_jar_task output from the tool |
↳ main_class_name | string | JAR entry point class |
↳ parameters | array | parameters output from the tool |
↳ jar_uri | string | Legacy JAR URI |
↳ spark_submit_task | object | Legacy spark-submit task |
↳ parameters | array | parameters output from the tool |
↳ python_wheel_task | object | python_wheel_task output from the tool |
↳ package_name | string | Python package name |
↳ entry_point | string | Package entry point |
↳ parameters | array | parameters output from the tool |
↳ named_parameters | object | Named wheel parameters |
↳ sql_task | object | sql_task output from the tool |
↳ warehouse_id | string | SQL warehouse identifier |
↳ parameters | object | SQL parameters |
↳ query | object | query output from the tool |
↳ query_id | string | Saved query identifier |
↳ file | object | file output from the tool |
↳ path | string | SQL file path |
↳ source | string | WORKSPACE or GIT |
↳ alert | object | alert output from the tool |
↳ alert_id | string | SQL alert identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ dashboard | object | dashboard output from the tool |
↳ dashboard_id | string | Legacy SQL dashboard identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ custom_subject | string | custom_subject output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ run_job_task | object | run_job_task output from the tool |
↳ job_id | number | Nested job identifier |
↳ job_parameters | object | Nested job parameters |
↳ pipeline_params | object | Pipeline refresh settings |
↳ pipeline_task | object | pipeline_task output from the tool |
↳ pipeline_id | string | Pipeline identifier |
↳ parameters | object | parameters output from the tool |
↳ full_refresh | boolean | full_refresh output from the tool |
↳ refresh_selection | array | refresh_selection output from the tool |
↳ full_refresh_selection | array | full_refresh_selection output from the tool |
↳ reset_checkpoint_selection | array | reset_checkpoint_selection output from the tool |
↳ refresh_flow_selection | array | refresh_flow_selection output from the tool |
↳ dbt_task | object | dbt_task output from the tool |
↳ commands | array | dbt commands |
↳ project_directory | string | project_directory output from the tool |
↳ profiles_directory | string | profiles_directory output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ catalog | string | catalog output from the tool |
↳ schema | string | schema output from the tool |
↳ source | string | WORKSPACE or GIT |
↳ condition_task | object | condition_task output from the tool |
↳ op | string | Comparison operator |
↳ left | string | Left operand |
↳ right | string | Right operand |
↳ outcome | string | Evaluation result: true or false |
↳ for_each_task | object | for_each_task output from the tool |
↳ inputs | string | JSON array or parameter reference to iterate over |
↳ concurrency | number | concurrency output from the tool |
↳ task | object | Nested task definition |
↳ clean_rooms_notebook_task | object | clean_rooms_notebook_task output from the tool |
↳ clean_room_name | string | clean_room_name output from the tool |
↳ notebook_name | string | notebook_name output from the tool |
↳ etag | string | etag output from the tool |
↳ notebook_base_parameters | object | notebook_base_parameters output from the tool |
↳ dashboard_task | object | dashboard_task output from the tool |
↳ dashboard_id | string | dashboard_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ subscription | object | subscription output from the tool |
↳ filters | object | filters output from the tool |
↳ alert_task | object | alert_task output from the tool |
↳ alert_id | string | alert_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ workspace_path | string | workspace_path output from the tool |
↳ subscribers | array | subscribers output from the tool |
↳ power_bi_task | object | power_bi_task output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ connection_resource_name | string | connection_resource_name output from the tool |
↳ refresh_after_update | boolean | refresh_after_update output from the tool |
↳ power_bi_model | object | power_bi_model output from the tool |
↳ tables | array | tables output from the tool |
↳ state | object | state output from the tool |
↳ life_cycle_state | string | life_cycle_state output from the tool |
↳ result_state | string | result_state output from the tool |
↳ state_message | string | state_message output from the tool |
↳ resolved_values | object | Resolved task parameters keyed by task type (notebook_task, spark_python_task, sql_task, and other task variants) |
↳ start_time | number | Task start in epoch milliseconds |
↳ end_time | number | Task end in epoch milliseconds |
↳ run_page_url | string | Task run URL |
jobClusters | array | Shared job compute definitions |
↳ job_cluster_key | string | Cluster reference key |
↳ new_cluster | object | Cloud-dependent compute configuration |
↳ spark_version | string | spark_version output from the tool |
↳ node_type_id | string | node_type_id output from the tool |
↳ num_workers | number | num_workers output from the tool |
↳ autoscale | object | autoscale output from the tool |
↳ min_workers | number | min_workers output from the tool |
↳ max_workers | number | max_workers output from the tool |
description | string | Job description |
parameters | array | Job parameter definitions |
queue | object | Job queue settings |
triggerState | object | Current file-arrival, table-update, or periodic trigger state |
↳ file_arrival | object | file_arrival output from the tool |
↳ table | object | table output from the tool |
↳ last_seen_table_states | array | last_seen_table_states output from the tool |
nextPageToken | string | Token for the next page of tasks or job clusters |
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 |
Create a Databricks job with tasks, scheduling, execution identity, and notifications.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
accessControlList | json | No | Initial permissions as [{user_name, group_name, service_principal_name, permission_level}] |
name | string | No | Display name of the job |
description | string | No | Description of the job |
emailNotifications | json | No | Email recipients by event, such as {on_failure: ["ops@example.com"]} |
webhookNotifications | json | No | Notification destination IDs grouped by event |
notificationSettings | json | No | Notification preferences for skipped runs, canceled runs, and retries |
timeoutSeconds | number | No | Maximum run duration in seconds; 0 disables the timeout |
health | json | No | Health rules as {rules: [{metric, op, value}]} |
schedule | json | No | Quartz schedule as {quartz_cron_expression, timezone_id, pause_status} |
jobTrigger | json | No | Job trigger settings in Databricks API format |
continuous | json | No | Continuous execution settings; mutually exclusive with schedule |
maxConcurrentRuns | number | No | Maximum simultaneous runs allowed for this job |
tasks | json | No | Task definitions using Databricks API fields, including task_key, depends_on, and notebook_task or other task types |
jobClusters | json | No | Shared job clusters as [{job_cluster_key, new_cluster}] |
gitSource | json | No | Git repository URL, provider, and branch, tag, or commit |
tags | json | No | Job tags as a JSON object of string keys and values |
queue | json | No | Queue behavior as {enabled: true} or {enabled: false} |
parameters | json | No | Job parameter definitions as [{name, default}] |
runAs | json | No | Execution identity as {user_name} or {service_principal_name} |
editMode | string | No | Whether the job can be edited in the Databricks UI |
deployment | json | No | External deployment metadata including kind and metadata_file_path |
environments | json | No | Task environments as [{environment_key, spec}] |
budgetPolicyId | string | No | Serverless budget policy identifier |
performanceTarget | string | No | Serverless performance mode: STANDARD or PERFORMANCE_OPTIMIZED |
triggers | json | No | Job trigger definitions; cannot be combined with the singular trigger setting |
environmentVariables | json | No | Named environment variable definitions in Databricks API format |
maxRetries | number | No | Maximum retry count; -1 retries indefinitely and 0 disables retries |
minRetryIntervalMillis | number | No | Minimum time in milliseconds between attempts |
retryOnTimeout | boolean | No | Whether a timed-out run should be retried |
disableAutoOptimization | boolean | No | Disable serverless automatic optimization |
| Parameter | Type | Description |
|---|
jobId | number | Job identifier |
Merge selected settings into a Databricks job and optionally remove settings or tasks.
| 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 | Job identifier |
newSettings | json | No | Job settings in Databricks API format; Update merges top-level fields and task keys, Reset replaces all settings |
fieldsToRemove | json | No | Settings to remove, such as ["schedule", "tasks/task_key"] |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Replace all settings of a Databricks job.
| 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 | Job identifier |
newSettings | json | Yes | Job settings in Databricks API format; Update merges top-level fields and task keys, Reset replaces all settings |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Delete a Databricks job and cancel its active runs.
| 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 | Job identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Trigger an existing Databricks job to run immediately with optional job-level or notebook parameters.
| Parameter | Type | Required | Description |
|---|
only | json | No | Task keys to run; omit to run every task |
queue | json | No | Run queue settings as {enabled: true} or {enabled: false} |
performanceTarget | string | No | Serverless performance: STANDARD or PERFORMANCE_OPTIMIZED |
pipelineParams | json | No | Pipeline full_refresh and selective table or flow settings |
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 | json | No | Job-level parameter overrides as a JSON object (e.g., {"key": "value"}) |
notebookParams | json | 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 |
Submit a one-time task run without creating a saved job.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
accessControlList | json | No | Initial permissions as [{user_name, group_name, service_principal_name, permission_level}] |
queue | json | No | Queue behavior as {enabled: true} or {enabled: false} |
runAs | json | No | Execution identity as {user_name} or {service_principal_name} |
runName | string | No | Display name of the one-time run |
timeoutSeconds | number | No | Maximum run duration in seconds; 0 disables the timeout |
health | json | No | Health rules as {rules: [{metric, op, value}]} |
idempotencyToken | string | No | Retry token that prevents duplicate runs; at most 64 characters |
tasks | json | No | Task definitions using Databricks API fields, including task_key, depends_on, and notebook_task or other task types |
gitSource | json | No | Git repository URL, provider, and branch, tag, or commit |
webhookNotifications | json | No | Notification destination IDs grouped by event |
emailNotifications | json | No | Email recipients by event, such as {on_failure: ["ops@example.com"]} |
notificationSettings | json | No | Notification preferences for skipped runs, canceled runs, and retries |
environments | json | No | Task environments as [{environment_key, spec}] |
budgetPolicyId | string | No | Serverless budget policy identifier |
environmentVariables | json | No | Named environment variable definitions in Databricks API format |
performanceTarget | string | No | Serverless performance mode: STANDARD or PERFORMANCE_OPTIMIZED |
| Parameter | Type | Description |
|---|
runId | number | Run identifier |
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) |
pageToken | string | No | Token for the next or previous page; takes precedence over legacy offset |
offset | number | No | Legacy Jobs 2.1 offset; prefer pageToken |
expandTasks | boolean | No | Include the first 100 tasks and job clusters for each run |
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 |
|---|
prevPageToken | string | Token for the previous page |
runs | array | List of job runs |
↳ tasks | array | Task definitions and task run IDs; nested keys use Databricks API names |
↳ task_key | string | Task key |
↳ run_id | number | Task run ID for Get Run Output |
↳ description | string | Task description |
↳ depends_on | array | depends_on output from the tool |
↳ task_key | string | Upstream task key |
↳ outcome | string | Required outcome of a condition task |
↳ existing_cluster_id | string | Existing compute cluster |
↳ job_cluster_key | string | Shared job cluster key |
↳ notebook_task | object | notebook_task output from the tool |
↳ notebook_path | string | Notebook path |
↳ source | string | WORKSPACE or GIT |
↳ base_parameters | object | Notebook parameter map |
↳ spark_python_task | object | spark_python_task output from the tool |
↳ python_file | string | Python file path or cloud URI |
↳ source | string | WORKSPACE or GIT |
↳ parameters | array | parameters output from the tool |
↳ spark_jar_task | object | spark_jar_task output from the tool |
↳ main_class_name | string | JAR entry point class |
↳ parameters | array | parameters output from the tool |
↳ jar_uri | string | Legacy JAR URI |
↳ spark_submit_task | object | Legacy spark-submit task |
↳ parameters | array | parameters output from the tool |
↳ python_wheel_task | object | python_wheel_task output from the tool |
↳ package_name | string | Python package name |
↳ entry_point | string | Package entry point |
↳ parameters | array | parameters output from the tool |
↳ named_parameters | object | Named wheel parameters |
↳ sql_task | object | sql_task output from the tool |
↳ warehouse_id | string | SQL warehouse identifier |
↳ parameters | object | SQL parameters |
↳ query | object | query output from the tool |
↳ query_id | string | Saved query identifier |
↳ file | object | file output from the tool |
↳ path | string | SQL file path |
↳ source | string | WORKSPACE or GIT |
↳ alert | object | alert output from the tool |
↳ alert_id | string | SQL alert identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ dashboard | object | dashboard output from the tool |
↳ dashboard_id | string | Legacy SQL dashboard identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ custom_subject | string | custom_subject output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ run_job_task | object | run_job_task output from the tool |
↳ job_id | number | Nested job identifier |
↳ job_parameters | object | Nested job parameters |
↳ pipeline_params | object | Pipeline refresh settings |
↳ pipeline_task | object | pipeline_task output from the tool |
↳ pipeline_id | string | Pipeline identifier |
↳ parameters | object | parameters output from the tool |
↳ full_refresh | boolean | full_refresh output from the tool |
↳ refresh_selection | array | refresh_selection output from the tool |
↳ full_refresh_selection | array | full_refresh_selection output from the tool |
↳ reset_checkpoint_selection | array | reset_checkpoint_selection output from the tool |
↳ refresh_flow_selection | array | refresh_flow_selection output from the tool |
↳ dbt_task | object | dbt_task output from the tool |
↳ commands | array | dbt commands |
↳ project_directory | string | project_directory output from the tool |
↳ profiles_directory | string | profiles_directory output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ catalog | string | catalog output from the tool |
↳ schema | string | schema output from the tool |
↳ source | string | WORKSPACE or GIT |
↳ condition_task | object | condition_task output from the tool |
↳ op | string | Comparison operator |
↳ left | string | Left operand |
↳ right | string | Right operand |
↳ outcome | string | Evaluation result: true or false |
↳ for_each_task | object | for_each_task output from the tool |
↳ inputs | string | JSON array or parameter reference to iterate over |
↳ concurrency | number | concurrency output from the tool |
↳ task | object | Nested task definition |
↳ clean_rooms_notebook_task | object | clean_rooms_notebook_task output from the tool |
↳ clean_room_name | string | clean_room_name output from the tool |
↳ notebook_name | string | notebook_name output from the tool |
↳ etag | string | etag output from the tool |
↳ notebook_base_parameters | object | notebook_base_parameters output from the tool |
↳ dashboard_task | object | dashboard_task output from the tool |
↳ dashboard_id | string | dashboard_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ subscription | object | subscription output from the tool |
↳ filters | object | filters output from the tool |
↳ alert_task | object | alert_task output from the tool |
↳ alert_id | string | alert_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ workspace_path | string | workspace_path output from the tool |
↳ subscribers | array | subscribers output from the tool |
↳ power_bi_task | object | power_bi_task output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ connection_resource_name | string | connection_resource_name output from the tool |
↳ refresh_after_update | boolean | refresh_after_update output from the tool |
↳ power_bi_model | object | power_bi_model output from the tool |
↳ tables | array | tables output from the tool |
↳ state | object | state output from the tool |
↳ life_cycle_state | string | life_cycle_state output from the tool |
↳ result_state | string | result_state output from the tool |
↳ state_message | string | state_message output from the tool |
↳ resolved_values | object | Resolved task parameters keyed by task type (notebook_task, spark_python_task, sql_task, and other task variants) |
↳ start_time | number | Task start in epoch milliseconds |
↳ end_time | number | Task end in epoch milliseconds |
↳ run_page_url | string | Task run URL |
↳ jobClusters | array | Shared job compute definitions |
↳ job_cluster_key | string | Cluster reference key |
↳ new_cluster | object | Cloud-dependent compute configuration |
↳ spark_version | string | spark_version output from the tool |
↳ node_type_id | string | node_type_id output from the tool |
↳ num_workers | number | num_workers output from the tool |
↳ autoscale | object | autoscale output from the tool |
↳ min_workers | number | min_workers output from the tool |
↳ max_workers | number | max_workers output from the tool |
↳ runStatus | object | Run lifecycle and termination or queue details |
↳ state | string | Current lifecycle state |
↳ termination_details | object | termination_details output from the tool |
↳ code | string | code output from the tool |
↳ type | string | type output from the tool |
↳ message | string | message output from the tool |
↳ queue_details | object | queue_details output from the tool |
↳ code | string | code output from the tool |
↳ message | string | message output from the tool |
↳ hasMore | boolean | Whether tasks or job clusters have additional pages |
↳ runPageUrl | string | Run details URL |
↳ 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 |
Get the status, timing, and details of a Databricks job run by its run ID.
| Parameter | Type | Required | Description |
|---|
pageToken | string | No | Token for the next page of tasks and job clusters |
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 |
|---|
tasks | array | Task definitions and task run IDs; nested keys use Databricks API names |
↳ task_key | string | Task key |
↳ run_id | number | Task run ID for Get Run Output |
↳ description | string | Task description |
↳ depends_on | array | depends_on output from the tool |
↳ task_key | string | Upstream task key |
↳ outcome | string | Required outcome of a condition task |
↳ existing_cluster_id | string | Existing compute cluster |
↳ job_cluster_key | string | Shared job cluster key |
↳ notebook_task | object | notebook_task output from the tool |
↳ notebook_path | string | Notebook path |
↳ source | string | WORKSPACE or GIT |
↳ base_parameters | object | Notebook parameter map |
↳ spark_python_task | object | spark_python_task output from the tool |
↳ python_file | string | Python file path or cloud URI |
↳ source | string | WORKSPACE or GIT |
↳ parameters | array | parameters output from the tool |
↳ spark_jar_task | object | spark_jar_task output from the tool |
↳ main_class_name | string | JAR entry point class |
↳ parameters | array | parameters output from the tool |
↳ jar_uri | string | Legacy JAR URI |
↳ spark_submit_task | object | Legacy spark-submit task |
↳ parameters | array | parameters output from the tool |
↳ python_wheel_task | object | python_wheel_task output from the tool |
↳ package_name | string | Python package name |
↳ entry_point | string | Package entry point |
↳ parameters | array | parameters output from the tool |
↳ named_parameters | object | Named wheel parameters |
↳ sql_task | object | sql_task output from the tool |
↳ warehouse_id | string | SQL warehouse identifier |
↳ parameters | object | SQL parameters |
↳ query | object | query output from the tool |
↳ query_id | string | Saved query identifier |
↳ file | object | file output from the tool |
↳ path | string | SQL file path |
↳ source | string | WORKSPACE or GIT |
↳ alert | object | alert output from the tool |
↳ alert_id | string | SQL alert identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ dashboard | object | dashboard output from the tool |
↳ dashboard_id | string | Legacy SQL dashboard identifier |
↳ subscriptions | array | subscriptions output from the tool |
↳ custom_subject | string | custom_subject output from the tool |
↳ pause_subscriptions | boolean | pause_subscriptions output from the tool |
↳ run_job_task | object | run_job_task output from the tool |
↳ job_id | number | Nested job identifier |
↳ job_parameters | object | Nested job parameters |
↳ pipeline_params | object | Pipeline refresh settings |
↳ pipeline_task | object | pipeline_task output from the tool |
↳ pipeline_id | string | Pipeline identifier |
↳ parameters | object | parameters output from the tool |
↳ full_refresh | boolean | full_refresh output from the tool |
↳ refresh_selection | array | refresh_selection output from the tool |
↳ full_refresh_selection | array | full_refresh_selection output from the tool |
↳ reset_checkpoint_selection | array | reset_checkpoint_selection output from the tool |
↳ refresh_flow_selection | array | refresh_flow_selection output from the tool |
↳ dbt_task | object | dbt_task output from the tool |
↳ commands | array | dbt commands |
↳ project_directory | string | project_directory output from the tool |
↳ profiles_directory | string | profiles_directory output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ catalog | string | catalog output from the tool |
↳ schema | string | schema output from the tool |
↳ source | string | WORKSPACE or GIT |
↳ condition_task | object | condition_task output from the tool |
↳ op | string | Comparison operator |
↳ left | string | Left operand |
↳ right | string | Right operand |
↳ outcome | string | Evaluation result: true or false |
↳ for_each_task | object | for_each_task output from the tool |
↳ inputs | string | JSON array or parameter reference to iterate over |
↳ concurrency | number | concurrency output from the tool |
↳ task | object | Nested task definition |
↳ clean_rooms_notebook_task | object | clean_rooms_notebook_task output from the tool |
↳ clean_room_name | string | clean_room_name output from the tool |
↳ notebook_name | string | notebook_name output from the tool |
↳ etag | string | etag output from the tool |
↳ notebook_base_parameters | object | notebook_base_parameters output from the tool |
↳ dashboard_task | object | dashboard_task output from the tool |
↳ dashboard_id | string | dashboard_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ subscription | object | subscription output from the tool |
↳ filters | object | filters output from the tool |
↳ alert_task | object | alert_task output from the tool |
↳ alert_id | string | alert_id output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ workspace_path | string | workspace_path output from the tool |
↳ subscribers | array | subscribers output from the tool |
↳ power_bi_task | object | power_bi_task output from the tool |
↳ warehouse_id | string | warehouse_id output from the tool |
↳ connection_resource_name | string | connection_resource_name output from the tool |
↳ refresh_after_update | boolean | refresh_after_update output from the tool |
↳ power_bi_model | object | power_bi_model output from the tool |
↳ tables | array | tables output from the tool |
↳ state | object | state output from the tool |
↳ life_cycle_state | string | life_cycle_state output from the tool |
↳ result_state | string | result_state output from the tool |
↳ state_message | string | state_message output from the tool |
↳ resolved_values | object | Resolved task parameters keyed by task type (notebook_task, spark_python_task, sql_task, and other task variants) |
↳ start_time | number | Task start in epoch milliseconds |
↳ end_time | number | Task end in epoch milliseconds |
↳ run_page_url | string | Task run URL |
jobClusters | array | Shared job compute definitions |
↳ job_cluster_key | string | Cluster reference key |
↳ new_cluster | object | Cloud-dependent compute configuration |
↳ spark_version | string | spark_version output from the tool |
↳ node_type_id | string | node_type_id output from the tool |
↳ num_workers | number | num_workers output from the tool |
↳ autoscale | object | autoscale output from the tool |
↳ min_workers | number | min_workers output from the tool |
↳ max_workers | number | max_workers output from the tool |
runStatus | object | Run lifecycle and termination or queue details |
↳ state | string | Current lifecycle state |
↳ termination_details | object | termination_details output from the tool |
↳ code | string | code output from the tool |
↳ type | string | type output from the tool |
↳ message | string | message output from the tool |
↳ queue_details | object | queue_details output from the tool |
↳ code | string | code output from the tool |
↳ message | string | message output from the tool |
repairHistory | array | Prior repairs; pass the latest id to Repair Run |
↳ id | number | id output from the tool |
↳ task_run_ids | array | task_run_ids output from the tool |
↳ status | object | Run lifecycle and termination or queue details |
↳ state | string | Current lifecycle state |
↳ termination_details | object | termination_details output from the tool |
↳ code | string | code output from the tool |
↳ type | string | type output from the tool |
↳ message | string | message output from the tool |
↳ queue_details | object | queue_details output from the tool |
↳ code | string | code output from the tool |
↳ message | string | message output from the tool |
jobParameters | array | Resolved job parameter values |
runDuration | number | Run duration including repairs in milliseconds |
nextPageToken | string | Token for the next page of tasks or job clusters |
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 |
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 |
|---|
info | string | Additional output information |
runJobOutput | object | Run Job task result |
↳ run_id | number | Child run identifier |
dbtOutput | object | dbt artifact download information |
↳ artifacts_link | string | Temporary artifact URL |
↳ artifacts_headers | object | Headers required to fetch the artifact |
sqlOutput | object | SQL query, alert, or dashboard task results |
↳ query_output | object | query_output output from the tool |
↳ alert_output | object | alert_output output from the tool |
↳ dashboard_output | object | dashboard_output output from the tool |
↳ widgets | array | widgets output from the tool |
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 |
Rerun failed or selected tasks within an existing Databricks run.
| 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 | Run identifier |
latestRepairId | number | No | Most recent repair ID; required after the first repair of a run |
rerunTasks | json | No | Task keys to repair; mutually exclusive with rerunAllFailedTasks |
jobParameters | json | No | Job-level parameter overrides as a JSON object of string keys and values |
rerunAllFailedTasks | boolean | No | Repair every failed task instead of specifying task keys |
rerunDependentTasks | boolean | No | Also rerun tasks downstream of the selected failed tasks |
performanceTarget | string | No | Serverless performance mode: STANDARD or PERFORMANCE_OPTIMIZED |
pipelineParams | json | No | Pipeline refresh settings, including full_refresh and selective table or flow lists |
| Parameter | Type | Description |
|---|
repairId | number | Identifier of the repair; pass it as latestRepairId on the next repair |
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 |
Request cancellation of active runs of a job or queued runs in 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 |
jobId | number | No | Job identifier; required unless allQueuedRuns is true |
allQueuedRuns | boolean | No | Cancel queued runs; without a job ID this applies to the workspace |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Delete a completed Databricks job run.
| 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 | Run identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
List a page of clusters in a Databricks workspace including their state, configuration, and resource details.
| Parameter | Type | Required | Description |
|---|
pageSize | number | No | Resources per page (default 20) |
pageToken | string | No | Token returned by the previous list request |
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
| Parameter | Type | Description |
|---|
nextPageToken | string | Token for the next page |
prevPageToken | string | Token for the previous page |
clusters | array | List of clusters in the workspace |
↳ policyId | string | Compute policy identifier |
↳ dataSecurityMode | string | Cluster access mode |
↳ terminatedTime | number | Cluster termination time in epoch milliseconds |
↳ customTags | object | Custom cluster tags |
↳ terminationReason | object | Reason for termination (code, type, parameters) |
↳ parameters | object | Provider-specific termination parameters |
↳ 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 |
↳ policyId | string | Compute policy identifier |
↳ dataSecurityMode | string | Cluster access mode |
↳ terminatedTime | number | Cluster termination time in epoch milliseconds |
↳ customTags | object | Custom cluster tags |
↳ terminationReason | object | Reason for termination (code, type, parameters) |
↳ parameters | object | Provider-specific termination parameters |
↳ 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) |
Create a compute cluster with runtime, sizing, policy, and cloud-specific settings.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
applyPolicyDefaultValues | boolean | No | Fill unspecified settings from the compute policy defaults |
cloneFrom | json | No | Clone source as {source_cluster_id, clone_source} |
numWorkers | number | No | Fixed worker count; use this or autoscale |
autoscale | json | No | Worker range as {min_workers, max_workers}; use this or numWorkers |
clusterName | string | No | Display name of the compute cluster |
sparkVersion | string | No | Databricks runtime version, or omit when supplied by a compute policy |
sparkConf | json | No | Spark configuration as a JSON map |
awsAttributes | json | No | AWS compute configuration such as availability, zone_id, and instance_profile_arn |
azureAttributes | json | No | Azure compute configuration such as availability and spot_bid_max_price |
gcpAttributes | json | No | GCP compute configuration such as availability and zone_id |
nodeTypeId | string | No | Worker node type identifier |
driverNodeTypeId | string | No | Driver node type identifier |
workerNodeTypeFlexibility | json | No | Alternative worker node type selection settings |
driverNodeTypeFlexibility | json | No | Alternative driver node type selection settings |
sshPublicKeys | json | No | SSH public keys to install on the cluster |
customTags | json | No | Custom cluster tags as a JSON map |
clusterLogConf | json | No | Cluster log destination in Databricks API format |
sparkEnvVars | json | No | Environment variables for the Spark processes as a JSON map |
autoterminationMinutes | number | No | Idle minutes before termination; 0 disables automatic termination |
enableElasticDisk | boolean | No | Allow automatic expansion of attached storage |
initScripts | json | No | Cluster initialization script locations in Databricks API format |
dockerImage | json | No | Custom container image URL and optional basic_auth settings |
instancePoolId | string | No | Worker instance pool identifier |
singleUserName | string | No | Assigned user or service principal for dedicated access mode |
policyId | string | No | Compute policy identifier |
enableLocalDiskEncryption | boolean | No | Encrypt local cluster storage |
driverInstancePoolId | string | No | Driver instance pool identifier |
workloadType | json | No | Permitted workload types in Databricks API format |
dataSecurityMode | string | No | Cluster access mode |
runtimeEngine | string | No | Runtime execution engine |
kind | string | No | Compute kind |
useMlRuntime | boolean | No | Use a machine learning runtime |
isSingleNode | boolean | No | Create a single-node compute resource |
remoteDiskThroughput | number | No | Remote disk throughput setting |
totalInitialRemoteDiskSize | number | No | Initial remote disk size setting |
dependencyMode | string | No | Cluster dependency mode |
| Parameter | Type | Description |
|---|
clusterId | string | Compute cluster identifier |
Replace a compute cluster configuration; a running cluster restarts to apply the changes.
| 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 | Compute cluster identifier |
applyPolicyDefaultValues | boolean | No | Fill unspecified settings from the compute policy defaults |
numWorkers | number | No | Fixed worker count; use this or autoscale |
autoscale | json | No | Worker range as {min_workers, max_workers}; use this or numWorkers |
clusterName | string | No | Display name of the compute cluster |
sparkVersion | string | No | Databricks runtime version, or omit when supplied by a compute policy |
sparkConf | json | No | Spark configuration as a JSON map |
awsAttributes | json | No | AWS compute configuration such as availability, zone_id, and instance_profile_arn |
azureAttributes | json | No | Azure compute configuration such as availability and spot_bid_max_price |
gcpAttributes | json | No | GCP compute configuration such as availability and zone_id |
nodeTypeId | string | No | Worker node type identifier |
driverNodeTypeId | string | No | Driver node type identifier |
workerNodeTypeFlexibility | json | No | Alternative worker node type selection settings |
driverNodeTypeFlexibility | json | No | Alternative driver node type selection settings |
sshPublicKeys | json | No | SSH public keys to install on the cluster |
customTags | json | No | Custom cluster tags as a JSON map |
clusterLogConf | json | No | Cluster log destination in Databricks API format |
sparkEnvVars | json | No | Environment variables for the Spark processes as a JSON map |
autoterminationMinutes | number | No | Idle minutes before termination; 0 disables automatic termination |
enableElasticDisk | boolean | No | Allow automatic expansion of attached storage |
initScripts | json | No | Cluster initialization script locations in Databricks API format |
dockerImage | json | No | Custom container image URL and optional basic_auth settings |
instancePoolId | string | No | Worker instance pool identifier |
singleUserName | string | No | Assigned user or service principal for dedicated access mode |
policyId | string | No | Compute policy identifier |
enableLocalDiskEncryption | boolean | No | Encrypt local cluster storage |
driverInstancePoolId | string | No | Driver instance pool identifier |
workloadType | json | No | Permitted workload types in Databricks API format |
dataSecurityMode | string | No | Cluster access mode |
runtimeEngine | string | No | Runtime execution engine |
kind | string | No | Compute kind |
useMlRuntime | boolean | No | Use a machine learning runtime |
isSingleNode | boolean | No | Create a single-node compute resource |
remoteDiskThroughput | number | No | Remote disk throughput setting |
totalInitialRemoteDiskSize | number | No | Initial remote disk size setting |
dependencyMode | string | No | Cluster dependency mode |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Start a terminated all-purpose compute cluster.
| 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 | Compute cluster identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Restart a running compute cluster.
| 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 | Compute cluster identifier |
restartUser | string | No | User requesting the cluster restart |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Change the fixed worker count or autoscaling range of a running cluster.
| 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 | Compute cluster identifier |
numWorkers | number | No | Fixed worker count; use this or autoscale |
autoscale | json | No | Worker range as {min_workers, max_workers}; use this or numWorkers |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Terminate a compute cluster while retaining its configuration for a later restart.
| 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 | Compute cluster identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Permanently delete a compute cluster and its configuration.
| 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 | Compute cluster identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
List a page of 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 |
|---|
pageSize | number | No | Resources per page (default 20) |
pageToken | string | No | Token returned by the previous list request |
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
| Parameter | Type | Description |
|---|
nextPageToken | string | Token for the next page |
warehouses | array | List of SQL warehouses in the workspace |
↳ jdbcUrl | string | JDBC connection string |
↳ odbcParams | object | ODBC connection settings |
↳ hostname | string | hostname output from the tool |
↳ path | string | path output from the tool |
↳ protocol | string | protocol output from the tool |
↳ port | number | port output from the tool |
↳ health | object | Warehouse health and failure reason |
↳ status | string | status output from the tool |
↳ failure_reason | object | failure_reason output from the tool |
↳ code | string | code output from the tool |
↳ type | string | type output from the tool |
↳ parameters | object | parameters output from the tool |
↳ tags | object | Warehouse tags |
↳ custom_tags | array | custom_tags output from the tool |
↳ key | string | key output from the tool |
↳ value | string | value output from the tool |
↳ enablePhoton | boolean | Whether Photon is enabled |
↳ spotInstancePolicy | string | Spot instance policy |
↳ channel | object | Warehouse release channel |
↳ name | string | name output from the tool |
↳ statementTimeout | number | Statement timeout in seconds |
↳ 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 |
Get the configuration, state, and scaling settings of a SQL warehouse.
| 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 | SQL warehouse identifier |
| Parameter | Type | Description |
|---|
warehouse | object | SQL warehouse configuration and state |
↳ jdbcUrl | string | JDBC connection string |
↳ odbcParams | object | ODBC connection settings |
↳ hostname | string | hostname output from the tool |
↳ path | string | path output from the tool |
↳ protocol | string | protocol output from the tool |
↳ port | number | port output from the tool |
↳ health | object | Warehouse health and failure reason |
↳ status | string | status output from the tool |
↳ failure_reason | object | failure_reason output from the tool |
↳ code | string | code output from the tool |
↳ type | string | type output from the tool |
↳ parameters | object | parameters output from the tool |
↳ tags | object | Warehouse tags |
↳ custom_tags | array | custom_tags output from the tool |
↳ key | string | key output from the tool |
↳ value | string | value output from the tool |
↳ enablePhoton | boolean | Whether Photon is enabled |
↳ spotInstancePolicy | string | Spot instance policy |
↳ channel | object | Warehouse release channel |
↳ name | string | name output from the tool |
↳ statementTimeout | number | Statement timeout in seconds |
↳ 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 |
Create a SQL warehouse with sizing, autoscaling, and serverless settings.
| Parameter | Type | Required | Description |
|---|
host | string | Yes | Databricks workspace host (e.g., dbc-abc123.cloud.databricks.com) |
apiKey | string | Yes | Databricks Personal Access Token |
name | string | No | Display name of the SQL warehouse |
clusterSize | string | No | SQL warehouse size, such as Small or Medium |
minNumClusters | number | No | Minimum number of SQL warehouse clusters |
maxNumClusters | number | No | Maximum number of SQL warehouse clusters |
autoStopMins | number | No | Idle minutes before stopping the warehouse; 0 disables automatic stopping |
creatorName | string | No | Warehouse creator name |
warehouseTags | json | No | Warehouse tags as {custom_tags: [{key, value}]} |
spotInstancePolicy | string | No | Cost or reliability preference for spot instances |
enablePhoton | boolean | No | Enable Photon for SQL warehouse compute |
channel | json | No | Warehouse release channel as {name: "CHANNEL_NAME_CURRENT"} |
enableServerlessCompute | boolean | No | Use serverless SQL warehouse compute |
warehouseType | string | No | Warehouse type; use PRO for serverless |
statementTimeout | number | No | Warehouse statement timeout in seconds |
| Parameter | Type | Description |
|---|
warehouseId | string | SQL warehouse identifier |
Update a SQL warehouse configuration.
| 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 | SQL warehouse identifier |
name | string | No | Display name of the SQL warehouse |
clusterSize | string | No | SQL warehouse size, such as Small or Medium |
minNumClusters | number | No | Minimum number of SQL warehouse clusters |
maxNumClusters | number | No | Maximum number of SQL warehouse clusters |
autoStopMins | number | No | Idle minutes before stopping the warehouse; 0 disables automatic stopping |
creatorName | string | No | Warehouse creator name |
warehouseTags | json | No | Warehouse tags as {custom_tags: [{key, value}]} |
spotInstancePolicy | string | No | Cost or reliability preference for spot instances |
enablePhoton | boolean | No | Enable Photon for SQL warehouse compute |
channel | json | No | Warehouse release channel as {name: "CHANNEL_NAME_CURRENT"} |
enableServerlessCompute | boolean | No | Use serverless SQL warehouse compute |
warehouseType | string | No | Warehouse type; use PRO for serverless |
statementTimeout | number | No | Warehouse statement timeout in seconds |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Start a stopped SQL warehouse.
| 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 | SQL warehouse identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Stop a running SQL warehouse.
| 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 | SQL warehouse identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
Delete a SQL warehouse.
| 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 | SQL warehouse identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
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 |
↳ etag | string | Space version for conditional updates |
↳ 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 |
|---|
etag | string | Space version for conditional updates |
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) |
Create a Genie space from its serialized configuration and a SQL warehouse.
| 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 | SQL warehouse identifier |
parentPath | string | No | Parent workspace folder for the Genie space |
serializedSpace | string | Yes | Serialized Genie configuration JSON, including data_sources, instructions, config, and benchmarks; get an example with Get Genie Space |
title | string | No | Genie space title |
description | string | No | Description of the Genie space |
| Parameter | Type | Description |
|---|
etag | string | Space version for conditional updates |
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 Genie configuration (data_sources, instructions, config, benchmarks) |
Update a Genie space, optionally protecting the change with its current ETag.
| 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 | Genie space identifier |
serializedSpace | string | No | Serialized Genie configuration JSON, including data_sources, instructions, config, and benchmarks; get an example with Get Genie Space |
title | string | No | Genie space title |
description | string | No | Description of the Genie space; an empty string clears the description |
warehouseId | string | No | SQL warehouse identifier |
etag | string | No | Version from Get Genie Space; prevents overwriting concurrent changes |
parentPath | string | No | Parent workspace folder for the Genie space |
| Parameter | Type | Description |
|---|
etag | string | Space version for conditional updates |
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 Genie configuration (data_sources, instructions, config, benchmarks) |
Move a Genie space to the trash.
| 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 | Genie space identifier |
| Parameter | Type | Description |
|---|
success | boolean | Whether Databricks accepted the request |
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 |
|---|
rowCount | number | Number of rows in this chunk |
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 |
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 |
totalChunks | number | Number of result chunks |
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
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 |
|---|
totalChunks | number | Number of result chunks |
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
rowCount | number | Number of rows in this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
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 |
|---|
totalChunks | number | Number of result chunks |
chunkIndex | number | Index of this result chunk |
rowOffset | number | Starting row offset of this chunk |
rowCount | number | Number of rows in this chunk |
nextChunkIndex | number | Next chunk to retrieve with Get Statement Chunk; null on the final chunk |
nextChunkInternalLink | string | Workspace-relative path to the next result chunk |
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 |
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 |
Cancel an in-flight Genie agent response using the response ID returned by the agent stream.
| 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 | Agent conversation identifier |
responseId | string | Yes | Response ID from the response.created stream event |
| 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 |