Agent usage monitoring

Monitor your agent’s token consumption to understand usage patterns and optimize costs. Alfa provides two ways to track token usage: per-run token counts and historical usage data.

Getting token usage from agent output

When you retrieve an agent’s output, you’ll also receive the token count for that specific run.

1 import requests
2 
3 BASE_URL = "https://alfa.boosted.ai/client"
4 API_KEY = "YOUR_API_KEY_HERE"
5 
6 headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
7 
8 def get_agent_output_with_usage(agent_id):
9     """Retrieve agent results along with token usage information."""
10     url = f"{BASE_URL}/get-agent-output/{agent_id}"
11     
12     response = requests.get(url, headers=headers)
13     
14     if response.status_code == 200:
15         data = response.json()
16         token_count = data.get("token_count")
17         outputs = data.get("outputs", [])
18         
19         print(f"Agent run used {token_count} tokens")
20         print(f"Generated {len(outputs)} outputs")
21         
22         return data
23     else:
24         print(f"Error: {response.status_code}, {response.text}")
25         return None
26 
27 # Get results and token usage for a completed agent
28 agent_id = "your-agent-id-here"
29 results = get_agent_output_with_usage(agent_id)

Tracking historical usage

View your agent’s token consumption over time to identify usage patterns and trends.

1 from datetime import datetime, timedelta
2 
3 def get_agent_usage_history(agent_id, from_date):
4     """Get daily token usage history for an agent."""
5     url = f"{BASE_URL}/get-agent-usage-history/{agent_id}/{from_date}"
6     
7     response = requests.get(url, headers=headers)
8     
9     if response.status_code == 200:
10         data = response.json()
11         usage_history = data.get("usage_history", [])
12         total_runs = data.get("total_runs", 0)
13         
14         print(f"Total runs in period: {total_runs}")
15         print("\nDaily usage breakdown:")
16         
17         for entry in usage_history:
18             date = entry["date"]
19             tokens = entry["tokens"]
20             runs = entry["run_count"]
21             print(f"{date}: {tokens} tokens across {runs} runs")
22         
23         return data
24     else:
25         print(f"Error: {response.status_code}, {response.text}")
26         return None
27 
28 # Get usage for the last 7 days
29 seven_days_ago = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
30 usage_data = get_agent_usage_history(agent_id, seven_days_ago)

Example: Analyzing usage patterns

Collect usage data

Retrieve historical usage for analysis:

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)

Calculate averages

Analyze consumption patterns:

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']}")

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