Reports

Analytics reports provide comprehensive insights into your platform usage, including metrics on conversations, messages, ratings, contacts, and agent activities across customizable time periods.

Reports are powerful analytics tools that help you understand how your conversational AI applications are performing. They provide detailed metrics and insights across various aspects of your platform usage, from user engagement to bot performance.

Generating Reports

To generate a report, you need to make a POST request to the report endpoint with the specific report ID you want to retrieve. Each report has unique input requirements and generates structured output data tailored to the metric being analyzed.

Reports are identified by their unique report ID, which you can discover by listing all available reports. Each report processes your request based on the input parameters you provide and returns comprehensive analytics data including current values, historical comparisons, and time-series breakdowns where applicable.

Most reports accept a periodDays parameter that allows you to specify the time window for the analysis. This parameter defaults to 30 days if not provided, giving you flexibility to analyze trends over different time periods such as weekly (7 days), monthly (30 days), quarterly (90 days), or custom durations.

Understanding Report Output

Report responses typically include several key components that help you understand both current performance and trends over time. The value field represents the current metric for the specified period, while the change field shows the difference compared to the previous equivalent period, helping you identify growth or decline patterns.

Many reports also include a breakdown array that provides day-by-day data points within your specified period. This granular data enables you to create visualizations, identify patterns, and understand how metrics fluctuate over time rather than just seeing aggregate totals.

Report Categories

The platform offers several categories of reports to help you analyze different aspects of your conversational AI system:

Engagement Reports track user interactions including total conversations, active contacts, and message volumes. These metrics help you understand how users are engaging with your bots and whether engagement is growing over time.

Performance Reports provide insights into bot behavior, including bot response counts, agent actions taken, and average messages per conversation. These metrics help you optimize your bot's configuration and understand its operational efficiency.

Quality Reports focus on user satisfaction through rating metrics, including total ratings received and breakdowns of positive versus negative feedback. These reports are essential for understanding user sentiment and identifying areas for improvement.

Contact Reports help you track your user base growth and activity levels, showing both total unique contacts and active contacts within specified time periods.

Use Cases

Reports can be integrated into dashboards, automated monitoring systems, or business intelligence tools. For example, you might query engagement reports daily to monitor platform health, track quality reports to identify declining satisfaction scores, or analyze performance reports to optimize bot configurations.

By combining multiple reports, you can build a comprehensive understanding of your platform's performance and make data-driven decisions about improvements, scaling, and feature development.

Important: Report data is calculated in real-time based on your current database state, so metrics reflect the most up-to-date information available at the time of the request.

Reports are structured analytics queries that process your platform activity data and return structured metrics with period comparisons, breakdowns, and ranked lists. Each report is identified by a stable ID and accepts typed input parameters described below.

Generating Reports

Use the batch generate endpoint to run one or more reports in a single call. The request body is a map of report ID → input object. All reports in a single request execute in parallel.

Responses use the same map structure. Each key resolves either to the report data or to an error object if that specific report failed.

Common Input Parameters

Most reports accept a single periodDays field that sets the look-back window. The previous equivalent window is computed automatically and used to calculate the change field in the output.

Parameter	Type	Default	Description
`periodDays`	`integer`	`30`	Number of days to analyse

Bot-specific reports additionally require a botId string.

Common Output Fields

Field	Type	Description
`value`	`number`	Metric total for the current period
`change`	`number`	Difference versus the previous equivalent period
`period`	`string`	Human-readable label, e.g. `"last 30 days"`
`breakdown`	`array`	Optional day-by-day `{ date, total }` entries

Reports are powerful analytical tools that transform your platform's raw activity data into meaningful insights. Each report is designed to answer specific questions about your usage patterns, performance metrics, or resource consumption, helping you understand trends, optimize operations, and demonstrate value.

Generating Reports

The report generation endpoint allows you to request multiple reports in a single API call. Each report is identified by a unique report ID, and you provide the necessary input parameters for that specific report type. The system processes all requested reports in parallel and returns results for each.

To generate reports, send a POST request with an object where each key is a report ID (obtained from the platform/report/list endpoint) and each value contains the input parameters required by that specific report. The endpoint returns a similarly structured response with results or errors for each requested report.

The response contains an object with the same report IDs as keys. Each value is either the successfully generated report data or an error object indicating why that specific report failed to generate. This design allows partial success - you'll receive data for all reports that completed successfully, even if some failed.

Discovering Available Reports

Before generating reports, use the /api/v1/platform/report/list endpoint to discover which reports are available on the platform. Each report has a unique identifier (ID), a descriptive name, and documentation about what input parameters it requires and what data it returns.

Different reports may require different input parameters. Common parameters include time period specifications (like periodDays for the number of days to analyze), resource filters (like botId to analyze a specific bot), or analysis options (like granularity for data aggregation level).

Report Input Parameters

Each report type accepts specific input parameters that control what data is analyzed and how it's aggregated. While parameter requirements vary by report, common patterns include:

Time Periods: Most reports accept periodDays (number of days to analyze) or explicit startDate/endDate parameters
Resource Filters: Many reports allow filtering by specific resources like botId, datasetId, or integrationId
Aggregation Options: Some reports support different aggregation levels like hourly, daily, weekly, or monthly

Consult the report list endpoint's response to understand the specific input schema for each report type. Reports validate their inputs and return clear error messages if required parameters are missing or invalid.

Batch Report Generation

Requesting multiple reports in a single API call is more efficient than making separate requests. The endpoint processes reports in parallel, reducing overall latency and minimizing the number of API calls needed to gather comprehensive analytics.

When batching reports, consider grouping related reports that cover the same time period or analyze the same resources. This approach provides a cohesive view of your platform activity and ensures consistent data across different analytical dimensions.

Error Handling and Partial Success

The batch report generation endpoint uses a partial success model. If one report encounters an error (due to invalid parameters, insufficient data, or processing issues), other reports in the same request continue to execute independently. Each report in the response indicates either success (with data) or failure (with an error message).

This design ensures you can always retrieve available data, even if some specific reports can't be generated. Review each report's response to identify which succeeded and which require attention or parameter adjustments.

Report Processing Performance

Report generation involves analyzing platform activity data, which can take several seconds depending on the time period, data volume, and complexity of the analysis. Longer time periods and accounts with high activity will generally require more processing time.

For optimal performance:

Request only the reports you need rather than generating all available reports
Use appropriate time periods - shorter periods generate faster while still providing useful insights
Cache generated reports for reuse rather than regenerating the same analysis repeatedly
Schedule resource-intensive reports during off-peak hours if running them regularly

Best Practices

Validate Report IDs: Use the list endpoint to discover valid report IDs before attempting to generate reports
Understand Input Requirements: Review each report's input schema to ensure you provide all required parameters correctly
Monitor for Errors: Check response objects for error fields and handle failures gracefully in automated workflows
Regular Analysis: Generate reports on a consistent schedule to track trends and identify patterns over time
Store Historical Data: Archive report results for long-term trend analysis and compliance requirements

Important: Report data reflects platform activity as recorded in the analytics systems. There may be a brief delay (typically a few minutes) between events occurring and appearing in generated reports due to data processing pipelines.

Discovering Available Reports

Before generating a report, you need to know which reports are available on the platform. The list endpoint provides a complete catalog of all report types you can access, including their identifiers, names, and descriptions.

Each report in the registry has a unique identifier (ID) that you use when fetching the actual report data. The list endpoint returns metadata about each report without executing any analytics queries, making it a lightweight operation suitable for building user interfaces or documentation.

The response includes an array of report objects, each containing the report ID, a human-readable name, a description of what the report measures, and timestamp information indicating when the report type was created and last updated.

Use the id field from the list response when making requests to the fetch endpoint to generate specific reports. The descriptive information helps you understand what each report measures and choose the appropriate reports for your analytics needs.

This endpoint is particularly useful when building dynamic dashboards or administrative interfaces where users need to select from available report types. You can cache the list of reports since new report types are only added during platform updates.

Dataset Records Report

ID: cm7k3m5n8k000008jq7h9e5b1a

Returns the total number of records stored across one or more datasets, with a per-dataset breakdown. Useful for monitoring knowledge-base size and validating import pipelines.

Input

Parameter	Type	Description
`datasetIds`	`string[]`	IDs of datasets to include in the count

Output

Field	Type	Description
`totalRecords`	`number`	Aggregate record count
`breakdown`	`array`	Per-dataset `{ datasetId, records }` entries

Total Ratings Report

ID: clr3m5n8k000008jq7h9e5b1a

Counts all ratings (thumbs up + thumbs down) received within the period, with a signed change versus the previous period and a daily breakdown.

Input: periodDays

Output

Field	Type	Description
`value`	`number`	Total ratings
`change`	`number`	Change vs previous period
`thumbsUp`	`number`	Count of positive ratings
`thumbsDown`	`number`	Count of negative ratings
`breakdown`	`array`	Daily `{ date, total }` entries

Thumbs Up Report

ID: clr3m5n8k000108jq3c4d7f2b

Counts only positive ratings with period-over-period change.

Input: periodDays

Output: Standard metric fields (value, change, period).

Thumbs Down Report

ID: clr3m5n8k000208jq8e5f6g3c

Counts only negative ratings with period-over-period change.

Input: periodDays

Output: Standard metric fields (value, change, period).

Total Contacts Report

ID: clr3m5n8k000308jq1h7i8j4d

Returns the all-time count of unique contacts on the account. Does not accept a time window because the metric is cumulative.

Input: (none required)

Output

Field	Type	Description
`value`	`number`	Total unique contacts
`period`	`string`	Always `"all time"`

Active Contacts Report

ID: clr3m5n8k000408jq9i8j9k5e

Counts contacts that initiated at least one conversation within the period, with a daily breakdown and period-over-period change.

Input: periodDays