> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Natural-language dashboards

> Turn a plain-language analytics question into safe, reviewable dashboard insights.

Natural-language dashboards let you describe an analytics view in everyday language. The platform translates the request into approved semantic metrics, shows a preview, and saves nothing until you confirm.

## Build a dashboard view

1. Open a custom dashboard.
2. Select **Build with AI**.
3. Describe the metrics, time range, comparison, and filters you need.
4. Select **Preview insights** and review every proposed card.
5. Select **Add insights** to save the plan.

For example:

> Show success rate and average duration for outbound calls in the last 30 days.

The manual **Add insight** editor remains available. Generated insights are regular dashboard widgets, so you can edit, resize, reorder, or remove them afterward.

## Supported analytics language

The built-in planner understands conversation volume, activity over time, success rate, average or total duration, assistant and campaign performance, outcome, status, direction, sentiment, and recent conversations. It supports 7, 14, 30, and 90-day ranges plus previous-period comparisons.

Provider costs and internal billing fields are intentionally unavailable. Customer-facing usage remains available through the platform's canonical minutes and credits surfaces.

Filters are limited to approved values for status, direction, sentiment, and success. If a request cannot be mapped safely, the preview returns a clear validation error instead of guessing.

## Safety model

<Note>
  The planner cannot run SQL or request arbitrary tables and fields. Both preview and save use the same versioned semantic metric catalog. The save operation revalidates the complete plan before any widget is written.
</Note>

Dashboard authorization and analytics remain scoped to the active workspace. An API key cannot use this feature to access another workspace, and the `custom_dashboards` plan entitlement still applies.

The deterministic planner works even when no separate language model is configured.

## Public API

Use `POST /dashboards/{id}/natural-language` to generate a non-writing preview. Send the returned plan unchanged to `PUT /dashboards/{id}/natural-language` to validate it again and save its widgets.

Both operations require `dashboards:write` or the legacy `calls:write` scope. See the API reference for the complete request and response schema.