Insights

Query workspace data, explore schema metadata, and get health digests through the platform insights endpoints.

The Insights endpoints let you run read-only SQL queries against workspace data, discover available tables and functions, and retrieve workspace health digests. They back the ad-hoc data exploration experience in the Developer Console.

Insights sits alongside two other query surfaces: Workspace Data Queries are pre-registered, parameterized SQL templates that agents invoke as tools mid-conversation, and the MCP Server exposes SQL tools to external MCP clients. Use Insights when a human (or dashboard) needs to explore workspace data interactively rather than through a registered tool.

All Insights endpoints are read-only and workspace-scoped. Permissions: viewer+ (Data:View), except raw SQL execution, which requires the Data:Query permission (admin role and above).

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/insights/sql	Execute a read-only SQL query (Data:Query, admin+)
GET	/v1/{workspace_id}/insights/schema	List available tables, columns, and functions
GET	/v1/{workspace_id}/insights/digest	Get a cached workspace health digest
GET	/v1/{workspace_id}/insights/suggestions	Get contextual starter questions
POST	/v1/{workspace_id}/insights/sessions	Create an insights chat session
GET	/v1/{workspace_id}/insights/sessions/{session_id}	Get an insights chat session
POST	/v1/{workspace_id}/insights/sessions/{session_id}/chat	Chat with the insights agent (SSE stream)

Execute SQL Query

POST /v1/{workspace_id}/insights/sql

Runs a read-only SQL query against the workspace's analytics warehouse. Requires the Data:Query permission (admin role and above); the statement is additionally constrained to the workspace-scoped data surface.

Request Body

Field	Type	Required	Description
sql	string	Yes	SQL query to execute

Response

Field	Type	Description
results	array of objects	Query result rows (null if error)
count	integer	Number of rows returned
error	string	Error message if the query failed

List Schema

GET /v1/{workspace_id}/insights/schema

Returns the tables, columns, and functions available to SQL queries.

Response

Field	Type	Description
lakebase_tables	object	Workspace database tables: map of table name to column definitions (column name to type)
databricks_catalogs	array of strings	Analytics warehouse catalog names available for querying
uc_functions	array of objects	Registered warehouse functions, each with name and description
ai_functions	array of strings	Available AI function names

Get Health Digest

GET /v1/{workspace_id}/insights/digest

Returns a cached workspace health digest (refreshed periodically, so it may be slightly stale) with entity counts, data quality signals, and suggested questions.

Response

The response includes:

Field	Type	Description
highlights	array of objects	Key metrics, each with label and value
trend	object	Trend data with title and data (array of date/value points)
suggested_questions	array of strings	Recommended queries to explore further

Get Suggestions

GET /v1/{workspace_id}/insights/suggestions

Returns contextual starter questions for exploring workspace data.

Response

Field	Type	Description
suggestions	array of strings	Suggested questions for data exploration

Chat Sessions

The insights agent supports conversational data exploration through chat sessions.

• POST /v1/{workspace_id}/insights/sessions creates a session and returns its id (and created_at).
• POST /v1/{workspace_id}/insights/sessions/{session_id}/chat sends a user message (1-16,000 characters) and returns a Server-Sent Events stream of response blocks.
• GET /v1/{workspace_id}/insights/sessions/{session_id} returns the session history. If the session is not found or has expired, the response contains an empty messages array and an error field rather than a 404.

API Reference

• Insights