> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/alfa/guides/build-with-alfa/workplans/track-token-usage/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# 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.

```python
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.

```python
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.

```python
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

#### Collect usage data

Retrieve comprehensive usage data for analysis:

```python
# 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")
```

```Python
# 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)
```

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

#### Calculate averages

Analyze consumption patterns:

```python
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")
```

> **Tip**
>
> 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](/guides/build-with-alfa/scheduling-workplans/schedule-and-automate-workplans) to run on a custom schedule
* Explore using [documents](/guides/build-with-alfa/knowledge-base/documents) with your agents

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

> Track token consumption and usage patterns for your Alfa workplans.