Skip to navigation
Build with AlfaWorkplans

Workplan usage monitoring

Track token consumption and usage patterns for your Alfa workplans.

Monitor your workplan’s token consumption to understand usage patterns and optimize costs. Alfa provides comprehensive token usage tracking for both workplan creation and report generation.

Tracking workplan token usage

View your workplan’s token consumption for both creation and all generated reports.

def get_workplan_token_usage(workplan_id):
    """Get token usage for workplan creation and all its reports."""
    url = f"{BASE_URL}/v2/workplans/{workplan_id}/usage"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        workplan_tokens = data.get("total_workplan_token_usage", 0)
        reports_tokens = data.get("total_reports_token_usage", 0)
        reports = data.get("reports", [])
        
        print(f"Workplan creation: {workplan_tokens} tokens")
        print(f"Total reports: {reports_tokens} tokens")
        print(f"Number of reports: {len(reports)}")
        
        # Show individual report usage
        for report in reports:
            report_id = report["report_id"]
            tokens = report["tokens"]
            last_ran = report["last_ran"]
            print(f"  Report {report_id}: {tokens} tokens (last ran: {last_ran})")
        
        return data
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Get comprehensive usage for a workplan
workplan_id = "your-workplan-id"
usage_data = get_workplan_token_usage(workplan_id)

Tracking report token usage

Get detailed token usage for a specific report.

def get_report_token_usage(report_id):
    """Get token usage for a specific report."""
    url = f"{BASE_URL}/v2/reports/{report_id}/usage"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        tokens = data.get("tokens", 0)
        workplan_id = data.get("workplan_id")
        
        print(f"Report {report_id} used {tokens} tokens")
        print(f"Generated from workplan: {workplan_id}")
        
        return data
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Get usage for a specific report
report_id = "your-report-id"
report_usage = get_report_token_usage(report_id)

Tracking overall user usage

View your total token consumption across all workplans and reports for a specific time period.

from datetime import datetime, timedelta
def get_user_token_usage(start_date, end_date):
    """Get total token usage for a user across a date range."""
    url = f"{BASE_URL}/v2/total-usage/{start_date}/{end_date}"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        total_tokens = data.get("tokens", 0)
        
        print(f"Total tokens used from {start_date} to {end_date}: {total_tokens}")
        
        return data
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Get usage for the last 7 days
seven_days_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
today = datetime.now().strftime("%Y-%m-%d")
usage_data = get_user_token_usage(seven_days_ago, today)

Example: Analyzing usage patterns

1

Collect usage data

Retrieve comprehensive usage data for analysis:

# Get 30 days of total usage data
thirty_days_ago = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
today = datetime.now().strftime("%Y-%m-%d")
total_usage = get_user_token_usage(thirty_days_ago, today)
# Get workplan-specific usage
workplan_usage = get_workplan_token_usage("your-workplan-id")
# Get 30 days of usage data
thirty_days_ago = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
usage = get_agent_usage_history(agent_id, thirty_days_ago)
if usage and "usage_history" in usage:
    history = usage["usage_history"]
    
    # Calculate daily averages
    total_tokens = sum(entry["tokens"] for entry in history)
    total_days = len(history)
    avg_tokens_per_day = total_tokens / total_days if total_days > 0 else 0
    
    print(f"Average daily usage: {avg_tokens_per_day:.0f} tokens")
    
    # Find peak usage day
    peak_day = max(history, key=lambda x: x["tokens"])
    print(f"Peak usage: {peak_day['tokens']} tokens on {peak_day['date']}")
2

Calculate averages

Analyze consumption patterns:

if total_usage:
    total_tokens = total_usage.get("tokens", 0)
    days = 30
    avg_tokens_per_day = total_tokens / days
    
    print(f"Average daily usage: {avg_tokens_per_day:.0f} tokens")
    print(f"Total usage over 30 days: {total_tokens} tokens")
if workplan_usage:
    workplan_tokens = workplan_usage.get("total_workplan_token_usage", 0)
    reports_tokens = workplan_usage.get("total_reports_token_usage", 0)
    total_workplan_usage = workplan_tokens + reports_tokens
    
    print(f"Workplan total usage: {total_workplan_usage} tokens")
    print(f"  Creation: {workplan_tokens} tokens")
    print(f"  Reports: {reports_tokens} tokens")

Use the usage data to identify optimal scheduling patterns and budget for token consumption in automated workplans.

Next steps

Now that you understand how to monitor workplan usage, you can:

Token usage is tracked per API call and aggregated for reporting. Monitor your usage regularly to optimize costs and performance.