Workplan usage monitoring

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.

1 def get_workplan_token_usage(workplan_id):
2     """Get token usage for workplan creation and all its reports."""
3     url = f"{BASE_URL}/v2/workplans/{workplan_id}/usage"
4     
5     response = requests.get(url, headers=headers)
6     
7     if response.status_code == 200:
8         data = response.json()
9         workplan_tokens = data.get("total_workplan_token_usage", 0)
10         reports_tokens = data.get("total_reports_token_usage", 0)
11         reports = data.get("reports", [])
12         
13         print(f"Workplan creation: {workplan_tokens} tokens")
14         print(f"Total reports: {reports_tokens} tokens")
15         print(f"Number of reports: {len(reports)}")
16         
17         # Show individual report usage
18         for report in reports:
19             report_id = report["report_id"]
20             tokens = report["tokens"]
21             last_ran = report["last_ran"]
22             print(f"  Report {report_id}: {tokens} tokens (last ran: {last_ran})")
23         
24         return data
25     else:
26         print(f"Error: {response.status_code}, {response.text}")
27         return None
28 
29 # Get comprehensive usage for a workplan
30 workplan_id = "your-workplan-id"
31 usage_data = get_workplan_token_usage(workplan_id)

Tracking report token usage

Get detailed token usage for a specific report.

1 def get_report_token_usage(report_id):
2     """Get token usage for a specific report."""
3     url = f"{BASE_URL}/v2/reports/{report_id}/usage"
4     
5     response = requests.get(url, headers=headers)
6     
7     if response.status_code == 200:
8         data = response.json()
9         tokens = data.get("tokens", 0)
10         workplan_id = data.get("workplan_id")
11         
12         print(f"Report {report_id} used {tokens} tokens")
13         print(f"Generated from workplan: {workplan_id}")
14         
15         return data
16     else:
17         print(f"Error: {response.status_code}, {response.text}")
18         return None
19 
20 # Get usage for a specific report
21 report_id = "your-report-id"
22 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.

1 from datetime import datetime, timedelta
2 
3 def get_user_token_usage(start_date, end_date):
4     """Get total token usage for a user across a date range."""
5     url = f"{BASE_URL}/v2/total-usage/{start_date}/{end_date}"
6     
7     response = requests.get(url, headers=headers)
8     
9     if response.status_code == 200:
10         data = response.json()
11         total_tokens = data.get("tokens", 0)
12         
13         print(f"Total tokens used from {start_date} to {end_date}: {total_tokens}")
14         
15         return data
16     else:
17         print(f"Error: {response.status_code}, {response.text}")
18         return None
19 
20 # Get usage for the last 7 days
21 seven_days_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
22 today = datetime.now().strftime("%Y-%m-%d")
23 usage_data = get_user_token_usage(seven_days_ago, today)

Example: Analyzing usage patterns

Collect usage data

Retrieve comprehensive usage data for analysis:

1 # Get 30 days of total usage data
2 thirty_days_ago = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
3 today = datetime.now().strftime("%Y-%m-%d")
4 total_usage = get_user_token_usage(thirty_days_ago, today)
5 
6 # Get workplan-specific usage
7 workplan_usage = get_workplan_token_usage("your-workplan-id")

1 # Get 30 days of usage data
2 thirty_days_ago = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
3 usage = get_agent_usage_history(agent_id, thirty_days_ago)

1 if usage and "usage_history" in usage:
2     history = usage["usage_history"]
3     
4     # Calculate daily averages
5     total_tokens = sum(entry["tokens"] for entry in history)
6     total_days = len(history)
7     avg_tokens_per_day = total_tokens / total_days if total_days > 0 else 0
8     
9     print(f"Average daily usage: {avg_tokens_per_day:.0f} tokens")
10     
11     # Find peak usage day
12     peak_day = max(history, key=lambda x: x["tokens"])
13     print(f"Peak usage: {peak_day['tokens']} tokens on {peak_day['date']}")

Calculate averages

Analyze consumption patterns:

1 if total_usage:
2     total_tokens = total_usage.get("tokens", 0)
3     days = 30
4     avg_tokens_per_day = total_tokens / days
5     
6     print(f"Average daily usage: {avg_tokens_per_day:.0f} tokens")
7     print(f"Total usage over 30 days: {total_tokens} tokens")
8 
9 if workplan_usage:
10     workplan_tokens = workplan_usage.get("total_workplan_token_usage", 0)
11     reports_tokens = workplan_usage.get("total_reports_token_usage", 0)
12     total_workplan_usage = workplan_tokens + reports_tokens
13     
14     print(f"Workplan total usage: {total_workplan_usage} tokens")
15     print(f"  Creation: {workplan_tokens} tokens")
16     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:

Learn how to schedule and automate workplans to run on a custom schedule
Explore using documents with your agents

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