Core Concepts
Tasks, events, cost confidence, and retry tracking.
Tasks
A task is a business operation your AI agent performs -- "resolve support ticket", "generate report", "classify document". Every task has:
- A type (what kind of work)
- A customer (who it serves)
- A status (pending, success, or failed)
- Aggregated costs rolled up from all events inside it
Tasks can be nested. A parent task can contain child tasks, and costs roll up through the hierarchy.
Events
An event is a single cost-generating action within a task. There are four types:
| Event Type | Description | Example |
|---|---|---|
llm_call | An LLM API call with token usage and cost | gpt-4o completion, $0.032 |
external_cost | A non-LLM paid API call | Stripe charge, Pinecone query |
compute_cost | Infrastructure or compute cost | Lambda execution, GPU time |
retry_marker | A retry event (retry cost tracking) | Rate-limited call repeated |
Cost confidence
Every cost event carries a confidence level indicating how the cost was determined:
| Level | Meaning |
|---|---|
exact | Cost came directly from the provider response or was manually set |
computed | Cost was computed from token counts and dexcost's pricing data |
estimated | Cost is an approximation (e.g., compute time estimation) |
unknown | Cost could not be determined |
Retry tracking
dexcost treats retry cost as a first-class metric. When an LLM call fails due to a transient error (rate limit, timeout, 5xx) and is retried, the retry cost is tracked separately.
Two detection modes:
- Manual -- call
task.mark_retry(reason)explicitly in your error handling - Heuristic -- enable automatic detection with
enable_retry_heuristics=True. dexcost uses a sliding-window algorithm to detect likely retries based on timing and error patterns.
Attribution
Every task carries optional customer_id and project_id fields. When set, all costs within that task are attributed to that customer and project, enabling per-customer profitability analysis in the dashboard.