Usage Tracking

CodeCourier provides comprehensive usage tracking that records every resource consumed during AI agent operations. From individual token counts to sandbox uptime, from per-step attribution to daily cost trends, the usage system gives you full visibility into what your AI workflows cost and where the money goes. This page explains what is tracked, how the analytics dashboard works, and strategies for optimizing your usage.

What Is Tracked

Every operation that consumes external resources is recorded as a usageRecord in the Convex database. Each record captures:

• Project -- Which project generated the usage.
• Service -- Which service was consumed (anthropic, openai, openrouter, e2b, trigger_dev, convex).
• Date -- The ISO date string (YYYY-MM-DD) when the usage occurred.
• Quantity -- The amount consumed (tokens, seconds, bytes, etc.).
• Unit-- What was consumed (e.g., "input_tokens", "output_tokens", "sandbox_seconds").
• Cost (USD) -- The calculated dollar cost based on applicable rates.

Tracked Metrics by Service

Anthropic / OpenAI / OpenRouter

• Input tokens -- Tokens sent to the AI model as context (system prompt, conversation history, code files).
• Output tokens -- Tokens generated by the AI model in response.
• Total tokens -- When input/output split is not available, the combined total is recorded.

E2B Sandboxes

• Sandbox seconds -- Active VM uptime from creation to termination.

Trigger.dev

• Task execution time -- Duration of background job execution.

Attribution Fields

Each usage record can optionally include detailed attribution:

• runId -- Which workflow run generated this usage.
• sandboxId -- Which sandbox was involved.
• chainId -- Which sprint chain, if applicable.
• issueSessionId -- Which issue session, if applicable.
• toolId -- Which CLI tool was used (claude, opencode, codex).
• modelId -- The exact AI model ID used.
• stepType -- Which pipeline step (designer, checker, optimizer, etc.).
• stepIndex -- The iteration number within the step.
• userId -- Which team member triggered the operation.
• personaId -- Which persona was responsible.
• durationMs -- Step execution time in milliseconds.

Usage Dashboard

The usage analytics are accessible from your project dashboard. The analytics system provides multiple query endpoints for different views:

Project Usage Summary

The usage.getProjectUsageSummary query returns aggregated usage for a project over a date range. This powers the overview cards showing total cost, total tokens, and total sandbox hours.

Usage Summary with Comparison

The usage.getProjectUsageSummaryWithComparison query returns the current period summary alongside the previous period for trend analysis. This enables the dashboard to show percentage changes (up or down) compared to the previous equivalent time period.

Usage by Day

The usage.getProjectUsageByDay query returns daily cost totals, enabling time-series charts that show spending patterns over time. This helps identify spikes and trends.

Usage by Service

The usage.getProjectUsageByService query breaks down costs by service category (Claude Code, E2B, Trigger.dev, etc.), showing which services consume the most resources.

Aggregated Usage

The usage.getProjectUsageAggregated query provides a flexible aggregation that can group usage by various dimensions (service, model, tool, step type) for detailed analysis.

Run-Level Analytics

For individual runs, the analytics system provides:

• runAnalytics.getRunCostsBatch -- Batch cost retrieval for multiple runs (used by run list views).
• runAnalytics.getRunDetailAnalytics -- Detailed cost breakdown for a single run, including per-step token counts and costs.
• runAnalytics.getRunContextAnalytics-- Contextual analytics comparing a run's costs to project averages.

Project Counters

In addition to detailed usage records, CodeCourier maintains denormalized counters in the projectCounters table for fast dashboard rendering:

• totalSandboxes / activeSandboxes -- Total and currently running sandbox counts.
• totalRuns / completedRuns / failedRuns -- Run counts by status.
• totalWorkflows -- Number of workflow blueprints.
• totalMembers / pendingInvitations -- Team size and pending invites.

Daily Statistics

The dailyStats table provides pre-aggregated daily activity metrics for each project:

• Sandboxes created per day
• Runs created, completed, and failed per day
• Total iterations across all runs per day
• Workflows created per day

These counters are updated incrementally as operations occur, avoiding expensive aggregation queries on large datasets.

Alerts and Limits

CodeCourier's notification system generates alerts for important events that may affect your costs:

• Run completed / failed -- Notifications when workflow runs finish, helping you stay aware of active operations.
• Sprint completed / failed -- Notifications for sprint chain progress, which can involve multiple sequential runs.
• PR created / merged / failed -- Notifications for pull request lifecycle events.

Since actual billing happens through your external provider accounts, we recommend also setting up spending alerts directly with:

• E2B -- Monitor sandbox usage in the E2B dashboard.
• Anthropic -- Set usage limits in the Anthropic console.
• OpenAI -- Configure spending limits in the OpenAI dashboard.

Optimizing Usage

Token Optimization

• Write focused prompts. Specific, well-scoped prompts reduce both input and output token usage compared to vague instructions.
• Use appropriate models. Assign smaller, faster models (like Sonnet or Haiku) to simple tasks through the persona system. Reserve larger models for complex architectural work.
• Limit iterations. Set reasonable maxIterations on designer-checker workflows. Three to five iterations is usually sufficient.
• Curate learnings. Well-curated learnings reduce wasted iterations by teaching agents to avoid common mistakes.

Sandbox Optimization

• Set appropriate timeouts. Shorter timeouts prevent forgotten sandboxes from running indefinitely.
• Use "Kill All" after sessions. When you are done working, kill all running sandboxes to stop accruing compute charges.
• Use custom templates. Templates with pre-installed dependencies avoid repeated installation time (and the token cost of the agent installing packages).

Workflow Optimization

• Use single designer for simple tasks. Not every task needs a checker. Simple, well-defined tasks can use the single designer workflow type.
• Review run analytics. After completing a batch of runs, review the per-run cost breakdown in the analytics dashboard. Identify runs that were unusually expensive and adjust your workflow configuration accordingly.
• Use issue sessions effectively. A well-structured discovery prompt can reduce per-issue token usage by producing clearer, more focused suggested prompts.

Data Retention

Usage records are retained indefinitely in the Convex database. Daily statistics are pre-aggregated and also retained indefinitely. This allows you to analyze historical trends and compare costs across any time period. If you need to export usage data for external accounting systems, you can query the usage endpoints programmatically through the Convex client library.