Skip to main content
connic
Platform

Usage & Budgets

Token usage and costs are tracked by currency through charts, agent rankings, alerts, hard limits, and anomaly detection. Full project credit is managed separately in Billing.

Last updated

Overview

The Token Usage page shows token consumption and token cost. connic/* charges use EUR. BYOK usage keeps the USD or EUR currency configured for that model; when a Project uses both currencies, both values are shown unless Cost Display converts them to EUR or USD.

Token analytics and Project billing
Token Usage covers model tokens. The Project Billing page shows the complete Project credit balance and consumption across LLM run starts, completed judge evaluations, runtime, web searches, extracted pages and browser sessions, storage, file storage and downloads, retrieval, and connic/* tokens. Standard Projects can add prepaid credit or enable capped auto-refill; enterprise Projects have custom commercial terms.
Token Cost
Daily token cost broken down by agent and currency, with monthly comparisons.
Token Cost Alerts
Configurable notifications when token cost crosses a threshold. Global, per-environment, or per-agent.
Hard Limits
Prevent matching queued runs from starting when a spending threshold is reached. Runs outside the limit's scope continue unaffected.
Anomaly Detection
Automatic alerts when a single agent run costs significantly more than its 30-day rolling average.

Daily Token Cost Chart

The chart at the top of the Token Usage page shows a stacked bar for each day of the month, broken down by agent, model, or context value. Judge evaluation tokens are included in each agent's total.

By Context groups token cost by a value that middleware or tools write to the run context, such as customer_id or use_case. Enter the key next to the tabs, with dots for nested keys such as customer.id. Runs without the key appear as (not set).

Use the month selector to navigate between months. The chart goes back to the month the project was created.

Token Usage page showing summary cards above a daily stacked bar chart, with each day's bar broken down by agent
The Token Usage page: summary cards above a per-day stacked bar chart, with each bar broken down by agent.

Summary Cards

Three summary cards appear above the chart:

CardDescription
Current TotalTotal token cost for the selected month. For the current month, also shows the projected total based on daily average so far.
Last MonthToken cost and token usage for the previous month, shown in each currency that has a value.
TrendAmount and percentage difference from the previous month, calculated for each displayed currency.

Agent Ranking

Below the chart, the table shows every agent, model, or context value for the selected month. Sort by name, run count, or any displayed currency; EUR and USD remain separate columns when both are present.

The REST endpoints budgets/daily-cost and budgets/agent-ranking accept the same grouping, for example group_by=context.customer_id.

Each agent row includes a full token cost breakdown:

Agent ranking table with each agent's cost broken down into Total, Input, Output, Thinking, Cached, and Judge columns
The agent ranking table, with each agent's token cost broken down by category.
ColumnDescription
Token CostCombined cost across all token categories, judge evaluations and external costs.
InputCost of prompt/input tokens (excluding cached and cache-write portions).
OutputCost of model output tokens.
ThinkingCost of reasoning/thinking tokens (when enabled).
CachedCost of cached input tokens using the configured cached rate, where available.
Cache WriteCost of input tokens written to the prompt cache using the configured cache-write rate, where available.
ExternalCosts from outside connic recorded on the agent's runs. See External Costs.
JudgeCost of judge evaluation runs associated with this agent.

External Costs

Record costs from outside connic, such as a translation or OCR service, on the run that caused them. They show on the run and count in its cost, on this page, in dashboards, and in token cost alerts and limits. connic never bills them.

Call record_cost from a tool or middleware. currency is EUR or USD; description, quantity, unit and external_id are optional.

tools/translation.py
import os
from decimal import Decimal
import httpx
from connic.tools import record_cost

PRICE_PER_CHARACTER = Decimal("0.00002")

async def translate(text: str, target_language: str) -> str:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://translate.example.com/v1/translate",
            headers={"Authorization": f"Bearer {os.environ['TRANSLATION_API_KEY']}"},
            json={"text": text, "target": target_language},
        )
    result = response.json()
    await record_cost(
        "translation",
        PRICE_PER_CHARACTER * len(text),
        "EUR",
        quantity=len(text),
        unit="characters",
        external_id=result["id"],
    )
    return result["translation"]

For costs known only after the run, such as a price the provider reports later, use POST /v1/projects/{project_id}/runs/{run_id}/cost-items with an API key that has the Record external costs on runs permission, or the record_run_costs MCP tool. Recording an external_id the run already holds replaces that item, so retries and corrected prices don't count twice. A run holds up to 1,000 items.

Token Cost Alerts & Limits

Token cost alerts and limits act on model-token cost plus external costs, not the complete Project credit balance. Each entry has a type, scope, period, and threshold amount in either EUR or USD.

Alert vs. Limit

AlertNotification only
Sends enabled member and project-channel notifications when the threshold is crossed. Agents continue running normally.
LimitQueue hold
Sends a notification and prevents matching queued runs from starting. Runs remain queued until the limit is raised, removed, disabled, or its next period begins.

Scope

Each alert or limit has one of these scopes:

ScopeBehavior
GlobalApplies to all token cost across the project. A reached global limit prevents queued runs from starting while it is active.
EnvironmentApplies to one or more specific environments. A reached environment limit prevents queued runs for those environments from starting while it is active.
AgentApplies to one or more agents by name. A reached agent limit prevents matching queued runs from starting while it is active; other agents continue normally.

Period

Choose whether the threshold resets daily or monthly:

  • Monthly: Token cost is accumulated from the 1st of the month. Resets on the 1st of the next month.
  • Daily: Token cost resets at midnight UTC each day.

Progress Tracking

Each alert and limit shows a visual progress bar when every applicable model call has an exact token cost. If a call cannot be priced, the current value is shown as unavailable instead of displaying a partial total.

How Limits Release Runs
Affected queued runs carry a reference to the specific limit. They are released when the limit is deleted, disabled, raised above the applicable spend, or its next period begins. A project banner indicates that a budget limit is active.

Token Cost Anomaly Detection

When enabled, connic compares each completed run's token cost with that agent's 30-day rolling average. If a run is significantly more expensive than normal, an alert is sent.

Configuration

SettingDescription
EnabledToggle anomaly detection on or off for the project.
MultiplierThe threshold multiplier. Default is 3x, meaning a run is flagged if it costs more than 3 times the rolling average.
Minimum Data Requirement
Anomaly detection requires at least 5 completed runs for a given agent in the preceding 30 days. Agents with fewer runs are skipped.

Token Cost Reports

Automated email reports keep EUR and USD token costs separate and include only the currencies used during the reporting period. Reports clearly mark incomplete coverage and omit calls without exact costs from cost rankings. Two report types are available:

Weekly Report
Sent every Monday at 9:00 UTC. Covers the preceding 7 days and includes token cost and token totals by agent plus the top 10 runs by token cost in each currency.
Monthly Report
Sent on the 1st of each month at 9:00 UTC. Covers the preceding calendar month and includes token cost and token totals by agent plus the top 10 runs by token cost in each currency.

Enable or disable each report type from the Token Usage page. Delivery preferences (which team members receive the email) can be managed in Settings > Notifications, where token cost reports appear as dedicated notification types.

Notification Settings

Token-cost events are integrated into the Project notification system. Each team member can independently control which notifications they receive and through which channel.

Event TypeEmailIn-AppDescription
Token Cost Alert TriggeredYesYesA token-cost threshold was crossed.
Token Cost Limit TriggeredYesYesA hard limit was reached and matching runs are held.
Token Cost Anomaly DetectedYesYesA run's token cost significantly exceeded its rolling average.
Weekly Token Cost ReportYesN/AEmail-only weekly token-cost summary.
Monthly Token Cost ReportYesN/AEmail-only monthly token-cost summary.

Member preferences are managed under Settings > Notifications. Spend reports are email-only. Enterprise projects can route token-cost alerts, limits, and anomalies to a signed webhook channel.

How token costs are calculated

Token Usage recalculates recorded model calls from the pricing currently configured in connic. connic/* costs use the current published EUR catalog rate, while BYOK costs use the current USD or EUR pricing definition that applies to the call date. Reporting currencies stay separate unless the project's Cost Display setting in Token Pricing settings converts them to EUR or USD. Conversion uses the European Central Bank daily reference rate for each call date, so converted totals are estimates and can differ from provider bills. These reporting values do not change the Project-credit debit recorded for managed inference.

The five token categories (input, output, thinking, cached input, cache write) are priced independently. Cached input and cache-write tokens are subsets of input tokens. Cached input is charged at the published cached rate when the supplier reports a cache hit, and cache writes at the published cache-write rate when the supplier reports tokens written to its prompt cache. Without a published cache rate, these tokens use the input rate. Audio tokens can have separate rates within each category. Select Text or Audio in the pricing drawer to configure its base prices and tiers; audio usage is included in the totals once.

BYOK pricing configuration
BYOK token pricing is managed under Settings > Token Pricing. Each entry uses USD or EUR. Editing a pricing definition recalculates recorded token costs, and effective dates select the definition according to each call date. Entries can use regex patterns for model-name variants.