> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/govern/ai-control-and-optimization/certified-answers.md).

# Certified Answers

{% hint style="info" %}
**Target Audience**: Makers who build and manage embedded analytics for their end users. {% endhint %}
{% endhint %}

#### TL;DR

Certified Answers surfaces recurring questions your embedded users (Explorers) ask the AI assistant, groups them into patterns, and lets you turn the most common ones into official, reusable charts, reducing repetitive AI usage and delivering consistent answers at scale.

***

#### What is Certified Answers?

When Explorers interact with the embedded AI assistant, they ask business questions: "Show me revenue by region", "What is the churn rate this quarter?", and so on. Many of these questions recur across users and conversations, yet today every occurrence triggers a fresh AI response — different wording, different chart type, different numbers depending on context.

**Certified Answers** gives Makers visibility into those recurring intents and a direct path to promote validated answers into governed dashboard content.

It works in two steps:

1. **Distil** — For each embed conversation in the last 30 days, an AI call reads the full exchange and extracts the distinct underlying business questions (called *intents*). Refinement chains ("show revenue" → "split by region" → "only EMEA") are collapsed into a single intent.
2. **Cluster** — A second AI call groups similar intents across all conversations and organizations into *patterns* (called *Certified Answers* in the UI). Each pattern gets a title, a short description, and a pre-written chart request you can use directly.

A pattern is only shown when **at least 2 intents** match — a single occurrence is noise, not a signal.

***

#### Conditions for Certified Answers to work

For patterns to appear, several conditions must be met:

| Condition                                                     | Why it matters                                                                                                                                                                                                                    |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Your plan includes AI credits**                             | Both the distillation and clustering steps consume AI credits. The analysis will not run if your organization has no credits available.                                                                                           |
| **Embed users have had AI conversations in the last 30 days** | Only conversations from users authenticated with an **embed token** (user IDs starting with `embed-`) are included in the analysis. Platform conversations (Maker and Admin sessions on the Toucan platform itself) are excluded. |
| **Explorers asked real data questions**                       | If a conversation contains only greetings or small talk, no intents are extracted from it.                                                                                                                                        |
| **At least 2 similar intents exist across conversations**     | A single occurrence does not form a pattern. You need at least two Explorers (or the same Explorer in two separate conversations) to ask a similar question before it surfaces as a Certified Answer.                             |
| **You have the Maker role (or equivalent AI permission)**     | The Certified Answers page is only visible to users with the `ai: query` permission. Admins and Makers typically have this permission; Explorers do not.                                                                          |

***

#### How to access Certified Answers

1. Open the Toucan platform and go to **Certified Answers** in the left sidebar (under the AI section).
2. If no analysis has been run yet, you will see an empty state with an **Analyze patterns** button.

***

#### How to run an analysis

1. Click **Analyze patterns**.
2. Confirm the dialog — the analysis covers the last 30 days and uses AI credits.
3. Wait a few minutes while the job runs. The UI polls automatically and refreshes when results are ready (up to 2 minutes timeout).
4. Detected patterns appear as cards in the grid.

The **Last analyzed** timestamp at the top of the page shows when the most recent analysis completed. You can re-run the analysis at any time to incorporate newer conversations; patterns with charts already created are preserved.

***

#### Understanding the results

Each detected pattern card shows:

* **Title** — a concise name for the recurring question cluster.
* **Description** — a short summary of the underlying business need.
* **Status badge** — *Detected* (no chart yet) or *Chart created* (a chart has been promoted from this pattern).
* **Explorers** — number of distinct embed users whose conversations contributed to this pattern.
* **Intents** — total number of individual intents matched to this pattern.
* **Last activity** — when the most recent intent in this cluster was recorded.

Click a card to open the detail panel. It shows the canonical intent phrasings that were grouped into this pattern, the conversation source (embedded chat, self-service dashboard, etc.), and the date each intent was recorded.

***

#### Filters

Use the tabs above the grid to filter patterns:

| Tab               | Shows                                       |
| ----------------- | ------------------------------------------- |
| **All**           | Every detected pattern                      |
| **Detected**      | Patterns with no chart yet                  |
| **Chart created** | Patterns that have been promoted to a chart |

***

#### Turning a pattern into a chart

1. Open a pattern's detail panel.
2. Click **Create a chart** in the panel footer.
3. A modal appears with the chart request pre-filled from the pattern's suggested prompt — review and edit it as needed.
4. Choose the destination dashboard.
5. Click **Generate** to open the chart editor with the AI request pre-filled. The AI does not generate the chart automatically; you send the request manually, review the result, and save.

Once a chart is saved, the pattern is marked **Chart created** and linked to the dashboard. Its title and description are frozen — re-running the analysis will update its stats but not overwrite the label you validated.

***

#### AI credit usage

Each **Analyze patterns** run consumes credits for:

* One distillation call per conversation that has changed since the last analysis.
* One clustering call covering all in-window intents.

Credit consumption is visible in **AI Usage** (Settings → AI Usage). Conversations that were already distilled in a previous run are not re-distilled unless they have received new messages (watermark gate).

***

#### Limitations (v1)

* **Embed-only signal**: Only conversations from embedded Explorers are included. Maker or Admin conversations on the Toucan platform are not analyzed.
* **Manual trigger**: Analysis must be launched manually. There is no automatic schedule in v1.
* **30-day window**: Only conversations active in the last 30 days are included per run.
* **Minimum 2 intents**: Singleton questions do not appear as patterns.
* **Pattern ≠ live answer**: Certified Answers surface recurring needs; they do not automatically intercept future Explorer questions and return the chart. That closed-loop capability is planned for a later phase.