# Usage Tracking

Solo tracks your token usage and agent executions to help you stay within plan limits and understand your usage patterns.

## What is Tracked?

### Token Usage

- **AI tokens consumed**: Every AI model call
- **Per identity**: Usage tracked per Solo Identity
- **Monthly totals**: Resets each month
- **Plan limits**: Based on your subscription plan

### Agent Executions

- **Agent runs**: Every time an agent processes work
- **Per identity**: Executions tracked per Solo Identity
- **Monthly totals**: Resets each month
- **Plan limits**: Based on your subscription plan

## Viewing Usage

### In Settings

1. Go to **Settings → Workflow**

2. View **Token Usage** card:
   - Current usage vs. plan limit
   - Percentage used
   - Progress bar
   - Warnings if approaching limit
3. View **Agent Executions** card:
   - Total executions this month
   - Completed vs. failed
   - Success rate
   - Progress bar

### Usage Metrics

**Token Usage:**

- **Used**: Tokens consumed this month
- **Limit**: Your plan's token limit
- **Percentage**: How much of limit used
- **Status**: Normal, Warning (80%), Error (100%)

**Agent Executions:**

- **Total**: Total executions this month
- **Completed**: Successful executions
- **Failed**: Failed executions
- **Success Rate**: Percentage of successful runs

## Plan Limits

| Plan | Token Limit | Execution Limit |
| --- | --- | --- |
| **Free** | 1M/month | 300/month (10/day) |
| **Solopreneur** | 50M/month | 4,500/month (150/day) |
| **Small Business** | 200M/month | 22,500/month (750/day) |
| **Enterprise** | Unlimited | Unlimited |

### Understanding Limits

**Token Limits:**

- Tokens are consumed by AI model calls
- Each agent action uses tokens
- Heavier workflows use more tokens
- Limits reset monthly

**Execution Limits:**

- Each agent run counts as one execution
- Executions are per agent action
- Limits reset monthly
- Based on daily limits × 30 days

## Usage Warnings

### 80% Warning

- **Warning displayed**: When usage reaches 80% of limit
- **Yellow indicator**: Visual warning in UI
- **Recommendation**: Consider optimizing or upgrading
- **Action**: Review usage and adjust if needed

### 100% Limit Reached

- **Error displayed**: When usage reaches 100% of limit
- **Red indicator**: Visual error in UI
- **Throttling**: May be throttled until reset
- **Action**: Upgrade plan or wait for monthly reset

## Tracking with Custom Workflow Tools

If using custom workflow tools (such as n8n):

- **Manual tracking**: You may need to track usage yourself
- **API available**: Use `/api/v1/usage/track` endpoint
- **See API docs**: For tracking implementation

### Tracking Token Usage

```bash
POST /api/v1/usage/track
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "type": "token_usage",
  "identityId": "uuid",
  "promptTokens": 100,
  "completionTokens": 50,
  "totalTokens": 150,
  "model": "gpt-4",
  "provider": "openai",
  "usageType": "completion",
  "operation": "email.reply",
  "agentId": "uuid",
  "conversationId": "uuid"
}
```

### Tracking Agent Executions

```bash
POST /api/v1/usage/track
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "type": "agent_execution",
  "identityId": "uuid",
  "agentId": "uuid",
  "status": "completed",
  "operation": "email.reply",
  "conversationId": "uuid",
  "taskId": "uuid",
  "metadata": { ... }
}
```

## Best Practices

### Monitor Regularly

- Check usage weekly
- Review before major workflows
- Check after adding agents
- Monitor approaching limits

### Optimize Usage

- Configure agents efficiently
- Use specialists when appropriate
- Avoid unnecessary agent calls
- Cache results when possible

### Plan for Growth

- Monitor usage trends
- Plan for increased usage
- Upgrade before hitting limits
- Consider usage patterns

### Understand Costs

- Tokens = AI model costs
- Executions = Agent processing
- Heavier workflows = More usage
- Optimize to reduce costs

## Troubleshooting

### Usage not updating?

- Check you're using default workflows
- Verify identity is activated
- Wait a few minutes for updates
- Contact support if persistent

### Incorrect usage shown?

- Check date range (monthly reset)
- Verify identity is correct
- Review agent activity
- Contact support to investigate

### Hitting limits unexpectedly?

- Review agent configuration
- Check for inefficient workflows
- Monitor agent activity
- Optimize agent usage

## Next Steps

- Learn about [Solo's Default Workflows](/content/docs/v1/workflows/solo-workflows/index.html)
- Explore [Custom Workflow Tools](/content/docs/v1/workflows/custom-n8n/index.html)
- Review [API Reference](/content/docs/v1/api/endpoints/index.html)

* * *

**Version**: 1.0

**Last Updated**: November 2025