## Overview
The Usage page provides detailed request-level analytics and logging. Monitor your API usage in real-time, filter requests by model stack, and track spending patterns. Auto-refreshes every 30 seconds to keep you informed of the latest activity.
## Key Features
View spending and usage metrics with 30-second auto-refresh.
Detailed logs of every API request with timestamps, costs, and model usage.
Filter by model stack, date range, or other criteria to analyze specific
workflows.
Navigate through request history with 25 items per page for easy browsing.
## Usage Dashboard
The dashboard displays high-level metrics about your API usage:
### Time-Windowed Spending
Visual representation of your spending against subscription caps:
**Current 5-Hour Window:**
- Remaining cap for current window
- Time until next reset
- Progress bar showing % used
- Spent amount vs cap amount
**Weekly Progress:**
- Total weekly spending vs weekly cap
- Days until weekly reset
- Progress bar showing weekly usage
**Premium Budget:**
- Remaining premium budget for this month
- Premium requests made
- Monthly reset date
The dashboard automatically refreshes every 30 seconds to show your latest
usage without manual refresh.
### Balance Overview
Current balance status:
- **Prepaid Balance** - Your top-up balance for overage
- **Subscription Status** - Active plan and renewal date
- **Recent Activity** - Quick summary of last 24 hours
## Request History
The main section shows a detailed log of all your API requests:
### Request Table Columns
| Column | Description | Example |
| ------------- | -------------------------- | ------------------------------------------ |
| **Timestamp** | When the request was made | "Jun 15, 2026 2:34 PM" |
| **Model** | Model or stack used | "claude-sonnet-4-6" or "code-review" (your Stack ID) |
| **Tokens** | Input + output token count | "1,234 tokens (850 in + 384 out)" |
| **Cost** | Request cost in dollars | "$0.0032" |
| **Status** | Success or error code | "200" or "429" |
| **Latency** | Response time | "1,234 ms" |
### Understanding Request Details
**Successful Requests (Status 200):**
- Show green checkmark indicator
- Display full token breakdown
- Show actual cost charged
**Failed Requests (Status 4xx/5xx):**
- Show red X indicator
- Display error code and message
- Zero cost (not charged for failures)
**Rate Limited (Status 429):**
- Show yellow warning indicator
- Display "Rate limit exceeded"
- Includes retry-after information
**Spending Cap Exceeded:**
- Show orange indicator
- Display "Window cap exceeded" or "Weekly cap exceeded"
- Includes cap reset time
## Filtering Logs
### Filter by Model Stack
Use the model stack dropdown to view requests for specific stacks:
1. Click the **Model Stack** filter dropdown
2. Select a stack from your list
3. Table updates to show only that stack's requests
4. "All Stacks" option shows requests from all sources
**Use Cases:**
- Compare performance between different stacks
- Analyze cost per stack
- Debug issues with specific stack configurations
- Track which stacks are used most frequently
### Filter Controls
**Reset Filters:**
- Click **Reset** button to clear all filters
- Returns to showing all requests
- Resets pagination to page 1
**Date Range** (coming soon):
- Filter by time period
- Last 24 hours, 7 days, 30 days
- Custom date range selector
## Pagination
Navigate through your request history:
- **25 requests per page** - Balance between detail and load time
- **Previous/Next buttons** - Navigate between pages
- **Page numbers** - Jump directly to specific pages
- **Total count** - Shows "Page X of Y" and total requests
Pagination resets to page 1 when you change filters to show the most recent
matching requests first.
## Auto-Refresh Behavior
The Usage page automatically refreshes to keep data current:
**Refresh Interval:**
- Every **30 seconds** automatically
- Only when tab is active (pauses when tab is hidden)
- Maintains current filter and page settings
**What Gets Refreshed:**
- Request history (new requests appear at top)
- Spending dashboard (caps, budgets, progress bars)
- Model stack list (if you create/delete stacks)
**When Auto-Refresh Pauses:**
- When you switch to another browser tab
- When computer goes to sleep
- Resumes automatically when you return
The 30-second auto-refresh ensures you see new requests without manual
refreshing. Perfect for monitoring active API usage in real-time.
## Use Cases
### Use Case 1: Monitoring Active Development
**Scenario:** You're actively developing and testing your integration
**How to use:**
1. Keep Usage page open in a browser tab
2. Make API requests from your application
3. Watch requests appear in real-time (within 30 seconds)
4. Check costs and token counts per request
5. Verify models and stacks are working as expected
**What to watch for:**
- Unexpected high token counts
- Error rates
- Latency spikes
- Incorrect model selections
### Use Case 2: Debugging Stack Behavior
**Scenario:** You have multiple stacks and one is behaving oddly
**How to use:**
1. Filter by the problematic stack
2. Review recent requests for that stack
3. Check which agents were consulted (if using multi-agent stack)
4. Analyze token usage patterns
5. Compare with working stacks
**What to look for:**
- Higher than expected costs
- Repeated errors
- Unusually long latencies
- Token count anomalies
### Use Case 3: Cost Analysis
**Scenario:** You want to understand where your spending goes
**How to use:**
1. View all requests without filters
2. Sort by cost (if available) or scroll to find expensive requests
3. Filter by high-usage stacks
4. Identify patterns in expensive requests
5. Optimize by switching models or adjusting stack configurations
**Metrics to track:**
- Average cost per request
- Total spending per stack
- Cost distribution across models
- Time periods with highest spending
### Use Case 4: Performance Monitoring
**Scenario:** You need to ensure API latency stays acceptable
**How to use:**
1. Monitor the Latency column
2. Check for requests over your target threshold (e.g., >2000ms)
3. Filter by stack to identify slow configurations
4. Compare latency across different models
5. Adjust stack models if needed
**Thresholds to watch:**
- Average latency under 1,500ms (good)
- Average latency 1,500-3,000ms (acceptable)
- Average latency over 3,000ms (investigate)
### Use Case 5: Quota Management
**Scenario:** You want to avoid hitting spending caps
**How to use:**
1. Watch the spending dashboard progress bars
2. Monitor request frequency in real-time
3. Check costs per request
4. Slow down or stop requests if approaching cap
5. Plan when to make expensive requests (after window reset)
**Dashboard indicators:**
- 🟢 Green (0-50% of cap) - Safe zone
- 🟡 Yellow (50-80% of cap) - Monitor closely
- 🔴 Red (80-100% of cap) - Approaching limit
## Error Handling
### When Logs Fail to Load
If the request history fails to load:
1. Error message displays: "Failed to load logs"
2. **Retry** button appears
3. Click Retry to attempt reload
4. Auto-refresh continues in background
**Common causes:**
- Temporary network issue
- Server maintenance
- Browser connectivity problem
**Resolution:**
- Wait a few seconds and click Retry
- Check your internet connection
- Try refreshing the entire page
- Contact support if persists
### Empty State
If you have no requests yet:
- "No requests found" message displays
- Tips for making your first API request
- Link to API documentation
- Confirmation that auto-refresh is active
## Best Practices
### Monitoring Strategy
1. **Keep tab open during development** - Auto-refresh shows new requests immediately
2. **Filter by stack when debugging** - Isolate issues to specific configurations
3. **Check daily during active development** - Catch issues early
4. **Review weekly for cost trends** - Identify optimization opportunities
5. **Monitor request volume** - Avoid unexpected 429 errors
### Cost Optimization
1. **Identify expensive patterns** - Find requests with high token counts
2. **Compare model costs** - Switch to cheaper models where appropriate
3. **Optimize prompts** - Reduce input tokens without losing quality
4. **Use context optimization** - Enable stack context modes to reduce tokens
5. **Batch requests** - Group similar requests to amortize overhead
### Performance Optimization
1. **Track latency trends** - Watch for degradation over time
2. **Compare model speeds** - Switch to faster models for latency-sensitive apps
3. **Monitor during peak hours** - Identify if latency correlates with time of day
4. **Test different stacks** - Compare performance across configurations
5. **Set up alerts** - Use external monitoring to alert on latency spikes
### Debugging Workflow
1. **Check recent requests** - Look at last 10-20 requests for patterns
2. **Filter by stack** - Isolate to problematic stack
3. **Review error messages** - Read full error text for clues
4. **Check token counts** - Unusually high counts suggest prompt issues
5. **Compare with working stacks** - Diff configurations to find differences
## Related Documentation
- [Analytics](/docs/dashboard/analytics) - Higher-level metrics and charts
- [Billing & Balance](/docs/billing/balance) - Understanding spending caps
- [Agents](/docs/dashboard/agents) - Creating and configuring stacks
- [API Reference](/docs/api-reference/errors) - Error codes and meanings