> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost tracking

> Public cost tracking signatures and configuration in @agentium/core 4.0.0.

Import these **9 exports** from `@agentium/core`. Read the [cost tracking guide](/cost/overview) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## CostBreakdown

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface CostBreakdown {
    input: number;
    output: number;
    reasoning: number;
    cached: number;
    audioInput: number;
    audioOutput: number;
    total: number;
}
```

## CostBudget

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface CostBudget {
    maxCostPerRun?: number;
    maxCostPerSession?: number;
    maxCostPerUser?: number;
    maxTokensPerRun?: number;
    onBudgetExceeded?: "throw" | "warn";
}
```

## CostEntry

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface CostEntry {
    runId: string;
    agentName: string;
    modelId: string;
    usage: TokenUsage;
    cost: number;
    breakdown: CostBreakdown;
    timestamp: Date;
    sessionId?: string;
    userId?: string;
}
```

Related: [`CostBreakdown`](/api-reference/core/cost#costbreakdown), [`TokenUsage`](/api-reference/core/models#tokenusage).

## CostSummary

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface CostSummary {
    totalCost: number;
    totalTokens: TokenUsage;
    totalBreakdown: CostBreakdown;
    entries: number;
    byAgent: Record<string, {
        cost: number;
        breakdown: CostBreakdown;
        tokens: TokenUsage;
        runs: number;
    }>;
    byModel: Record<string, {
        cost: number;
        breakdown: CostBreakdown;
        tokens: TokenUsage;
    }>;
    byUser: Record<string, {
        cost: number;
        breakdown: CostBreakdown;
        tokens: TokenUsage;
    }>;
}
```

Related: [`CostBreakdown`](/api-reference/core/cost#costbreakdown), [`TokenUsage`](/api-reference/core/models#tokenusage).

## CostTracker

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/cost-tracker.ts)

```typescript theme={null}
export declare class CostTracker {
    constructor(config?: CostTrackerConfig);
    track(entry: Omit<CostEntry, "cost" | "breakdown" | "timestamp">): CostEntry;
    checkBudget(runId: string, sessionId?: string, userId?: string): void;
    getSummary(filter?: {
        agentName?: string;
        userId?: string;
        since?: Date;
    }): CostSummary;
    /**
     * Check budget using in-progress (cumulative) usage without persisting an entry.
     * Called during multi-roundtrip runs (e.g. tool calling) to enforce limits mid-run.
     */
    checkInProgressBudget(modelId: string, cumulativeUsage: TokenUsage, runId?: string, sessionId?: string, userId?: string): boolean;
    /** @deprecated Use checkInProgressBudget for mid-run checks. This now delegates to it. */
    isBudgetExceeded(runId: string, sessionId?: string, userId?: string): boolean;
    estimateRemaining(runId: string): {
        costRemaining: number | null;
        tokensRemaining: number | null;
    };
    getEntries(): readonly CostEntry[];
    reset(): void;
}
```

Related: [`CostEntry`](/api-reference/core/cost#costentry), [`CostSummary`](/api-reference/core/cost#costsummary), [`CostTrackerConfig`](/api-reference/core/cost#costtrackerconfig), [`TokenUsage`](/api-reference/core/models#tokenusage).

## CostTrackerConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface CostTrackerConfig {
    pricing?: Record<string, ModelPricing>;
    budget?: CostBudget;
}
```

Related: [`CostBudget`](/api-reference/core/cost#costbudget), [`ModelPricing`](/api-reference/core/cost#modelpricing).

## DEFAULT\_PRICING

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/pricing.ts)

```typescript theme={null}
export declare const DEFAULT_PRICING: Record<string, ModelPricing>;
```

Related: [`ModelPricing`](/api-reference/core/cost#modelpricing).

## lookupPricing

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/pricing.ts)

```typescript theme={null}
export declare function lookupPricing(modelId: string, customPricing?: Record<string, ModelPricing>): ModelPricing | undefined;
```

Related: [`ModelPricing`](/api-reference/core/cost#modelpricing).

## ModelPricing

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/cost/types.ts)

```typescript theme={null}
export interface ModelPricing {
    promptPer1k: number;
    completionPer1k: number;
    reasoningPer1k?: number;
    cachedPromptPer1k?: number;
    audioInputPer1k?: number;
    audioOutputPer1k?: number;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.