Skip to main content

​
Usage Tracking

Monitor your API usage, track costs, and manage billing with the Account API.

​
Overview

Track three key metrics:

API Usage

Total API calls, documents processed, questions asked

Resource Usage

Storage used, rate limits, quotas

Billing & Costs

Current period costs, next invoice, breakdown

​
Get Usage Statistics

from cerevox import Account

account = Account(api_key="your-api-key")

# Get current usage
usage = account.get_usage()

print(f"API Calls: {usage.total_requests}")
print(f"Documents Processed: {usage.documents_processed}")
print(f"Questions Asked: {usage.questions_asked}")
print(f"Storage Used: {usage.storage_bytes / (1024**3):.2f} GB")
print(f"Rate Limit: {usage.rate_limit}")
Response fields:
  • total_requests: Total API calls in current period
  • documents_processed: Total documents processed
  • questions_asked: Total questions submitted to Hippo
  • storage_bytes: Total storage used in bytes
  • rate_limit: Maximum requests allowed per period
  • rate_limit_reset: When rate limit resets (timestamp)

​
Usage by Date Range

from datetime import datetime, timedelta

# Get usage for specific date range
start_date = datetime(2025, 1, 1)
end_date = datetime(2025, 1, 31)

usage = account.get_usage(
    start_date=start_date.isoformat(),
    end_date=end_date.isoformat()
)

print(f"January 2025 Usage:")
print(f"  API Calls: {usage.total_requests}")
print(f"  Documents: {usage.documents_processed}")
print(f"  Questions: {usage.questions_asked}")

​
Billing Information

# Get current billing period information
billing = account.get_billing_info()

print(f"Billing Period: {billing.period_start} to {billing.period_end}")
print(f"Total Cost: ${billing.total_cost:.2f}")
print(f"Currency: {billing.currency}")

# Cost breakdown
print("\nCost Breakdown:")
print(f"  Hippo: ${billing.breakdown.hippo_cost:.2f}")
print(f"  Lexa: ${billing.breakdown.lexa_cost:.2f}")
print(f"  Storage: ${billing.breakdown.storage_cost:.2f}")

print(f"\nNext Invoice: {billing.next_invoice_date}")
Response fields:
  • period_start: Billing period start date
  • period_end: Billing period end date
  • total_cost: Total cost for period
  • currency: Currency code (USD, EUR, etc.)
  • breakdown: Cost breakdown by service
  • next_invoice_date: When next invoice is generated

​
Monitor Rate Limits

# Check rate limit status
usage = account.get_usage()

# Calculate usage percentage
usage_percent = (usage.total_requests / usage.rate_limit) * 100

print(f"Rate Limit Status:")
print(f"  Used: {usage.total_requests:,} / {usage.rate_limit:,}")
print(f"  Percentage: {usage_percent:.1f}%")
print(f"  Resets: {usage.rate_limit_reset}")

# Alert if approaching limit
if usage_percent > 80:
    print("\n⚠️ WARNING: Approaching rate limit!")
    print("Consider upgrading plan or optimizing usage")
elif usage_percent > 90:
    print("\n🚨 CRITICAL: Nearly at rate limit!")
    print("Immediate action required")

​
Usage Monitoring Dashboard

from cerevox import Account
from datetime import datetime, timedelta
import pandas as pd

class UsageMonitor:
    def __init__(self, api_key):
        self.account = Account(api_key=api_key)

    def get_daily_summary(self):
        """Get usage summary for today"""
        usage = self.account.get_usage()

        return {
            'api_calls': usage.total_requests,
            'documents': usage.documents_processed,
            'questions': usage.questions_asked,
            'storage_gb': usage.storage_bytes / (1024**3),
            'rate_limit_used_pct': (usage.total_requests / usage.rate_limit) * 100
        }

    def get_weekly_trend(self):
        """Get usage trend for past 7 days"""
        end_date = datetime.now()
        start_date = end_date - timedelta(days=7)

        usage_data = []

        for i in range(7):
            day = start_date + timedelta(days=i)

            usage = self.account.get_usage(
                start_date=day.isoformat(),
                end_date=day.isoformat()
            )

            usage_data.append({
                'date': day.strftime('%Y-%m-%d'),
                'api_calls': usage.total_requests,
                'cost': usage.estimated_cost
            })

        return pd.DataFrame(usage_data)

    def check_alerts(self):
        """Check for usage alerts"""
        usage = self.account.get_usage()
        billing = self.account.get_billing_info()

        alerts = []

        # Rate limit check
        rate_limit_pct = (usage.total_requests / usage.rate_limit) * 100
        if rate_limit_pct > 80:
            alerts.append({
                'type': 'rate_limit',
                'severity': 'warning' if rate_limit_pct < 90 else 'critical',
                'message': f'Rate limit at {rate_limit_pct:.0f}%'
            })

        # Cost check (example threshold: $100)
        if billing.total_cost > 100:
            alerts.append({
                'type': 'cost',
                'severity': 'warning',
                'message': f'Monthly cost: ${billing.total_cost:.2f}'
            })

        return alerts

# Usage
monitor = UsageMonitor(api_key="your-api-key")

# Daily summary
summary = monitor.get_daily_summary()
print("Today's Usage:")
print(f"  API Calls: {summary['api_calls']:,}")
print(f"  Documents: {summary['documents']:,}")
print(f"  Questions: {summary['questions']:,}")

# Weekly trend
trend = monitor.get_weekly_trend()
print("\nWeekly Trend:")
print(trend)

# Alerts
alerts = monitor.check_alerts()
if alerts:
    print("\n🚨 Alerts:")
    for alert in alerts:
        print(f"  [{alert['severity'].upper()}] {alert['message']}")

​
Cost Analysis

​
Understand Cost Breakdown

billing = account.get_billing_info()

# Total cost
total = billing.total_cost

# Service breakdown
hippo_pct = (billing.breakdown.hippo_cost / total) * 100
lexa_pct = (billing.breakdown.lexa_cost / total) * 100
storage_pct = (billing.breakdown.storage_cost / total) * 100

print("Cost Breakdown:")
print(f"  Hippo (RAG):   ${billing.breakdown.hippo_cost:8.2f} ({hippo_pct:.1f}%)")
print(f"  Lexa (Parse):  ${billing.breakdown.lexa_cost:8.2f} ({lexa_pct:.1f}%)")
print(f"  Storage:       ${billing.breakdown.storage_cost:8.2f} ({storage_pct:.1f}%)")
print(f"  {'─' * 40}")
print(f"  Total:         ${total:8.2f}")

​
Calculate ROI from 80% Savings

# Traditional RAG cost (without Hippo)
questions_asked = usage.questions_asked
traditional_cost_per_question = 0.05  # $0.05 per query
traditional_total = questions_asked * traditional_cost_per_question

# Actual cost with Hippo
actual_hippo_cost = billing.breakdown.hippo_cost

# Savings
savings = traditional_total - actual_hippo_cost
savings_percent = (savings / traditional_total) * 100

print("Cost Comparison:")
print(f"  Traditional RAG:  ${traditional_total:8.2f}")
print(f"  With Hippo:       ${actual_hippo_cost:8.2f}")
print(f"  {'─' * 40}")
print(f"  Savings:          ${savings:8.2f} ({savings_percent:.0f}%)")

​
Usage Optimization

# ❌ Bad - Create new chat for every question
for question in questions:
    chat = hippo.create_chat(folder.id, "Q&A")
    answer = hippo.submit_ask(chat.id, question)
    hippo.delete_chat(chat.id)

# ✅ Good - Reuse chat for related questions
chat = hippo.create_chat(folder.id, "Q&A Session")
for question in questions:
    answer = hippo.submit_ask(chat.id, question)
Impact: Reduces overhead, maintains context
import asyncio
from cerevox import AsyncHippo

# ✅ Good - Concurrent upload
async with AsyncHippo() as hippo:
    tasks = [hippo.upload_file(folder.id, f) for f in files]
    await asyncio.gather(*tasks)
Impact: Faster, more efficient processing
# Delete old/unused folders
folders = hippo.get_folders()

for folder in folders:
    if folder.file_count == 0:
        hippo.delete_folder(folder.id)
Impact: Reduces storage costs
# ❌ Bad - Vague question
answer = hippo.submit_ask(chat.id, "Tell me about features")

# ✅ Good - Specific question
answer = hippo.submit_ask(
    chat.id,
    "What are the three main features of Product X?"
)
Impact: Better answers with less retrieval overhead

​
Set Up Usage Alerts

import schedule
import time
from cerevox import Account

account = Account()

def check_usage_alerts():
    """Check usage and send alerts"""
    usage = account.get_usage()

    # Rate limit alert
    usage_pct = (usage.total_requests / usage.rate_limit) * 100

    if usage_pct > 80:
        send_alert(
            title="Rate Limit Warning",
            message=f"Usage at {usage_pct:.0f}% of rate limit",
            severity="warning"
        )

    # Cost alert
    billing = account.get_billing_info()

    if billing.total_cost > 100:  # Threshold: $100
        send_alert(
            title="Cost Alert",
            message=f"Monthly cost: ${billing.total_cost:.2f}",
            severity="info"
        )

def send_alert(title, message, severity):
    """Send alert via email, Slack, etc."""
    print(f"[{severity.upper()}] {title}: {message}")
    # Implement your notification logic here
    # - Send email
    # - Post to Slack
    # - Log to monitoring system

# Schedule daily checks
schedule.every().day.at("09:00").do(check_usage_alerts)

# Run scheduler
while True:
    schedule.run_pending()
    time.sleep(60)

​
Export Usage Data

import csv
from datetime import datetime, timedelta

def export_usage_report(account, days=30):
    """Export usage data to CSV"""
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days)

    # Collect daily usage
    usage_data = []

    current_date = start_date
    while current_date <= end_date:
        usage = account.get_usage(
            start_date=current_date.isoformat(),
            end_date=current_date.isoformat()
        )

        usage_data.append({
            'date': current_date.strftime('%Y-%m-%d'),
            'api_calls': usage.total_requests,
            'documents': usage.documents_processed,
            'questions': usage.questions_asked,
            'cost': usage.estimated_cost
        })

        current_date += timedelta(days=1)

    # Write to CSV
    with open('usage_report.csv', 'w', newline='') as f:
        writer = csv.DictWriter(
            f,
            fieldnames=['date', 'api_calls', 'documents', 'questions', 'cost']
        )
        writer.writeheader()
        writer.writerows(usage_data)

    print(f"✅ Exported {len(usage_data)} days to usage_report.csv")

# Usage
export_usage_report(account, days=30)

​
Plan Limits

  • Free Plan
  • Pro Plan
  • Enterprise
Rate Limits:
  • 1,000 API calls/month
  • 100 documents/month
  • 500 questions/month
Storage:
  • 1 GB included
Features:
  • Hippo, Lexa, Account APIs
  • 1 user

​
Best Practices

Monitor usage daily to catch issues early:
  • Track rate limit usage
  • Monitor costs
  • Review usage trends
  • Set up automated alerts
Reduce costs without sacrificing quality:
  • Use async for batch operations
  • Reuse chats and folders
  • Clean up unused resources
  • Write specific questions
Forecast usage and costs:
  • Estimate monthly costs
  • Plan for growth
  • Upgrade plan proactively
  • Budget for peak periods

​
Next Steps

Authentication

Manage authentication and tokens

Account Overview

Back to Account API overview

Hippo Best Practices

Optimize RAG costs and quality
⌘I