# Reports

Build custom analyses across Foldspace's full event and metric library, beyond the preset widgets.

**Path:** Analytics → Reports

Reports let you build custom analyses using Foldspace's full event and metric library, far beyond the preset [Dashboard](/user-guides/analytics/dashboard/) widgets. Open it from the document icon in the Analytics sidebar.

## The report builder

Click **Create New** to open the report builder. It has three panels.

### Events or Metrics

Click **+ Select Metric or Event** to open the metric picker. You can add multiple metrics to a single report — each gets a letter label (A, B, C, and so on). The picker is organized into four top-level categories.

**Conversation Signals** (5 metrics) are high-level signals extracted from the conversation:

| Metric | What it tracks |
|---|---|
| **Agent Gap** | Conversations where the agent could not answer, split into Action Gap (missing action) and Knowledge Gap (missing information) |
| **Primary Language** | The detected language of the conversation |
| **Resolution Status** | Whether the conversation was Resolved, Unresolved, or Escalated |
| **User Intent** | The user's inferred goal or intent |
| **User Sentiment** | Emotional tone detected in user messages |

**Conversation Interactions** (8 metrics) are granular events that happen within conversations:

- *Action Execution* — **Action Called** (the agent invokes an action), **Action Registered** (an action is first registered with the system), and **Action Response Received** (the agent receives the response from an action call).
- *Conversation Lifecycle* — **Conversation Started** (a new conversation begins) and **Message Sent** (each individual message sent in a conversation).
- *User Feedback & Escalation* — **Agent Handoff** (the conversation is handed off to a human agent) and **Message Rated** (a user rates a message thumbs up or down).
- *UI Interactions* — **UI Element Rendered** (a UI element such as a widget, card, or button is rendered in the conversation).

**Application Event** (1 metric) covers custom events your product fires via the Foldspace SDK with [`foldspace.track()`](/reference/track-api/) — browse them first in [Event Explorer](/user-guides/analytics/events-metrics/). **Web Tracking** (5 metrics) covers standard web analytics events such as page views and clicks.

Once you select a metric, you can configure:

- **Conversation / Event** — whether to count unique conversations or total event occurrences.
- **Unique / Total** — whether to deduplicate (unique users or conversations) or count all instances.
- **Filter on this Metric** — add a metric-specific filter, for example only Action Called events where the action is `create_project`.

### Report filter and breakdown

**+ Add report-level filter** adds a filter that applies to *every* metric in the report — useful for scoping the whole report to a specific agent, user [segment](/user-guides/analytics/segments/), or date sub-range.

**Breakdown** adds a dimension that splits your metric into groups. Common breakdowns:

- **Gap** — splits Agent Gap into Action Gap vs Knowledge Gap.
- **Status** — splits Resolution Status into Resolved / Unresolved / Escalated.
- **Action key** — splits Action Called by which specific action was triggered.
- **Primary Language** — splits any metric by conversation language.

### Chart

The chart updates live as you configure metrics and breakdowns. Controls in the top-right set the **date range** (last 7 days, 30 days, custom range), the **granularity** (daily, weekly, monthly), and the **chart type** (line, stacked bar, and others). Below the chart, toggle between chart view and table view to see exact numbers by day alongside averages and totals.

## Example reports

- **Agent Gap analysis** — add the Agent Gap metric, break down by Gap. Shows Action Gap vs Knowledge Gap over time, telling you whether the agent is missing capabilities (actions needed) or information (knowledge needed).
- **Resolution Status trends** — add Resolution Status, break down by Status. Plots Unresolved, Resolved, and Escalated conversations separately. Use it to track whether your resolution rate is improving week over week.
- **Action breakdown** — add Action Called, break down by Action key. Renders as a stacked bar chart showing which actions are called most frequently each day. Helps identify which capabilities are most used and which might not be triggering. A zero-usage action may have a bug.
- **Intent breakdown** — add User Intent, break down by Intent. This is the core intent analytics view: it shows how many conversations fall into each intent category — Action Request, Information Request, Reported Issue — plotted as separate lines over time. Use it to understand what users are trying to do each day and to spot a shifting intent mix; a rising Reported Issue line signals a product problem.

## Save and share

Click **Save** to name the report and add it to the Reports list, where it is accessible to all team members. Click **Share** to copy a direct link.