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

# Reports & Insights

> Create data-driven reports and track key metrics with customizable insights for your AI conversations

## Overview

Reports and Insights in Oration AI provide a powerful analytics framework for tracking, measuring, and understanding your AI conversation performance. Build comprehensive reports from pre-built templates or from scratch, customize visual insights with various chart types, and share findings with your team to make data-driven decisions.

<CardGroup cols="2">
  <Card title="Pre-built templates" icon="template">
    Jump-start your analytics with professionally designed report templates for common use cases
  </Card>

  <Card title="Custom insights" icon="chart-line">
    Create tailored visualizations to track the metrics that matter most to your business
  </Card>

  <Card title="Real-time data" icon="bolt">
    Access up-to-date metrics and trends as your AI agents interact with customers
  </Card>

  <Card title="Team collaboration" icon="users">
    Share reports and insights across your workspace for aligned decision-making
  </Card>
</CardGroup>

## Understanding Reports vs Insights

### Reports

Reports are organized collections of insights that tell a complete story about your AI performance. Think of reports as dashboards that bring together multiple data visualizations and metrics into a cohesive view.

**Key characteristics:**

* Container for multiple insights
* Can be created from templates or blank
* Shareable with team members
* Can be favorited for quick access
* Include metadata like creator, description, and creation date

### Insights

Insights are individual data visualizations that track specific metrics. Each insight focuses on a single measurement or trend, visualized through charts, graphs, or tables.

**Key characteristics:**

* Individual metric or KPI visualization
* Customizable chart types (line, bar, area, pie, etc.)
* Configurable time granularity (hourly, daily, weekly, monthly)
* Can be added to multiple reports
* Real-time data updates

## Quick start

### Create your first report

1. Navigate to **Reports** from the side navigation
2. Click **New Report** in the top-right corner
3. Select a template or choose **Blank Report** for custom creation
4. Configure report details (name, description)
5. Add insights to populate your report
6. Save and share with your team

### Create your first insight

1. Navigate to **Reports** and switch to the **Insights** tab
2. Click **New Insight**
3. Select the metric you want to track
4. Choose your visualization type
5. Configure time range and granularity
6. Name your insight and save

## Report templates

Oration AI provides professionally designed templates to help you get started quickly. Each template is optimized for specific use cases and includes pre-configured insights.

### Available templates

| Template                      | Description                                              | Best for                                                 |
| ----------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
| **Campaigns Performance**     | Track campaign metrics, engagement rates, and ROI        | Marketing teams measuring campaign effectiveness         |
| **Conversations Performance** | Monitor conversation volume, duration, and outcomes      | Operations teams optimizing conversation quality         |
| **Agents Performance**        | Evaluate individual agent metrics and efficiency         | Team leads managing multiple AI agents                   |
| **Customer Analytics**        | Analyze customer behavior, satisfaction, and trends      | Customer success teams understanding user patterns       |
| **Revenue Reports**           | Track revenue metrics, conversions, and growth           | Finance and sales teams monitoring financial performance |
| **User Engagement**           | Monitor active users, session duration, and retention    | Product teams improving user experience                  |
| **Support Tickets**           | Manage support volume, resolution time, and satisfaction | Support teams optimizing response workflows              |
| **Product Performance**       | Evaluate feature usage and product adoption              | Product managers tracking feature success                |
| **Custom Dashboard**          | Build personalized views with selected insights          | Teams with specific reporting needs                      |

### Using templates

When creating a new report, selecting a template automatically:

* Configures relevant insights for that use case
* Sets appropriate time ranges and granularity
* Applies industry-standard visualization types
* Includes recommended metrics and KPIs

You can customize any template after creation by adding, removing, or modifying insights.

## Creating insights

Insights are the building blocks of your reports. Each insight tracks a specific metric and presents it visually.

### Insight configuration options

| Option                 | Description                      | Values                                          |
| ---------------------- | -------------------------------- | ----------------------------------------------- |
| **Name**               | Descriptive name for the insight | Text string (e.g., "Daily Conversation Count")  |
| **Metric**             | The data point being measured    | Conversations, Agents, Campaigns, Revenue, etc. |
| **Visualization Type** | Chart style for presenting data  | Line, Bar, Area, Pie, Donut, Table              |
| **Time Grain**         | Data aggregation interval        | Hourly, Daily, Weekly, Monthly                  |
| **Date Range**         | Period for data analysis         | Last 7 days, Last 30 days, Custom range         |
| **Filters**            | Criteria to narrow results       | Agent ID, Campaign ID, Customer segment, etc.   |

### Visualization types

Choose the visualization that best represents your data:

#### Line charts

**Best for:** Tracking trends over time, identifying patterns, showing continuous data

**Example use cases:**

* Daily conversation volume
* Weekly revenue trends
* Monthly user growth

#### Bar charts

**Best for:** Comparing discrete categories, showing rankings, displaying counts

**Example use cases:**

* Agent performance comparison
* Campaign engagement by channel
* Support ticket categories

#### Area charts

**Best for:** Showing cumulative totals, visualizing part-to-whole relationships over time

**Example use cases:**

* Cumulative revenue
* Stacked conversation outcomes
* Multi-agent volume distribution

#### Pie & Donut charts

**Best for:** Showing proportions, displaying percentage breakdowns

**Example use cases:**

* Conversation outcome distribution
* Customer segment breakdown
* Agent workload distribution

#### Tables

**Best for:** Detailed data inspection, precise values, sortable metrics

**Example use cases:**

* Top performing agents list
* Detailed campaign metrics
* Customer engagement scores

### Time granularity

Select the appropriate time grain based on your analysis needs:

* **Hourly:** For real-time monitoring and intraday patterns
* **Daily:** For day-to-day trends and week-over-week comparisons
* **Weekly:** For monthly trends and reducing daily noise
* **Monthly:** For long-term trends and year-over-year analysis

<Tip>
  Match your time grain to your data volume. Hourly granularity works well for high-volume operations, while monthly views are better for strategic planning.
</Tip>

## Building effective reports

### Report organization best practices

**1. Start with context**
Begin your report with high-level overview insights that set the stage. Include total volumes, success rates, and key trends.

**2. Follow the data flow**
Organize insights logically, moving from general metrics to specific details. For example:

* Overall conversation volume → Conversation outcomes → Individual agent performance

**3. Highlight anomalies**
Include insights that help identify unusual patterns or outliers requiring attention.

**4. End with actionable items**
Conclude reports with insights that inform specific decisions or next steps.

### Example: Campaign Performance Report structure

```
1. Campaign Overview Insights
   - Total conversations initiated
   - Overall engagement rate
   - Campaign ROI

2. Engagement Metrics
   - Conversation completion rate
   - Average conversation duration
   - Time-of-day engagement patterns

3. Outcome Analysis
   - Conversion rates by campaign
   - Drop-off points analysis
   - Customer feedback scores

4. Agent Performance
   - Individual agent metrics
   - Response time distribution
   - Quality scores

5. Recommendations
   - Top performing campaigns
   - Optimization opportunities
   - Resource allocation insights
```

## Managing reports

### Favorite reports

Mark frequently accessed reports as favorites for quick access:

1. Navigate to your report
2. Click the star icon in the report header
3. Access favorited reports from the **Favorite Reports** section

Favorite reports appear at the top of your reports list and in your dashboard for convenient monitoring.

### Sharing reports

Reports can be shared with workspace members:

1. Open the report you want to share
2. Click the **Share** button
3. Select team members or set workspace-wide access
4. Notify recipients via email (optional)

Shared reports maintain real-time data, ensuring everyone sees current metrics.

### Report permissions

| Permission Level | Can View | Can Edit | Can Delete | Can Share |
| ---------------- | -------- | -------- | ---------- | --------- |
| **Owner**        | ✓        | ✓        | ✓          | ✓         |
| **Editor**       | ✓        | ✓        | ✗          | ✓         |
| **Viewer**       | ✓        | ✗        | ✗          | ✗         |

### Duplicating reports

Create variations of existing reports:

1. Open the source report
2. Click the **More options** menu (three dots)
3. Select **Duplicate**
4. Modify the duplicate as needed

This is useful for creating similar reports for different time periods, teams, or agents.

## Advanced features

### Combining insights from multiple sources

Build comprehensive reports by combining insights from different data sources:

* **Conversation data:** Volume, duration, outcomes
* **Agent performance:** Response times, quality scores
* **Campaign metrics:** Engagement, conversion rates
* **Customer data:** Satisfaction scores, retention rates
* **Revenue data:** Conversion value, lifetime value

### Custom time ranges

While preset ranges (Last 7 days, Last 30 days) work for most cases, custom ranges enable:

* **Specific campaign period analysis**
* **Quarter-over-quarter comparisons**
* **Event-driven reporting** (product launch, seasonal campaigns)
* **Historical baseline establishment**

To set a custom range:

1. Click the date selector in your insight configuration
2. Choose **Custom Range**
3. Select start and end dates
4. Apply to insight

### Filtering insights

Apply filters to focus insights on specific segments:

**Agent filters:**

```
agent_id = "asst_abc123"
agent_name contains "Support"
```

**Campaign filters:**

```
campaign_id = "camp_xyz789"
campaign_status = "active"
```

**Customer filters:**

```
customer_segment = "enterprise"
customer_region = "North America"
```

**Outcome filters:**

```
conversation_outcome = "successful"
call_duration > 300 (seconds)
```

## Best practices

### Performance optimization

**For faster report loading:**

* Limit insights per report to 10-15 for optimal performance
* Use appropriate time grains (avoid hourly for long date ranges)
* Apply filters to reduce data volume
* Cache frequently accessed reports by favoriting

### Data accuracy

**Ensure reliable insights:**

* Allow 5-10 minutes for real-time data processing
* Verify date ranges match your analysis period
* Cross-reference totals with raw conversation data
* Document any filters applied to insights

### Meaningful metrics

**Choose metrics that drive action:**

* Focus on leading indicators, not just lagging metrics
* Balance quantitative (numbers) with qualitative (satisfaction) data
* Align metrics with business objectives
* Review and update metrics quarterly

## Common use cases

### Executive dashboard

Create a high-level overview for leadership:

**Insights to include:**

* Total conversation volume (trend line)
* Overall success rate (big number + comparison)
* Revenue generated (bar chart by period)
* Customer satisfaction score (gauge chart)
* Top 5 performing agents (table)

**Time grain:** Daily or Weekly\
**Date range:** Last 30 days with previous period comparison

### Agent performance review

Track individual agent effectiveness:

**Insights to include:**

* Conversations handled per agent (bar chart)
* Average response time by agent (table)
* Conversation outcomes by agent (stacked bar)
* Customer feedback scores (line chart)
* Peak performance hours (heatmap)

**Time grain:** Daily\
**Date range:** Last 7 days

### Campaign ROI analysis

Measure campaign effectiveness:

**Insights to include:**

* Campaign reach and engagement (funnel chart)
* Conversion rates by campaign (bar chart)
* Cost per conversation (table)
* Revenue per campaign (pie chart)
* Time-to-conversion (line chart)

**Time grain:** Daily\
**Date range:** Campaign duration

## Troubleshooting

### Insight not showing data

**Possible causes and solutions:**

1. **Insufficient data in selected range**
   * Solution: Expand date range or check if agent has processed conversations

2. **Filters too restrictive**
   * Solution: Review and relax filter criteria

3. **Data processing delay**
   * Solution: Wait 5-10 minutes for real-time data to populate

4. **Metric not applicable to selected agents**
   * Solution: Verify agents support the metric being tracked

### Report performance issues

**If reports load slowly:**

1. Reduce number of insights (keep under 15)
2. Shorten date ranges for detailed time grains
3. Apply filters to limit data volume
4. Break large reports into focused sub-reports

### Data discrepancies

**If numbers don't match expectations:**

1. Verify time zones match your workspace settings
2. Check for duplicate insights with different filters
3. Confirm date ranges align correctly
4. Review data processing timestamps

## Keyboard shortcuts

Speed up your workflow with keyboard shortcuts:

| Action             | Shortcut               |
| ------------------ | ---------------------- |
| Create new report  | `Cmd/Ctrl + N`         |
| Create new insight | `Cmd/Ctrl + I`         |
| Search reports     | `Cmd/Ctrl + K`         |
| Toggle favorites   | `Cmd/Ctrl + D`         |
| Share report       | `Cmd/Ctrl + Shift + S` |
| Refresh data       | `Cmd/Ctrl + R`         |

## API access

Programmatically access report data via the Oration API:

```javascript theme={null}
// Fetch report data
const response = await fetch('https://api.oration.ai/v1/reports/{reportId}', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const reportData = await response.json();
```

See the [API Reference](/api-reference/reports) for complete documentation.

<Warning>
  Reports reflect data from conversations processed by your AI agents. Ensure agents are properly configured and active to collect meaningful metrics.
</Warning>

<Tip>
  Schedule regular report reviews with your team to identify trends, celebrate wins, and address areas for improvement. Data-driven decisions lead to better AI performance.
</Tip>

***

> Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai)