Ratings provide a comprehensive system for capturing and managing feedback across your conversational AI platform. Unlike simple upvote/downvote operations, ratings offer flexible numerical values and detailed reasoning that help you analyze performance patterns, identify improvement opportunities, and make data-driven optimization decisions.

The rating system enables you to track feedback at multiple levels: individual messages, entire conversations, specific bots, and even contact interactions. Each rating includes a numerical value for quantitative analysis and an optional reason field for capturing qualitative insights about what worked well or needs improvement.

Listing Ratings

Retrieve a paginated list of all ratings associated with your account, enabling comprehensive analysis of feedback patterns across your conversational AI implementations. The list operation supports advanced filtering to help you focus on specific aspects of your rating data.

GET /api/v1/rating/list
http

This endpoint returns all ratings you've created, ordered by creation date (most recent first by default). Each rating includes complete context about what was rated, including associated contact, bot, conversation, and message identifiers.

Filtering by Resource

Focus your analysis by filtering ratings for specific resources using query parameters. You can filter by contact, bot, conversation, or message to analyze feedback for particular interactions:

GET /api/v1/rating/list?botId=bot_abc123&value=-100
http

The filtering system supports multiple criteria simultaneously, allowing you to create precise queries like "all negative ratings for a specific bot" or "all ratings from a particular contact during a conversation." This flexibility enables targeted analysis of feedback patterns and helps identify specific areas requiring attention.

Pagination and Ordering

Manage large rating datasets efficiently using cursor-based pagination:

GET /api/v1/rating/list?take=50&cursor=rating_xyz789
http

The take parameter controls how many ratings to retrieve per request (useful for performance when dealing with thousands of ratings), while the cursor parameter enables efficient pagination through large result sets. Use the order parameter to control sort direction (asc or desc).

Metadata Filtering

Enhance your rating organization by using the metadata filtering system to tag and categorize ratings according to your specific needs. Metadata provides flexible key-value storage for custom attributes, enabling sophisticated analysis and reporting:

GET /api/v1/rating/list?meta[category]=technical&meta[severity]=high
http

Common metadata use cases include categorizing rating types (technical, usability, content quality), tracking rating sources (automated testing, user feedback, internal review), and associating ratings with specific feature areas or business metrics.

Warning: Rating data accumulates over time and can become substantial. Use filtering and pagination effectively to maintain query performance and avoid retrieving unnecessary data. Consider implementing date range filters through metadata when analyzing time-specific feedback patterns.

Exporting Ratings

Export your rating data in bulk for comprehensive analysis, reporting, or archival purposes. The export operation provides access to your complete rating history with the same powerful filtering capabilities available in the list operation, but optimized for large-scale data retrieval.

GET /api/v1/rating/export
http

Exports include all rating fields such as value, reason, timestamps, and associated resource identifiers (contact, bot, conversation, message). The operation returns data in a format suitable for import into spreadsheet applications, business intelligence tools, or custom analytics platforms.

Filtering Export Data

Apply the same filtering capabilities available in the list operation to control which ratings are included in your export. This enables targeted analysis such as exporting all negative ratings for a specific time period, all ratings for a particular bot, or ratings matching specific metadata criteria:

GET /api/v1/rating/export?botId=bot_abc123&meta[severity]=high
http

Common export scenarios include generating monthly feedback reports, analyzing rating trends over time, identifying patterns in negative feedback, comparing performance across different bots, and creating compliance or audit documentation.

Metadata in Exports

Metadata fields are included in exports and can be used for filtering, enabling rich categorization and analysis of exported data. Structure your metadata consistently to facilitate automated processing and reporting of exported rating data:

GET /api/v1/rating/export?meta[exported]=false
http

Consider using metadata flags like exported, processed, or reviewed to track which ratings have been included in previous exports or analysis cycles. This helps maintain data integrity and prevents duplicate processing in recurring export workflows.

Performance Note: Export operations may take longer than list operations when retrieving large volumes of rating data. For optimal performance, use filtering parameters to limit exports to specific time periods or resources rather than exporting entire rating histories unnecessarily.