Getting Usage Statistics

This guide explains how to retrieve usage statistics for a user using Liona’s API. Usage stats are valuable for monitoring spending limits, displaying usage information in your UI, and proactively notifying users who are approaching their limits.

🚫

Important

This endpoint uses the user’s access key for authentication, not the admin API key. This means users can check their own usage stats without needing administrative privileges.

Understanding Usage Statistics

Liona tracks usage across three time periods:

Hourly - Usage within the current hour
Daily - Usage within the current day (24-hour period)
Monthly - Usage within the current month

For each period, the API returns:

The limit set in the user’s policy
Current usage amount
Usage as a percentage of the limit

API Endpoint

Field	Value
URL	`https://liona.ai/v1/client/user-stats`
Method	GET
Authentication	User Access Key (in Authorization header)

Request Parameters

This endpoint doesn’t require any parameters in the request body.

Response Structure

The API returns a JSON object containing:

Note

All decimal values are returned as strings in the JSON response to preserve precision. You’ll need to parse these strings into decimal/float values in your application.

Field	Type	Description
`hourly_limit`	decimal/string	The hourly spending limit defined in the user’s policy
`hourly_limit_used`	decimal/string	Current usage amount for the hour
`hourly_limit_used_pct`	decimal/string	Percentage of hourly limit used (0-100)
`daily_limit`	decimal/string	The daily spending limit defined in the user’s policy
`daily_limit_used`	decimal/string	Current usage amount for the day
`daily_limit_used_pct`	decimal/string	Percentage of daily limit used (0-100)
`monthly_limit`	decimal/string	The monthly spending limit defined in the user’s policy
`monthly_limit_used`	decimal/string	Current usage amount for the month
`monthly_limit_used_pct`	decimal/string	Percentage of monthly limit used (0-100)

Examples

cURL


curl -X GET https://liona.ai/v1/client/user-stats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer USER_ACCESS_KEY"

JavaScript


// Using fetch
async function getUserStats() {
  try {
    const response = await fetch('https://liona.ai/v1/client/user-stats', {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer USER_ACCESS_KEY'  // User's access key, not admin API key
      }
    });
 
    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }
 
    const data = await response.json();
    // Parse string values to numbers as needed
    const monthlyLimit = parseFloat(data.monthly_limit);
    const monthlyUsed = parseFloat(data.monthly_limit_used);
    const monthlyPct = parseFloat(data.monthly_limit_used_pct);
 
    console.log('Monthly limit:', monthlyLimit);
    console.log('Monthly usage:', monthlyUsed);
    console.log('Monthly usage percentage:', monthlyPct, '%');
 
    return data;
  } catch (error) {
    console.error('Failed to fetch user stats:', error);
  }
}

Python


import requests
 
def get_user_stats():
    url = "https://liona.ai/v1/client/user-stats"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer USER_ACCESS_KEY"  # User's access key, not admin API key
    }
 
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # Raise exception for 4XX/5XX status codes
 
        data = response.json()
        # Parse string values to float as needed
        monthly_limit = float(data['monthly_limit'])
        monthly_used = float(data['monthly_limit_used'])
        monthly_pct = float(data['monthly_limit_used_pct'])
 
        print(f"Monthly limit: {monthly_limit}")
        print(f"Monthly usage: {monthly_used}")
        print(f"Monthly usage percentage: {monthly_pct}%")
 
        return data
    except requests.exceptions.RequestException as e:
        print(f"Failed to fetch user stats: {e}")
        return None

How It Works

This endpoint performs the following operations:

Validates the provided user access key
Retrieves the user’s policy and its limits
Calculates the current usage for hourly, daily, and monthly periods
Computes usage percentages for each time period
Returns the compiled statistics

Common Use Cases

Proactively Warning Users About Usage

Alert users when they approach their spending limits:


async function checkUsageLimits() {
  const stats = await getUserStats();
 
  if (stats) {
    // Parse string to float
    const monthlyUsagePct = parseFloat(stats.monthly_limit_used_pct);
 
    // Warn at 80% usage
    if (monthlyUsagePct > 80) {
      showWarningBanner(`You've used ${monthlyUsagePct.toFixed(1)}% of your monthly limit.`);
    }
 
    // Critical warning at 95% usage
    if (monthlyUsagePct > 95) {
      showCriticalAlert("You're about to reach your monthly limit!");
    }
  }
}

Implementing Auto-Disable Features

Prevent further API calls when a user is close to their limit:


async function shouldAllowAiRequest() {
  const stats = await getUserStats();
 
  if (stats) {
    // Parse string to float
    const monthlyUsagePct = parseFloat(stats.monthly_limit_used_pct);
 
    if (monthlyUsagePct > 98) {
      // Disable AI features and show upgrade prompt
      showUpgradeModal("You've reached your monthly limit. Upgrade to continue using AI features.");
      return false;
    }
  }
 
  return true;
}

Error Handling

The API may return the following errors:

Status Code	Description
401	Unauthorized - Invalid or missing access key
500	Internal Server Error - Error retrieving usage statistics

Best Practices

Caching: For high-traffic applications, consider caching usage statistics for a short period (1-5 minutes) to avoid excessive API calls
Progressive Notifications: Implement tiered notifications at different thresholds (e.g., 50%, 75%, 90%, 95%)
Graceful Degradation: When users approach limits, consider offering reduced functionality rather than completely disabling features
Security: Keep user access keys secure, even though they have limited privileges compared to admin API keys

Next Steps

After implementing usage statistics in your application, you might want to:

Create more granular policies for different user types
Implement automatic policy upgrades for users who need higher limits
Set up request tracing for debugging and auditing