Reports

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.

POST /api/v1/report/{reportId}/fetch
Content-Type: application/json

{
  "userId": "your-user-id",
  "periodDays": 30
}

http

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.

{
  "value": 1250,
  "change": 180,
  "period": "last 30 days",
  "breakdown": [
    { "date": "2025-10-18", "total": 35 },
    { "date": "2025-10-19", "total": 42 },
    { "date": "2025-10-20", "total": 38 }
  ]
}

javascript

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.

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.

GET /api/v1/platform/report/list

http

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.

{
  "items": [
    {
      "id": "clr3m5n8k000008jq7h9e5b1a",
      "name": "Total Ratings Report",
      "description": "Comprehensive report on total number of ratings received",
      "createdAt": "2025-11-17T00:00:00.000Z",
      "updatedAt": "2025-11-17T00:00:00.000Z"
    },
    {
      "id": "clr3m5n8k000108jq3c4d7f2b",
      "name": "Thumbs Up Report",
      "description": "Report on positive ratings received",
      "createdAt": "2025-11-17T00:00:00.000Z",
      "updatedAt": "2025-11-17T00:00:00.000Z"
    }
  ]
}

javascript

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.

Go to cbk.ai