Usage Statistics

Listing Usage Records

Individual usage records capture granular token and resource consumption events throughout your application. Each record corresponds to a specific operation - such as a conversation completion, a task execution, or an ability invocation - and includes the type of usage, the count of units consumed, and links to the related platform resources.

Listing usage records gives you detailed, audit-level visibility into how your application consumes platform resources. Unlike the aggregate usage fetch endpoint, this endpoint returns individual event records that can be filtered, paginated, and correlated with specific conversations, bots, tasks, and other platform entities.

Pagination

Results are returned in pages using cursor-based pagination. Include the cursor value from a previous response to fetch the next page. Use the order parameter to control sort direction (asc or desc, defaulting to desc for most recent records first), and the take parameter to control page size.

Filtering by Resource

You can narrow results to usage records associated with a specific platform resource by providing one of the available filter parameters. This is particularly useful when auditing consumption for a particular bot, conversation, or task.

Supported filter fields include type, conversationId, messageId, taskId, contactId, blueprintId, botId, datasetId, skillsetId, and abilityId. Multiple filters can be combined to narrow results further.

Filtering by Metadata

Usage records can also be filtered using metadata key-value pairs attached at the time of recording. Use the meta query parameter with deep object syntax to match records by their metadata values.

Response Structure

Each record in the items array includes the usage type (a string identifying the operation category), a count representing the number of units consumed (such as token count), optional relation IDs linking the record to platform resources, custom meta data, and standard createdAt and updatedAt timestamps. A cursor field in the response envelope can be used to retrieve subsequent pages.

Note: Usage records are immutable. They are created automatically by the platform during API operations and cannot be modified or deleted via the API. Use this endpoint for monitoring and auditing purposes only.

Fetching Usage Time Series Data

Retrieve detailed time-series usage data spanning the last 90 days to analyze consumption trends, identify patterns, and track platform activity over time. Unlike the snapshot endpoint that provides current billing period totals, the series endpoint delivers daily data points enabling granular trend analysis, forecasting, and historical comparisons.

Time-series usage data is essential for understanding how your platform usage evolves. It reveals daily and weekly patterns, helps identify consumption spikes that might indicate viral growth or issues, supports accurate resource planning and capacity forecasting, enables comparison of usage across different time periods, and provides data for building custom usage dashboards and analytics visualizations.

Response Structure and Data Points

The endpoint returns three parallel time-series arrays covering the last 90 days, each containing daily aggregated totals. Every data point includes a Unix timestamp (in milliseconds) marking midnight UTC for that day, paired with the cumulative total for that metric on that specific day.

Token Series: Daily token consumption across all AI model interactions. Tokens represent the computational cost of language model operations including chat completions, content generation, embeddings, and other AI-powered features. Sharp increases in token usage indicate either growing user engagement or the deployment of more token-intensive features. Use this data to project future costs and optimize expensive operations.

Conversation Series: Number of new conversation instances created each day. Each conversation represents a distinct interaction session with bots or agents. This metric tracks user engagement frequency and provides insight into how many separate interactions occur daily. Conversation counts help measure user adoption, identify high-traffic periods, and assess the effectiveness of new features or marketing campaigns.

Message Series: Total messages exchanged daily across all conversations, including both user inputs and bot responses. Message volume relative to conversation count indicates interaction depth and engagement quality. High message-to-conversation ratios suggest users are having longer, more detailed exchanges, while low ratios might indicate quick, transactional interactions or potential user experience issues.

Analysis and Visualization Patterns

Trend Detection: Plot the time-series data to identify growth trajectories, seasonal patterns, or usage anomalies. Sustained upward trends indicate healthy growth, while sudden drops may signal technical issues or user experience problems requiring investigation.

Comparative Analysis: Compare usage across different periods to assess the impact of new features, marketing campaigns, or pricing changes. For example, compare the 30 days before and after launching a new bot to measure adoption and engagement impact.

Peak Period Identification: Identify days or periods with unusually high usage to understand when your infrastructure experiences peak load. This information guides capacity planning and helps schedule maintenance during low-usage periods.

Cost Forecasting: Use historical token consumption trends to project future costs and plan budgets. Linear regression or time-series forecasting models can predict upcoming usage based on historical patterns, enabling proactive resource allocation.

Dashboard Integration: Integrate time-series data into operational dashboards to provide real-time visibility into platform health and usage patterns. Consider building visualizations showing 7-day moving averages, week-over-week growth, or month-over-month comparisons.

Usage Pattern Examples

Daily Monitoring Workflow:

Weekly Trend Analysis:

Data Interpretation Guidelines

Normal Fluctuations: Daily usage naturally varies based on user activity patterns, weekday vs. weekend differences, and time zones. Week-over-week comparisons often provide more meaningful insights than day-to-day changes.

Seasonal Patterns: Many applications exhibit weekly or monthly patterns. Business-focused bots might see higher weekday usage, while consumer applications might peak on weekends. Identify your application's natural rhythms to distinguish normal patterns from anomalies.

Growth Assessment: Healthy growth typically shows consistent upward trends with manageable day-to-day variation. Exponential growth curves might indicate viral adoption but could also strain infrastructure and budgets.

Important Note: The series endpoint returns up to 90 days of historical data. For longer retention periods or more granular (hourly) data, consider implementing your own logging and storage solution that captures usage metrics in real-time as they occur.