# Usage

Usage endpoints provide essential metrics and statistics about your organization's resource consumption across all replicas. These endpoints help you monitor conversation volumes, knowledge base utilization, and track usage patterns for billing, capacity planning, and optimization purposes.

All usage endpoints return aggregated data at the organization level, providing both total counts and breakdowns by individual replicas to give you detailed insights into resource distribution.

## Overview

The usage API provides three main endpoints:

- **Combined Usage** (`/usage`) - Returns both conversation and knowledge base metrics in a single response
- **Conversation Usage** (`/usage/conversations`) - Returns detailed conversation metrics for the current month
- **Knowledge Base Usage** (`/usage/knowledgeBaseEntries`) - Returns knowledge base entry counts across all replicas

## Key Features

### Current Month Conversation Tracking
Conversations are counted based on chat history activity within the current calendar month. A conversation is only counted if it has at least one chat message in the current month, regardless of when the conversation was originally created.

### Knowledge Base Entry Filtering
Knowledge base entries are filtered to include only entries with `READY` status, excluding any processing, failed, or incomplete entries.

### Replica-Level Breakdown
All metrics include both organization totals and per-replica breakdowns, allowing you to understand usage distribution across your replicas.

## Authentication

All usage endpoints require organization-level authentication using service tokens. User-specific authentication is optional but recommended for audit trails.

## Response Format

All usage endpoints return a consistent response structure with:
- `success: true` - Indicates successful request
- Metric-specific data with totals and replica breakdowns
- Non-negative integer counts for all metrics

## Date Boundaries

Conversation metrics use precise calendar month boundaries:
- **Start of Month**: First day at 00:00:00.000
- **End of Month**: Last day at 23:59:59.999

All dates and times are in UTC.

Conversations spanning multiple months are counted in the month where they have chat activity.

## Data Isolation

Usage metrics are strictly isolated by organization. Each organization can only access its own usage data, ensuring complete data privacy and security.

## Error Handling

Usage endpoints return standard HTTP status codes:
- `200 OK` - Successful request with usage data
- `401 Unauthorized` - Invalid or missing authentication credentials
- `500 Internal Server Error` - Server-side processing errors

## Rate Limiting

Usage endpoints are subject to standard API rate limits. For high-frequency monitoring, consider caching responses and implementing appropriate polling intervals.

## Best Practices

### Monitoring Strategy
- Poll usage endpoints at reasonable intervals (e.g., hourly or daily)
- Cache responses to reduce API calls for dashboard displays

### Integration Patterns
- Combine with analytics endpoints for comprehensive insights
- Use in conjunction with replica management for capacity decisions
- Integrate with billing systems for automated usage tracking


## Operations
- [Get usage metrics](https://docs.sensay.io/operation/operation-get-v1-users-me-usage.md)

[Powered by Bump.sh](https://bump.sh)