Transactions Object Structure

Overview

The transactions object controls whether token usage records are saved to the database in LibreChat. This allows administrators to enable or disable transaction tracking independently from the balance system.

Fields under transactions:

• enabled

Notes:

• Transaction recording is essential for tracking historical token usage
• When balance.enabled is set to true, transactions are automatically enabled regardless of this setting
• Default value is true to ensure token usage is tracked by default
• Disabling transactions can reduce database storage requirements but will prevent historical usage analysis

Example

transactions:
  enabled: false

enabled

Key:

Description:

The enabled field determines whether LibreChat saves detailed transaction records for each token usage event. These records include:

• Token counts for prompts and completions
• Associated costs and rates
• User and conversation identifiers
• Timestamps for each transaction

Important Behavior:

When the balance system is enabled (balance.enabled: true), transaction recording is automatically enabled regardless of the transactions.enabled setting. This ensures that:

1. Balance tracking functions correctly with a complete audit trail
2. Token usage can be accurately calculated and deducted from user balances
3. Historical data is available for balance reconciliation

Use Cases:

• Enable transactions (true): When you need to track usage patterns, generate reports, or maintain an audit trail
• Disable transactions (false): When you want to reduce database storage and don’t need historical usage data (only works when balance tracking is also disabled)

Relationship with Balance System

The transactions and balance systems work together:

# When balance is enabled, transactions are always enabled
balance:
  enabled: true
  startBalance: 20000
 
transactions:
  enabled: false  # This will be overridden to true because balance.enabled is true

# Track transactions without balance management
balance:
  enabled: false
 
transactions:
  enabled: true  # Records all token usage without enforcing balance limits

Database Impact

When transactions are enabled, each API call that consumes tokens creates a record in the “Transactions” collection with the following information:

• User ID and email
• Conversation ID
• Model used
• Token counts (prompt and completion)
• Token values and rates
• Timestamp
• Transaction type (credit or debit)

Consider the storage implications when enabling transactions for high-volume deployments.