Agent Usage Tracking — Real-Time Monitoring & Analytics

Monitor your agent's spending in real-time. Track costs, analyze consumption patterns, and optimize budgets with programmatic access to all usage data.

Real-Time Usage Dashboard

Get Current Usage

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

# Today's usage
usage = requests.get(
    "https://api.skillboss.co/v1/agents/usage",
    headers=headers,
    params={"period": "today"}
).json()

print(f"""
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    TODAY'S USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spent:           ${usage['amount_spent']:.4f}
Operations:      {usage['operation_count']}
Tokens Used:     {usage['total_tokens']:,}
Avg Cost/Op:     ${usage['amount_spent'] / max(usage['operation_count'], 1):.6f}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Top Models:
1. {usage['top_models'][0]['model']} - ${usage['top_models'][0]['cost']:.4f} ({usage['top_models'][0]['calls']} calls)
2. {usage['top_models'][1]['model']} - ${usage['top_models'][1]['cost']:.4f} ({usage['top_models'][1]['calls']} calls)
3. {usage['top_models'][2]['model']} - ${usage['top_models'][2]['cost']:.4f} ({usage['top_models'][2]['calls']} calls)
""")

Sample Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    TODAY'S USAGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Spent:           $12.4523
Operations:      1,247
Tokens Used:     2,450,000
Avg Cost/Op:     $0.009987
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Top Models:
1. claude-4-5-sonnet - $8.2340 (156 calls)
2. gemini-2.5-flash - $2.1200 (892 calls)
3. flux-1.1-pro - $1.5000 (15 calls)

Usage by Time Period

# Different time periods
periods = ["today", "yesterday", "week", "month", "all_time"]

for period in periods:
    usage = requests.get(
        "https://api.skillboss.co/v1/agents/usage",
        headers=headers,
        params={"period": period}
    ).json()

    print(f"{period.upper():12} | ${usage['amount_spent']:>10.2f} | {usage['operation_count']:>8} ops")

Output:

TODAY        |      $12.45 |     1247 ops
YESTERDAY    |      $15.23 |     1892 ops
WEEK         |      $89.67 |    12450 ops
MONTH        |     $342.18 |    48723 ops
ALL_TIME     |    $1284.56 |   182345 ops

Model-by-Model Breakdown

Detailed Model Usage

# Get breakdown by model
breakdown = requests.get(
    "https://api.skillboss.co/v1/agents/usage/breakdown",
    headers=headers,
    params={"period": "month", "group_by": "model"}
).json()

print(f"""
╔════════════════════════════════════════════════════════════════════════════╗
║                         MONTHLY MODEL BREAKDOWN                            ║
╠══════════════════════════╦════════════╦════════════╦═══════════╦══════════╣
║ Model                    ║ Cost       ║ Calls      ║ Tokens    ║ Avg/Call ║
╠══════════════════════════╬════════════╬════════════╬═══════════╬══════════╣""")

for model in breakdown["models"]:
    avg = model["cost"] / max(model["calls"], 1)
    print(f"║ {model['model']:<24} ║ ${model['cost']:>8.2f} ║ {model['calls']:>10,} ║ {model['tokens']:>9,} ║ ${avg:>6.4f} ║")

print("╚══════════════════════════╩════════════╩════════════╩═══════════╩══════════╝")

Output:

╔════════════════════════════════════════════════════════════════════════════╗
║                         MONTHLY MODEL BREAKDOWN                            ║
╠══════════════════════════╦════════════╦════════════╦═══════════╦══════════╣
║ Model                    ║ Cost       ║ Calls      ║ Tokens    ║ Avg/Call ║
╠══════════════════════════╬════════════╬════════════╬═══════════╬══════════╣
║ claude-4-5-sonnet        ║   $185.23 ║      4,521 ║ 8,234,567 ║ $0.0410 ║
║ gemini-2.5-flash         ║    $45.67 ║     28,456 ║12,456,789 ║ $0.0016 ║
║ gpt-5                    ║    $78.34 ║      1,234 ║ 2,345,678 ║ $0.0635 ║
║ flux-1.1-pro             ║    $23.50 ║        235 ║       N/A ║ $0.1000 ║
║ firecrawl/scrape         ║    $12.25 ║        980 ║       N/A ║ $0.0125 ║
╚══════════════════════════╩════════════╩════════════╩═══════════╩══════════╝

Category Breakdown

# Breakdown by category
categories = requests.get(
    "https://api.skillboss.co/v1/agents/usage/breakdown",
    headers=headers,
    params={"period": "month", "group_by": "category"}
).json()

for cat in categories["categories"]:
    bar = "█" * int(cat["percent"] / 2) + "░" * (50 - int(cat["percent"] / 2))
    print(f"{cat['category']:<15} [{bar}] {cat['percent']:.1f}% (${cat['cost']:.2f})")

Output:

Chat/LLM        [██████████████████████████████░░░░░░░░░░░░░░░░░░░░] 60.2% ($206.12)
Image Gen       [███████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 22.5% ($77.04)
Web Scraping    [████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  8.3% ($28.41)
Video Gen       [███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  5.2% ($17.80)
Other           [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  3.8% ($13.01)

Cost Alerts & Webhooks

Configure Alerts

# Set up budget alerts
requests.post(
    "https://api.skillboss.co/v1/agents/alerts",
    headers=headers,
    json={
        "daily_budget": 25.00,
        "alerts": [
            {"percent": 50, "action": "webhook"},
            {"percent": 80, "action": "webhook"},
            {"percent": 95, "action": "webhook"},
            {"percent": 100, "action": "pause_agent"}
        ],
        "webhook_url": "https://your-agent.com/budget-alert",
        "email": "alerts@company.com"
    }
)

Alert Webhook Payload

{
  "alert_type": "budget_warning",
  "agent_id": "agent_abc123",
  "timestamp": "2026-03-24T14:30:00Z",
  "budget": {
    "daily_limit": 25.00,
    "amount_spent": 20.00,
    "percent_used": 80,
    "amount_remaining": 5.00
  },
  "projection": {
    "estimated_daily_total": 32.50,
    "hours_until_depleted": 3.2,
    "will_exceed_budget": true
  },
  "top_cost_drivers": [
    {"model": "claude-4-5-sonnet", "cost": 12.50, "percent": 62.5},
    {"model": "gpt-5", "cost": 4.20, "percent": 21.0},
    {"model": "gemini-2.5-flash", "cost": 3.30, "percent": 16.5}
  ],
  "recommendations": [
    {
      "action": "switch_model",
      "from": "claude-4-5-sonnet",
      "to": "gemini-2.5-flash",
      "estimated_savings": "$8.75/day"
    },
    {
      "action": "reduce_frequency",
      "task": "content_generation",
      "estimated_savings": "$3.20/day"
    }
  ]
}

Handle Alerts in Agent

from flask import Flask, request

app = Flask(__name__)

@app.route("/budget-alert", methods=["POST"])
def handle_budget_alert():
    alert = request.json

    if alert["budget"]["percent_used"] >= 80:
        # Switch to economy mode
        switch_to_cheaper_models()

        # Pause non-critical operations
        pause_background_tasks()

        # Notify human
        send_slack_notification(
            f"⚠️ Agent budget at {alert['budget']['percent_used']}%\n"
            f"Spent: ${alert['budget']['amount_spent']:.2f}\n"
            f"Remaining: ${alert['budget']['amount_remaining']:.2f}"
        )

    if alert["budget"]["percent_used"] >= 95:
        # Emergency mode - only critical operations
        enter_emergency_mode()

    return {"received": True}

def switch_to_cheaper_models():
    """Replace expensive models with budget alternatives."""
    global MODEL_OVERRIDE
    MODEL_OVERRIDE = {
        "claude-4-5-sonnet": "gemini-2.5-flash",
        "gpt-5": "deepseek/deepseek-v3",
        "dall-e-3": "flux-schnell"
    }

def enter_emergency_mode():
    """Only process highest-priority tasks."""
    global EMERGENCY_MODE
    EMERGENCY_MODE = True

Historical Analytics

Daily Trends

# Get daily usage for the past 30 days
analytics = requests.get(
    "https://api.skillboss.co/v1/agents/analytics",
    headers=headers,
    params={
        "start_date": "2026-02-22",
        "end_date": "2026-03-24",
        "group_by": "day"
    }
).json()

import pandas as pd

df = pd.DataFrame(analytics["daily_usage"])

print(f"""
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 30-DAY SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Spent:     ${df['cost'].sum():.2f}
Daily Average:   ${df['cost'].mean():.2f}
Peak Day:        {df.loc[df['cost'].idxmax(), 'date']} (${df['cost'].max():.2f})
Lowest Day:      {df.loc[df['cost'].idxmin(), 'date']} (${df['cost'].min():.2f})
Total Operations: {df['operations'].sum():,}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
""")

# Print sparkline-style chart
max_cost = df['cost'].max()
for _, row in df.iterrows():
    bar_len = int((row['cost'] / max_cost) * 40)
    bar = "▓" * bar_len + "░" * (40 - bar_len)
    print(f"{row['date'][-5:]} [{bar}] ${row['cost']:>7.2f}")

Hourly Patterns

# Identify peak usage hours
hourly = requests.get(
    "https://api.skillboss.co/v1/agents/analytics",
    headers=headers,
    params={
        "start_date": "2026-03-17",
        "end_date": "2026-03-24",
        "group_by": "hour"
    }
).json()

print("Hourly Usage Pattern (UTC):")
print("=" * 60)

for hour_data in hourly["hourly_usage"]:
    hour = hour_data["hour"]
    cost = hour_data["avg_cost"]
    ops = hour_data["avg_operations"]
    bar = "█" * int(cost * 4)
    print(f"{hour:02d}:00 [{bar:<40}] ${cost:.2f} ({ops:.0f} ops)")

Output:

Hourly Usage Pattern (UTC):
============================================================
00:00 [████                                    ] $1.23 (45 ops)
01:00 [██                                      ] $0.56 (23 ops)
02:00 [█                                       ] $0.34 (12 ops)
...
09:00 [████████████████████                    ] $5.67 (234 ops)
10:00 [██████████████████████████████          ] $8.45 (356 ops)
11:00 [████████████████████████████████████████] $12.34 (489 ops)
...

Optimization Recommendations

Automated Analysis

# Get optimization recommendations
recommendations = requests.get(
    "https://api.skillboss.co/v1/agents/usage/optimize",
    headers=headers
).json()

print("""
╔═══════════════════════════════════════════════════════════════════════════╗
║                      OPTIMIZATION RECOMMENDATIONS                         ║
╚═══════════════════════════════════════════════════════════════════════════╝
""")

for i, rec in enumerate(recommendations["recommendations"], 1):
    print(f"""
{i}. {rec['title']}
   Problem:  {rec['problem']}
   Solution: {rec['solution']}
   Impact:   {rec['estimated_savings']} ({rec['percent_reduction']}% reduction)
   Priority: {rec['priority']}
""")

Output:

╔═══════════════════════════════════════════════════════════════════════════╗
║                      OPTIMIZATION RECOMMENDATIONS                         ║
╚═══════════════════════════════════════════════════════════════════════════╝

1. Model Downgrade Opportunity
   Problem:  72% of Claude calls could use cheaper models
   Solution: Route simple queries to Gemini Flash
   Impact:   $8.50/day (45% reduction)
   Priority: HIGH

2. Redundant API Calls
   Problem:  23% of scraping calls hit cached URLs
   Solution: Implement response caching
   Impact:   $2.20/day (18% reduction)
   Priority: MEDIUM

3. Batch Processing
   Problem:  Multiple single-item requests could be batched
   Solution: Batch similar operations (max 10 per request)
   Impact:   $1.50/day (12% reduction)
   Priority: MEDIUM

Implement Optimizations

class CostOptimizedAgent:
    """Agent with built-in cost optimization."""

    def __init__(self, api_key: str):
        self.client = OpenAI(
            base_url="https://api.skillboss.co/v1",
            api_key=api_key
        )
        self.cache = {}

    def smart_route(self, task: str, messages: list):
        """Route to optimal model based on task complexity."""

        # Simple classification/extraction → cheap model
        simple_tasks = ["summarize", "extract", "classify", "translate"]
        if any(t in task.lower() for t in simple_tasks):
            model = "gemini-2.5-flash"  # $0.10/1M tokens

        # Reasoning/analysis → mid-tier model
        elif "analyze" in task.lower() or "compare" in task.lower():
            model = "deepseek/deepseek-v3"  # $0.14/1M tokens

        # Creative/complex → premium model
        else:
            model = "claude-4-5-sonnet"  # $3/1M tokens

        return self.client.chat.completions.create(
            model=model,
            messages=messages
        )

    def cached_call(self, prompt: str, model: str = "gemini-2.5-flash"):
        """Cache responses to avoid redundant API calls."""
        cache_key = f"{model}:{hash(prompt)}"

        if cache_key in self.cache:
            return self.cache[cache_key]

        response = self.client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}]
        )

        self.cache[cache_key] = response.choices[0].message.content
        return self.cache[cache_key]

    def batch_process(self, items: list, task_template: str, model: str = "gemini-2.5-flash"):
        """Process multiple items in fewer API calls."""

        batches = [items[i:i+5] for i in range(0, len(items), 5)]
        results = []

        for batch in batches:
            batch_prompt = f"""Process these items:

{chr(10).join(f'{i+1}. {item}' for i, item in enumerate(batch))}

Task: {task_template}

Return results as numbered list."""

            response = self.client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": batch_prompt}]
            )
            results.extend(parse_batch_response(response.choices[0].message.content))

        return results

Multi-Agent Fleet Monitoring

Parent Agent Dashboard

class FleetMonitor:
    """Monitor all agents in a multi-agent system."""

    def __init__(self, parent_key: str, children: dict):
        self.parent_key = parent_key
        self.children = children

    def get_fleet_status(self):
        """Get real-time status of all agents."""
        status = {
            "timestamp": datetime.now().isoformat(),
            "total_spent": 0,
            "total_budget": 0,
            "agents": []
        }

        for name, child_key in self.children.items():
            usage = requests.get(
                "https://api.skillboss.co/v1/agents/usage",
                headers={"Authorization": f"Bearer {child_key}"},
                params={"period": "month"}
            ).json()

            agent = {
                "name": name,
                "spent": usage["amount_spent"],
                "budget": usage.get("budget", 0),
                "percent": (usage["amount_spent"] / usage.get("budget", 1)) * 100 if usage.get("budget") else 0,
                "operations": usage["operation_count"],
                "status": self._get_status(usage)
            }

            status["agents"].append(agent)
            status["total_spent"] += agent["spent"]
            status["total_budget"] += agent["budget"]

        return status

    def _get_status(self, usage):
        percent = (usage["amount_spent"] / usage.get("budget", 1)) * 100 if usage.get("budget") else 0
        if percent >= 95:
            return "🔴 CRITICAL"
        elif percent >= 80:
            return "🟡 WARNING"
        elif percent >= 50:
            return "🟢 NORMAL"
        else:
            return "🔵 LOW USAGE"

    def print_dashboard(self):
        """Print fleet monitoring dashboard."""
        status = self.get_fleet_status()

        print(f"""
╔══════════════════════════════════════════════════════════════════════════════╗
║                          MULTI-AGENT FLEET MONITOR                           ║
║                          {status['timestamp'][:19]}                            ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ Fleet Total: ${status['total_spent']:.2f} / ${status['total_budget']:.2f}                                    ║
╠══════════════════════════════════════════════════════════════════════════════╣
""")

        for agent in status["agents"]:
            bar = "█" * int(agent["percent"] / 5) + "░" * (20 - int(agent["percent"] / 5))
            print(f"║ {agent['name']:<18} [{bar}] {agent['percent']:>5.1f}% {agent['status']}")
            print(f"║   ${agent['spent']:.2f} / ${agent['budget']:.2f} | {agent['operations']:,} ops")

        print("╚══════════════════════════════════════════════════════════════════════════════╝")

# Usage
monitor = FleetMonitor("sk-parent", {
    "ResearchAgent": "sk-research",
    "ContentAgent": "sk-content",
    "MarketingAgent": "sk-marketing"
})

monitor.print_dashboard()

Output:

╔══════════════════════════════════════════════════════════════════════════════╗
║                          MULTI-AGENT FLEET MONITOR                           ║
║                          2026-03-24T14:30:00                                  ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ Fleet Total: $342.18 / $900.00                                               ║
╠══════════════════════════════════════════════════════════════════════════════╣
║ ResearchAgent      [████████░░░░░░░░░░░░]  38.2% 🔵 LOW USAGE
║   $76.40 / $200.00 | 1,234 ops
║ ContentAgent       [████████████████░░░░]  82.3% 🟡 WARNING
║   $329.20 / $400.00 | 892 ops
║ MarketingAgent     [██████████░░░░░░░░░░]  45.5% 🟢 NORMAL
║   $136.58 / $300.00 | 2,456 ops
╚══════════════════════════════════════════════════════════════════════════════╝

Export & Reporting

Generate CSV Report

# Export usage data to CSV
export = requests.get(
    "https://api.skillboss.co/v1/agents/usage/export",
    headers=headers,
    params={
        "format": "csv",
        "start_date": "2026-03-01",
        "end_date": "2026-03-24"
    }
)

with open("usage_report.csv", "w") as f:
    f.write(export.text)

Generate PDF Invoice

# Get detailed invoice
invoice = requests.get(
    "https://api.skillboss.co/v1/agents/invoice",
    headers=headers,
    params={"month": "2026-03"}
).json()

print(f"""
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                      SKILLBOSS INVOICE
                        March 2026
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Agent ID:     {invoice['agent_id']}
Period:       {invoice['period_start']} to {invoice['period_end']}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

USAGE BREAKDOWN:
""")

for item in invoice["line_items"]:
    print(f"  {item['category']:<20} {item['usage']:<15} ${item['cost']:>10.2f}")

print(f"""
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Subtotal:                                      ${invoice['subtotal']:>10.2f}
Volume Discount ({invoice['discount_percent']}%):                         -${invoice['discount']:>9.2f}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOTAL:                                         ${invoice['total']:>10.2f}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
""")

API Reference

Endpoints

Query Parameters

Next Steps

Agent-Readable Monitoring Summary:

{
  "monitoring_endpoints": {
    "current_usage": "GET /v1/agents/usage?period=today",
    "breakdown": "GET /v1/agents/usage/breakdown?group_by=model",
    "analytics": "GET /v1/agents/analytics?start_date=YYYY-MM-DD",
    "optimize": "GET /v1/agents/usage/optimize"
  },
  "alert_thresholds": {
    "warning": 80,
    "critical": 95,
    "actions": ["webhook", "email", "pause_agent"]
  },
  "optimization_actions": [
    "switch_to_cheaper_model",
    "implement_caching",
    "batch_processing",
    "reduce_frequency"
  ]
}