# Conversational Analytics

Read what users ask your agent, whether it resolved, what it could not do, and what it cost.

Conversational Analytics is generally available. It reads the conversations users have with your [Product Agent](/start/install/) and turns them into intent, resolution, gap, sentiment, and cost signals. Every conversation and tracked event flows in automatically once the agent is embedded, so there is nothing to configure beyond the agent itself.

Select **Analytics** from the top-left app switcher.

:::note
Conversational Analytics is included in every plan. It requires the Product Agent to be embedded in your product, because it analyzes the conversations users have with the agent.
:::

## What users are trying to do

**Path:** Analytics → Dashboard → Conversations

[User Intent](/user-guides/analytics/user-intent/) classifies every conversation into what the user was trying to do:

| Intent | What it means |
| :--- | :--- |
| **Information Request** | The user is asking for information. |
| **Action Request** | The user wants the agent to do something. |
| **Reported Issue** | The user is reporting a problem. |

A rising **Action Request** share means users increasingly want the agent to act rather than answer, which raises the value of closing action gaps. A rising **Reported Issue** share is usually a product problem worth investigating, not an agent one.

:::note
Intents can overlap, so one conversation may carry several. The shares do not sum to 100%.
:::

For a full time series, open [Reports](/user-guides/analytics/reports/), add **User Intent**, and break it down by intent.

## What the agent could not deliver

When the agent cannot deliver, the conversation is tagged, and the two gap tags are the actionable ones:

- **Agent Action Gap**: users want a capability that does not exist yet.
- **Agent Knowledge Gap**: the information was missing, stale, or never retrieved.

One is a build list. The other is a writing list. Both are ranked in aggregate on [Signals frequency](/user-guides/analytics/signals-frequency/), and both are filters in [Conversations](/user-guides/conversations/) so you can read the underlying requests.

In [Reports](/user-guides/analytics/reports/), add the **Agent Gap** metric and break it down by **Gap** to see Action Gap against Knowledge Gap over time.

:::tip
Before building an action for a rising Action Gap, check whether the action already exists and the agent simply is not calling it. That is an instruction fix, not a build.
:::

## Whether the agent delivered

**Path:** Analytics → Dashboard → Conversations

- [Conversation metrics](/user-guides/analytics/conversation-metrics/) cover volume, **Resolution Rate**, and **Conversation Handoffs**.
- [Resolution Status](/user-guides/analytics/reports/) splits into Resolved, Unresolved, and Escalated when broken down by **Status** in Reports.
- [User sentiment](/user-guides/analytics/sentiment/) surfaces the conversations that turned negative.

Read the volume numbers as a set rather than in isolation. Conversations rising is ambiguous on its own, because retries after a failure also raise the count. Messages rising faster than conversations means users are working harder for the same result, which usually points to a knowledge problem rather than a capability one. Action calls rising alongside steady engagement is the healthiest pattern on the dashboard.

:::tip
On a rated reply, read the message *before* it. The rating lands on the reply, but the cause is usually the turn before.
:::

## Actions by type, frequency, and cost

**Path:** Analytics → Event Explorer

[Event Explorer](/user-guides/analytics/event-explorer/) is the catalog of every event and metric flowing into Foldspace, spanning product usage, conversational activity, and AI cost and token consumption. Because all three live in one place, you can see your key actions by **type**, **frequency**, and **cost** without leaving the surface.

Every metric is assembled the same way:

1. Pick an **event or metric**, for example **Action Called**, which fires every time the agent performs a distinct task.
2. Choose how to **count** it: unique conversations or users, or an **aggregate** (Sum or Average) of a numeric property.
3. **Filter** and **break down** by any property.
4. Chart it, or save it as a [Report](/user-guides/analytics/reports/) or a [Dashboard](/user-guides/analytics/dashboard/) widget.

Applied to actions, that gives you three readings of the same event:

| Question | How to build it |
| :--- | :--- |
| **Which actions run** (type) | **Action Called**, broken down by **Action key**. |
| **How often** (frequency) | **Action Called**, counted as Total Events, as a stacked bar over 7 or 30 days. |
| **What they cost** | **Action Called**, aggregated as **Sum of Estimated cost**, broken down by **Action key**. |

The most-called action and the most-expensive action are often not the same one, and the gap between those two rankings is usually where the optimization is.

- A **zero-usage** action may have a bug, or the agent may not know when to call it.
- A **low-usage** action may need better instructions.
- **Action Response Received** confirms the action actually returned.

## Cost and tokens <Badge text="Beta" variant="caution" />

**Path:** Analytics → Event Explorer

:::note
The cost and tokens report is currently in beta. [Token Quotas](/user-guides/quotas/) and [High Availability](/user-guides/high-availability/) are generally available.
:::

[Cost and tokens](/user-guides/analytics/cost-tokens/) metrics work by aggregating the numeric properties on an event rather than counting occurrences. Select **Action Called**, open the counting dropdown, choose **Aggregate Property**, pick the property, and select **Sum** for the total or **Average** for the per-event figure.

You can aggregate **Estimated cost**, **Action call estimated cost**, **Input tokens**, **Output tokens**, **Cached tokens**, **Thoughts tokens**, **Total tokens**, and **Action instructions tokens**.

Break the total down by **Action key** to find the action driving spend, or by **AI provider LLM model name** or **LLM provider** to compare models and providers. Set chart type to **Stacked Bar** over 7D or 30D: each bar is that day's total, and a large colored segment flags the driver.

:::tip
If one action is too expensive, optimize its prompt tokens or cache its results, then aggregate **Cached tokens** to confirm caching is working.
:::

## Controlling and protecting spend

[Token Quotas](/user-guides/quotas/) cap what agents and users consume, with agent-global, monthly user, daily user, per-conversation, and burst limits configured per agent. Quotas count weighted tokens rather than raw messages, and the daily and monthly windows roll continuously instead of resetting on a shared date, so access returns gradually rather than in a spike.

[High Availability](/user-guides/high-availability/) is the uptime half of model routing. If a provider throttles or goes down, Foldspace fails over to the next healthy model and key automatically, usually without the user noticing. Unavailability applies to a single model, key, and region combination and never to a whole provider. Every failover and failback is recorded as a routing event in [Event Explorer](/user-guides/analytics/event-explorer/).

**Path:** Settings → AI Gateway

## Reading the conversations behind the numbers

[Session replay](/user-guides/analytics/session-replay/) shows exactly what the user did on screen, with conversation events overlaid as a timeline. Reach for it when the transcript alone does not explain the outcome: an escalation, a thumbs-down with no obvious cause, or a strongly positive conversation on a valuable task.

In [Conversations](/user-guides/conversations/) you can filter by tag, including **Agent Action Gap** and **Agent Knowledge Gap**, and read the requests themselves. You can also ask the built-in Foldspace agent there, for example *"What are the action gaps in the last 30 days?"* or *"What topics get the most thumbs down?"*, then apply the matching filter and read the conversations yourself.

## Who is using the agent

- [Audience](/user-guides/analytics/audiences/) lists every identified user, with last seen, sign-up, subscription, role, and device. Open a row for that user's conversation history, replays, and attribute timeline.
- [Segments](/user-guides/analytics/segments/) define named groups by attribute or behavior. Once saved, a segment becomes a filter across Dashboard widgets, Audience, and Reports.
- [Product analytics](/user-guides/analytics/product-analytics/) covers new and active users, subscriptions, and retention, built from what the SDK captures.

Call `foldspace.identify()` to see named users and segments rather than anonymous sessions.

## Get started

1. **Open the Dashboard.** The default widgets already track conversations, resolution, handoffs, sentiment, action calls, languages, and signal frequency.
2. **Read the quantitative layer first.** Conversations, User Messages, and Action Calls, as a set.
3. **Build the Agent Gap report.** Add **Agent Gap**, break down by **Gap**.
4. **Build the intent breakdown.** Add **User Intent**, break down by intent.
5. **Check actions in Event Explorer.** Break **Action Called** down by **Action key** for frequency, then aggregate **Sum of Estimated cost** on the same event for spend.
6. **Watch a few escalated replays.** Filter [Session replay](/user-guides/analytics/session-replay/) to sessions with a handoff.
7. **Re-check next period.** If a gap's share dropped, the fix worked. If it held steady, read the new ones.

:::note
All dates, times, and daily buckets in Analytics use your account **Time Zone**, set in [Subscription settings](/user-guides/settings/subscription-settings/).
:::

## Related

- [Analyzing conversations](/user-guides/analytics/analyzing-conversations/): the full best-practice workflow behind this release.
- [Event Explorer](/user-guides/analytics/event-explorer/) and [Reports](/user-guides/analytics/reports/): where these metrics are built.
- [Cost and tokens](/user-guides/analytics/cost-tokens/) and [Token Quotas](/user-guides/quotas/): what the agent spends, and how to cap it.
- [Knowledge base](/user-guides/knowledge-base/) and [Authoring actions](/user-guides/authoring-actions/): where the fixes get made.