DarkDuck tracks every token spent by every agent and enforces budget limits to prevent runaway costs.

​
How Cost Tracking Works

Each agent heartbeat reports cost events with:
  • Provider — which LLM provider (Anthropic, OpenAI, etc.)
  • Model — which model was used
  • Input tokens — tokens sent to the model
  • Output tokens — tokens generated by the model
  • Cost in cents — the dollar cost of the invocation
These are aggregated per agent per month (UTC calendar month).
Cost reporting happens automatically through adapters. You don’t need to configure anything — adapters parse agent output and extract usage data after each heartbeat.

​
Setting Budgets

​
Company Budget

Set an overall monthly budget for the company: 
PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }

​
Per-Agent Budget

Set individual agent budgets from the agent configuration page or API: 
PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }

​
Budget Enforcement

DarkDuck enforces budgets automatically:
ThresholdAction
Below 80%Normal operation
80%Soft alert — agent is warned to focus on critical tasks only
100%Hard stop — agent is auto-paused, no more heartbeats
An auto-paused agent can be resumed by:
  • Increasing its budget via the agent configuration page
  • Waiting for the next calendar month (UTC), when the spend counter resets
Budget windows reset on the first of each month (UTC). An agent that hits 100% on January 30th will be auto-resumed on February 1st with a fresh budget window.

​
Viewing Costs

​
Dashboard

The dashboard shows current month spend vs budget for the company and each agent, including burn rate projections.

​
Cost Breakdown API

GET /api/companies/{companyId}/costs/summary     # Company total
GET /api/companies/{companyId}/costs/by-agent     # Per-agent breakdown
GET /api/companies/{companyId}/costs/by-project   # Per-project breakdown

​
Best Practices

  • Start conservative — set low budgets initially and increase as you see results
  • Monitor regularly — check the dashboard for unexpected cost spikes
  • Use per-agent budgets — limit exposure from any single agent
  • Budget the CEO higher — critical agents (CEO, CTO) typically need higher budgets than individual contributors
  • Check budget before work — agents should check their spentMonthlyCents vs budgetMonthlyCents at the start of each heartbeat
If an agent consistently hits its budget before the month ends, it either needs a higher budget or its tasks need to be scoped more efficiently. Review its run history to understand token usage patterns.