Skip to main content

Usage Analytics

Monitor your API usage in real-time with detailed analytics. Track token consumption, identify usage patterns, and optimize your integration.

Accessing Usage Analytics​

  1. Log in to Hindsight Cloud
  2. Open the Organization menu in the top navigation bar and select Usage

Dashboard Overview​

The Usage page provides comprehensive analytics with automatic refresh every 30 seconds.

Time Period Selection​

Choose from three time periods:

PeriodData ResolutionBest For
24 HoursHourly bucketsRecent activity, debugging
7 DaysDaily bucketsWeekly patterns
30 DaysDaily bucketsMonthly trends

Click the period buttons to switch views.

Summary Cards​

Seven cards display aggregate metrics for the selected period:

Total Tokens​

  • Combined usage across all operations
  • Displayed with an Activity icon

Retain Tokens​

  • Tokens consumed by memory storage operations
  • Blue color coding
  • Database icon

Recall Tokens​

  • Tokens consumed by memory retrieval operations
  • Green color coding
  • Search icon

Reflect Tokens​

  • Tokens consumed by AI insight operations
  • Purple color coding
  • Brain icon

Retrieve Model Tokens​

  • Tokens consumed by mental model GET operations (lightweight lookups)
  • Teal color coding

Refresh Model Tokens​

  • Tokens consumed by mental model create/refresh operations
  • Orange color coding

File Conversion (Iris) Tokens​

  • Tokens consumed by Enhanced (Iris) file extraction
  • Only appears when Iris extraction has been used
  • Billed on the extracted text output tokens
  • See Billing for pricing details

Each card shows:

  • Large formatted number (K for thousands, M for millions)
  • Color-coded by operation type
  • Descriptive icon

Usage Over Time Chart​

A stacked area chart visualizes usage patterns:

Reading the Chart​

  • X-axis: Time (hours for 24h, days for 7d/30d)
  • Y-axis: Token count
  • Colors:
    • Blue: Retain
    • Green: Recall
    • Purple: Reflect
    • Teal: Retrieve Model
    • Orange: Refresh Model
    • Red: File Conversion (Iris)

Interactive Features​

  • Hover: View exact values at any point
  • Legend: Click to toggle operation types
  • Tooltip: Shows breakdown by operation

Understanding Patterns​

Look for:

  • Spikes: Sudden increases may indicate bulk operations
  • Patterns: Regular peaks might show scheduled jobs
  • Trends: Gradual increases suggest growing usage

Usage by API Key​

When API keys have been used, a breakdown shows usage per key:

Key Usage Cards​

Each card displays:

  • Key Name: The name you gave the key (or "UI" for web interface usage)
  • Key Prefix: First few characters for identification
  • Token Breakdown: Retain, Recall, Reflect counts
  • Total: Combined tokens for this key
  • Percentage: Share of total usage

Identifying Keys​

  • Regular API keys show their custom name
  • Web interface usage appears as "UI" with a special badge
  • Revoked keys are indicated with their prefix only

Optimizing Usage​

Reducing Token Consumption​

Retain Operations​

  • Batch multiple memories in single API calls
  • Avoid storing redundant information
  • Use efficient text formats

Recall Operations​

  • Use specific, targeted queries
  • Apply filters to narrow search scope
  • Cache frequently accessed results

Reflect Operations​

  • Formulate clear, focused questions
  • Limit context when possible
  • Reuse insights across similar queries

Mental Model Operations​

  • Retrieve models instead of refreshing when recent data is sufficient
  • Refreshing a model runs reflect internally, so it costs more than a simple retrieval
  • Use auto-refresh sparingly for frequently changing banks

File Conversion (Iris)​

  • Use Standard extraction for text-based documents (Word, Excel, text files, digitally-created PDFs) — it's free
  • Reserve Enhanced (Iris) extraction for images, scanned PDFs, and documents with complex layouts where Standard extraction produces poor results

Monitoring Costs​

  1. Check usage weekly to catch unexpected increases
  2. Review by API key to identify inefficient integrations
  3. Compare periods to understand growth patterns

Data Interpretation​

Understanding Token Counts​

Tokens are sub-word units used by the AI models:

  • Average word ≈ 1-2 tokens
  • 1 million tokens ≈ 750,000 words

Empty Data​

If no usage data appears:

  • Verify the selected time period
  • Check that API keys have been used
  • Ensure you're viewing the correct organization

Data Freshness​

  • Dashboard auto-refreshes every 30 seconds
  • Historical data may have slight delays
  • Real-time usage is accurate within minutes