> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/safety/insights.md).

# Insights

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

Insights supports interactive, read-only exploration of workspace data. It sits alongside [Workspace Data Queries](/developer-guide/platform-api/functions/workspace-data-queries.md), which are registered agent tools, and the [MCP Server](/developer-guide/platform-api/functions/mcp-server.md), which exposes SQL tools to external MCP clients.

Insights operations require `viewer+` (`Data:View`) except raw SQL execution, which requires `Data:Query` at the admin tier or above.

## Execute SQL

Runs a read-only statement against the workspace-scoped analytics surface. In the customer-data catalog, a statement can read only the calling workspace's own two schemas, the workspace's schema and its `_dev` schema. A query against `information_schema` or another workspace's schema is rejected with an error naming the allowed schemas. The same rule applies to the MCP `sql_query` tool, the Insights Agent, dashboard panels, and trigger actions.

Tables outside the customer-data catalog, such as the call KPI view and the other analytics tables the [schema operation](#list-query-schema) lists, must each be filtered with `workspace_id = :ws_id` on their own alias, for example `c.workspace_id = :ws_id`. The platform binds `:ws_id` to the calling workspace, and a statement that leaves one unfiltered, such as a join that filters only one side, is rejected. A join's `ON` clause filters only the rows it limits, so an outer or anti join's `ON` doesn't filter the table whose rows the join keeps; filter that table in `WHERE`. A filter written without an alias counts only when its table is the only source its `SELECT` reads. Tables in the workspace's own two schemas need no filter.

Function calls are checked too. A call that reads past its arguments and the rows the statement reads, such as one that reads files, secrets, or other tables, or reports who is running the query, is rejected with an error that names the function. So are `IDENTIFIER()`, `TABLE()`, and calls to functions the platform doesn't offer; the error says what is callable.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/sql" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## List Query Schema

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/schema" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

`customer_data_tables` maps each of the workspace's customer-data tables and views, by the name to query it with, to its column types. Use it instead of `information_schema` to discover customer data.

The schema also lists the call KPI view, which gives the same call counts and rates as the [call KPI analytics](/developer-guide/platform-api/safety/analytics.md#call-kpis), and the per-call rows it summarizes. Read the view's measures with `MEASURE(<name>)`, grouped by its fields, for window totals and trends. The per-call rows include each call's `caller_id`, the number on the far end of the call: the caller on an inbound call and the callee on an outbound one.

## Get Health Digest

Returns a workspace health snapshot. Analytical values can lag recent workspace changes.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/digest" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Get Suggestions

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/suggestions" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Chat Sessions

### Create a Session

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/sessions" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get a Session

An unknown or expired session returns an empty message history with an error field rather than `404`.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/sessions/{session\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Chat

Chat returns a Server-Sent Events stream of response blocks.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/insights/sessions/{session\_id}/chat" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/safety/insights.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.