ComusThumbz Documentation
HTML Markdown Print/PDF Plain Text
Admin Login

Documentation Menu


Admin Access

Token Usage

Overview

The Token & Credit Usage Dashboard is an administrative interface for monitoring ComusThumbz license API usage, credit balance, and transaction history. It connects to the ComusThumbz license server to display real-time account information, pricing data, and detailed usage logs. The dashboard includes intelligent caching to reduce API calls while maintaining data freshness.

Location: Navigate to this page via Admin Panel → Reports → Token Usage or access directly via ct/admin/tokenusage.php

[Screenshot: token-usage-main-interface]

Getting to This Page

Navigate to Admin Panel → ReportsClick Token Usage link

  1. Alternatively, access directly via ct/admin/tokenusage.php

 

Note:
This page displays your ComusThumbz license API credit balance and usage statistics. Credits are consumed by AI-powered features like image processing and data enrichment.

 

System Requirements

 

Configuration Required:
This page requires a valid ComusThumbz license with API credentials configured. Internet connectivity to the license server is required for data retrieval.

 

PHP Requirements

Requirement Minimum Recommended Notes
PHP Version 8.0 8.2+ Uses modern PHP syntax
memorylimit 64M 128M For transaction history processing
maxexecutiontime 30 60 API calls may take time

Required PHP Extensions

Extension Required Purpose
curl Yes License API communication
session Yes CSRF protection, authentication
json Yes API response parsing
date Yes Timestamp formatting
openssl Yes HTTPS connections

Required PHP Functions

Function Required For Notes
curlinit() API requests Core
curlsetoptarray() API configuration Core
curlexec() API execution Core
jsondecode() Response parsing Core
jsonencode() Cache storage Caching
fileputcontents() Cache writing Caching
filegetcontents() Cache reading Caching
fileexists() Cache checking Caching
mkdir() Cache directory creation Setup
unlink() Cache clearing Maintenance
glob() Cache file listing Maintenance
bin2hex() CSRF token generation Security
randombytes() CSRF token generation Security

Folder Permissions

Folder Permission Purpose
ct/dat/ 755 (write) Pricing cache storage
ct/dat/transactioncache/ 755 (write) Transaction history cache

Network Requirements

Endpoint Protocol Purpose
comusthumbz.com/projects/api.php HTTPS License API
Font Awesome CDN HTTPS Icons

Features & UI Elements

Page Header

[Screenshot: token-usage-header]

Element Description
Title "Token & Credit Usage Dashboard" with coin icon
Breadcrumb Dashboard → Reports → Token Usage

Navigation Buttons

[Screenshot: token-usage-navigation]

Button Action
Overview Reload main dashboard
Refresh Data Force refresh of all data and caches
Download History Export complete transaction history as CSV
Update Pricing Clear pricing cache and fetch latest
Clear Cache Clear all transaction cache files
Debug API Show raw API responses for troubleshooting
Back to Reports Return to reports.php
Help Open manual/help page

Account Overview Card

[Screenshot: token-usage-account-overview]

Field Description
Email License account email address
License Type License tier (e.g., Pro, Enterprise)
Domain Registered domain
Member Since Account creation date

Balance & Usage Statistics Card

[Screenshot: token-usage-balance-stats]

Metric Description
Current Balance Available credit balance (green if > $1, red if < $1)
Tokens Used Total AI tokens consumed
Credits Used Total credits consumed (USD)
API Calls Made Number of API requests
Images Processed Total images processed
Last Updated Current timestamp

Current API Pricing Card

[Screenshot: token-usage-pricing]

Live pricing from the license server:

Service Display
Image Processing Cost per 10,000 images
Input Tokens Cost per 1 million tokens
Completion Tokens Cost per 1 million tokens
Cached Tokens Cost per 1 million tokens
Tip: Pricing is cached for 5 minutes to reduce API calls. Click "Update Pricing" to force a fresh fetch from the server.

Estimated Usage Remaining Card

[Screenshot: token-usage-estimated]

Calculates remaining usage based on current balance:

Estimate Description
Image Searches Images remaining at current rate
AI Input Tokens Input tokens remaining
AI Completion Tokens Completion tokens remaining
AI Cached Tokens Cached tokens remaining

Low Balance Warning

[Screenshot: token-usage-warning]

 

Warning:
When balance drops below $1.00, a prominent red warning banner appears with a link to purchase more credits at comusthumbz.com/projects/buycredits.php

 

Transaction History Table

[Screenshot: token-usage-transactions]

Column Description
Date Transaction timestamp (Mon Day, HH:MM)
Type Badge: usage (red), purchase (green), refund (blue)
Service AI service type (branded as CTZ-AI)
Amount Credit amount (positive = green, negative = red)
Tokens Tokens used in transaction
Images Images processed in transaction
Description Transaction details (first 50 chars)

Pagination

[Screenshot: token-usage-pagination]

Element Description
Info "Showing X-Y of Z transactions (Page N of M)"
Cache Status Age of cached data
Previous/Next Page navigation arrows
Page Numbers Direct page links (±5 around current)
Note: Pagination displays 300 transactions per page. Use arrow keys (← →) for keyboard navigation between pages.
Element Description
API Current API endpoint URL
Updated Last refresh timestamp
Pricing Cache status (Cached/Live)
Transactions Cache status (Cached/Live)
Refresh Quick refresh link
Help Help documentation link

Caching System

The dashboard implements a two-tier caching system:

Pricing Cache

Property Value
File ct/dat/pricingcache.json
Duration 5 minutes (300 seconds)
Contents API pricing rates, timestamp

Transaction Cache

Property Value
Directory ct/dat/transactioncache/
File Pattern transactions{domainhash}{date}.json
Duration 1 hour (3600 seconds)
Contents Complete transaction history
Tip: Cache files are domain-specific using MD5 hash, allowing multiple installations to share the same server without conflicts.

AI Provider Name Branding

The dashboard sanitizes AI provider names for consistent branding:

Original Replaced With
via xai, openai, anthropic, google via CTZ-AI
(grok-), (gpt-), (claude-), (gemini-), (o1-), (o3-) (ComusThumbz AI)
Standalone model names ComusThumbz AI

This ensures transaction descriptions show branded names instead of third-party AI provider names.

Step-by-Step Usage

Viewing Credit Balance

  1. Navigate to Admin Panel → Reports → Token Usage
  2. View Current Balance in Balance & Usage Statistics card
  3. Green color indicates healthy balance (> $1.00)
  4. Red color indicates low balance (< $1.00)

Checking Usage Statistics

  1. View Balance & Usage Statistics card
  2. Note total tokens used and credits consumed
  3. Check Estimated Usage Remaining for projections
  4. Monitor API calls and images processed counts

Downloading Transaction History

  1. Click Download History button in navigation
  2. CSV file downloads automatically
  3. File includes all transactions with:
  • Date, Type, Service, Amount, Tokens, Images, Description
  1. Open in Excel or spreadsheet application

Refreshing Data

  1. Click Refresh Data button
  2. All caches are cleared
  3. Fresh data fetched from API
  4. Page reloads with updated information

Clearing Caches Manually

Clear Pricing Cache:

  1. Click Update Pricing button
  2. Pricing cache deleted
  3. Latest pricing fetched from API

 

Clear Transaction Cache:

  1. Click Clear Cache button
  2. All transaction cache files deleted
  3. Fresh transaction history fetched on next load

 

Debugging API Issues

  1. Click Debug API button
  2. Page displays raw API responses:
  • Configuration settings
  • Cache file status
  • USER INFO response
  • USER STATS response
  • First 5 transactions
  1. Use for troubleshooting connection issues

Purchasing More Credits

  1. When low balance warning appears
  2. Click "Click here to purchase credits" link
  3. Redirects to comusthumbz.com purchase page
  4. Complete credit purchase
  5. Return to dashboard and click Refresh Data

API Endpoints Used

The dashboard calls the following license server endpoints:

Endpoint Method Purpose
pricing/current GET Fetch current pricing rates
user/info GET Get user account information
user/stats GET Get usage statistics
credits/history GET Get transaction history (limit: 10000)

All requests include authentication parameters:

  • licensekey - Your license key
  • domain - Registered domain
  • email - Account email

Troubleshooting

Common Errors

 

Error:
"Failed to connect to License API"


Cause: Network connectivity or SSL issues
Solution:

  1. Check internet connectivity
  2. Verify cURL extension is enabled
  3. Check if SSL certificates are valid
  4. Try accessing API URL in browser

 

 

Error:
"API returned HTTP 500"


Cause: Server-side API error
Solution:

  1. Wait a few minutes and retry
  2. Contact ComusThumbz support if persistent
  3. Check license validity

 

 

Error:
"Invalid API response format"


Cause: API returned non-JSON response
Solution:

  1. Use Debug API to see raw response
  2. Check for PHP errors on license server
  3. Verify license credentials

 

 

Warning:
"Unable to Load Account Data"


Cause: License configuration missing or incorrect
Solution:

  1. Verify licenseconfig in config.inc.php
  2. Check licensekey, domain, email values
  3. Ensure license is active and not expired

 

 

Warning:
Cache not updating


Cause: Permission issues or stale cache
Solution:
Click Clear Cache and Update PricingCheck write permissions on ct/dat/ folder

  1. Verify ct/dat/transactioncache/ exists

 

Debug Mode

Access debug mode by adding ?debug=1 to the URL:

ct/admin/tokenusage.php?debug=1

Debug output includes:

  • API Base URL
  • License Key (truncated)
  • Domain and Email
  • Cache file paths and status
  • Raw API responses for all endpoints

 

Auto-Refresh

The dashboard automatically refreshes every 10 minutes:

setTimeout(function() {
    window.location.href = '?action=refreshdata';
}, 600000);

 

Tip:
Leave the dashboard open to monitor credit usage in near real-time. Data refreshes automatically every 10 minutes.

 

Keyboard Navigation

Key Action
← (Left Arrow) Previous page of transactions
→ (Right Arrow) Next page of transactions

CSV Export Format

Downloaded CSV includes UTF-8 BOM for Excel compatibility:

Column Description
Date Transaction timestamp
Transaction Type usage, purchase, refund
Service Type AI service (sanitized branding)
Amount Credit amount
Tokens Used Token count
Images Processed Image count
Description Full description (sanitized)

Translatable Strings

The following strings should be added to backendtranslations.md:

tokenusagetitle = "Token & Credit Usage Dashboard"
tokenusagebreadcrumb = "Token Usage"
tokenusageoverview = "Overview"
tokenusagerefresh = "Refresh Data"
tokenusagedownload = "Download History"
tokenusageupdatepricing = "Update Pricing"
tokenusageclearcache = "Clear Cache"
tokenusagedebug = "Debug API"
tokenusageback = "Back to Reports"
tokenusagehelp = "Help"
tokenusageaccountoverview = "Account Overview"
tokenusageemail = "Email"
tokenusagelicensetype = "License Type"
tokenusagedomain = "Domain"
tokenusagemembersince = "Member Since"
tokenusagebalancestats = "Current Balance & Usage Statistics"
tokenusagecurrentbalance = "Current Balance"
tokenusagetokensused = "Tokens Used"
tokenusagecreditsused = "Credits Used"
tokenusageapicalls = "API Calls Made"
tokenusageimagesprocessed = "Images Processed"
tokenusagelastupdated = "Last Updated"
tokenusagepricing = "Current API Pricing (Live)"
tokenusageimageprocessing = "Image Processing"
tokenusageinputtokens = "Input Tokens"
tokenusagecompletiontokens = "Completion Tokens"
tokenusagecachedtokens = "Cached Tokens"
tokenusageestimated = "Estimated Usage Remaining"
tokenusageimagesearches = "Image Searches"
tokenusagelowbalance = "LOW BALANCE WARNING"
tokenusagelowbalancemsg = "Your credit balance is below $1.00. Consider purchasing more credits to continue using AI services."
tokenusagebuycredits = "Click here to purchase credits"
tokenusagetransactionhistory = "Complete Transaction History"
tokenusageshowing = "Showing"
tokenusageof = "of"
tokenusagetransactions = "transactions"
tokenusagepage = "Page"
tokenusagecache = "Cache"
tokenusageold = "old"
tokenusageprevious = "Previous"
tokenusagenext = "Next"
tokenusagedate = "Date"
tokenusagetype = "Type"
tokenusageservice = "Service"
tokenusageamount = "Amount"
tokenusagetokens = "Tokens"
tokenusageimages = "Images"
tokenusagedescription = "Description"
tokenusagenotransactions = "No transaction history available"
tokenusageunableload = "Unable to Load Account Data"
tokenusagecheckconfig = "Please check your license configuration and try again."
tokenusageretry = "Retry Loading Data"
tokenusagenotransactionsdownload = "No transaction history available to download."
tokenusagedownloadfailed = "Failed to fetch data for download. Please try again."
tokenusagedatarefreshed = "Data refreshed successfully"
tokenusagepricingcleared = "Pricing cache cleared. Latest prices will be fetched."
tokenusagecachecleared = "Cleared transaction cache files. Fresh data will be fetched."

Version History

Version Date Changes
1.0 2024 Initial release with pagination and caching
1.1 2025 Added AI provider name branding/sanitization

Related Pages