Cost

AI Cost Tracking Protocol

Monitor and control AI API costs with budgets, alerts, and analytics.

Provides cost optimization, budget enforcement, and financial reporting.

Source: packages/spec/src/ai/cost.zod.ts

TypeScript Usage

import { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai';
import type { AIOperationCost, BillingPeriod, BudgetLimit, BudgetStatus, BudgetType, CostAlert, CostAlertType, CostAnalytics, CostBreakdownDimension, CostBreakdownEntry, CostEntry, CostMetricType, CostOptimizationRecommendation, CostQueryFilters, CostReport, TokenUsage } from '@objectstack/spec/ai';

// Validate data
const result = AIOperationCost.parse(data);

AIOperationCost

Properties

Property	Type	Required	Description
operationId	`string`	✅
operationType	`Enum<'conversation' \| 'orchestration' \| 'prediction' \| 'rag' \| 'nlq'>`	✅
agentName	`string`	optional	Agent that performed the operation
modelId	`string`	✅
tokens	`Object`	✅
cost	`number`	✅	Cost in USD
timestamp	`string`	✅
metadata	`Record<string, any>`	optional

BillingPeriod

Allowed Values

hourly
daily
weekly
monthly
quarterly
yearly
custom

BudgetLimit

Properties

Property	Type	Required	Description
type	`Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>`	✅
scope	`string`	optional	Scope identifier (userId, agentId, etc.)
maxCost	`number`	✅	Maximum cost limit
currency	`string`	✅
period	`Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>`	✅
customPeriodDays	`integer`	optional	Custom period in days
softLimit	`number`	optional	Soft limit for warnings
warnThresholds	`number[]`	optional	Warning thresholds (e.g., [0.5, 0.8, 0.95])
enforced	`boolean`	✅	Block requests when exceeded
gracePeriodSeconds	`integer`	✅	Grace period after limit exceeded
allowRollover	`boolean`	✅	Allow unused budget to rollover
maxRolloverPercentage	`number`	optional	Max rollover as % of limit
name	`string`	optional	Budget name
description	`string`	optional
active	`boolean`	✅
tags	`string[]`	optional

BudgetStatus

Properties

Property	Type	Required	Description
budgetId	`string`	✅
type	`Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>`	✅
scope	`string`	optional
periodStart	`string`	✅	ISO 8601 timestamp
periodEnd	`string`	✅	ISO 8601 timestamp
currentCost	`number`	✅
maxCost	`number`	✅
currency	`string`	✅
percentageUsed	`number`	✅	Usage as percentage (can exceed 1.0 if over budget)
remainingCost	`number`	✅	Remaining budget (can be negative if exceeded)
isExceeded	`boolean`	✅
isWarning	`boolean`	✅
projectedCost	`number`	optional	Projected cost for period
projectedOverage	`number`	optional	Projected overage
lastUpdated	`string`	✅	ISO 8601 timestamp

BudgetType

Allowed Values

global
user
agent
object
project
department

CostAlert

Properties

Property	Type	Required	Description
id	`string`	✅
timestamp	`string`	✅	ISO 8601 timestamp
type	`Enum<'threshold_warning' \| 'threshold_critical' \| 'limit_exceeded' \| 'anomaly_detected' \| 'projection_exceeded'>`	✅
severity	`Enum<'info' \| 'warning' \| 'critical'>`	✅
budgetId	`string`	optional
budgetType	`Enum<'global' \| 'user' \| 'agent' \| 'object' \| 'project' \| 'department'>`	optional
scope	`string`	optional
message	`string`	✅	Alert message
currentCost	`number`	✅
maxCost	`number`	optional
threshold	`number`	optional
currency	`string`	✅
recommendations	`string[]`	optional
acknowledged	`boolean`	✅
acknowledgedBy	`string`	optional
acknowledgedAt	`string`	optional
resolved	`boolean`	✅
metadata	`Record<string, any>`	optional

CostAlertType

Allowed Values

threshold_warning
threshold_critical
limit_exceeded
anomaly_detected
projection_exceeded

CostAnalytics

Properties

Property	Type	Required	Description
periodStart	`string`	✅	ISO 8601 timestamp
periodEnd	`string`	✅	ISO 8601 timestamp
totalCost	`number`	✅
totalRequests	`integer`	✅
totalTokens	`integer`	optional
currency	`string`	✅
averageCostPerRequest	`number`	✅
averageCostPerToken	`number`	optional
averageRequestsPerDay	`number`	✅
costTrend	`Enum<'increasing' \| 'decreasing' \| 'stable'>`	optional
trendPercentage	`number`	optional	% change vs previous period
byModel	`Object[]`	optional
byProvider	`Object[]`	optional
byUser	`Object[]`	optional
byAgent	`Object[]`	optional
byOperation	`Object[]`	optional
byDate	`Object[]`	optional
topModels	`Object[]`	optional
topUsers	`Object[]`	optional
topAgents	`Object[]`	optional
tokensPerDollar	`number`	optional
requestsPerDollar	`number`	optional

CostBreakdownDimension

Allowed Values

model
provider
user
agent
object
operation
date
hour
tag

CostBreakdownEntry

Properties

Property	Type	Required	Description
dimension	`Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>`	✅
value	`string`	✅	Dimension value (e.g., model ID, user ID)
totalCost	`number`	✅
requestCount	`integer`	✅
totalTokens	`integer`	optional
percentageOfTotal	`number`	✅
periodStart	`string`	optional
periodEnd	`string`	optional

CostEntry

Properties

Property	Type	Required	Description
id	`string`	✅	Unique cost entry ID
timestamp	`string`	✅	ISO 8601 timestamp
modelId	`string`	✅	AI model used
provider	`string`	✅	AI provider (e.g., "openai", "anthropic")
operation	`string`	✅	Operation type (e.g., "chat_completion", "embedding")
tokens	`Object`	optional	Standardized token usage
requestCount	`integer`	✅
promptCost	`number`	optional	Cost of prompt tokens
completionCost	`number`	optional	Cost of completion tokens
totalCost	`number`	✅	Total cost in base currency
currency	`string`	✅
sessionId	`string`	optional	Conversation session ID
userId	`string`	optional	User who triggered the request
agentId	`string`	optional	AI agent ID
object	`string`	optional	Related object (e.g., "case", "project")
recordId	`string`	optional	Related record ID
tags	`string[]`	optional
metadata	`Record<string, any>`	optional

CostMetricType

Allowed Values

token
request
character
second
image
embedding

CostOptimizationRecommendation

Properties

Property	Type	Required
id	`string`	✅
type	`Enum<'switch_model' \| 'reduce_tokens' \| 'batch_requests' \| 'cache_results' \| 'adjust_parameters' \| 'limit_usage'>`	✅
title	`string`	✅
description	`string`	✅
estimatedSavings	`number`	optional
savingsPercentage	`number`	optional
priority	`Enum<'low' \| 'medium' \| 'high'>`	✅
effort	`Enum<'low' \| 'medium' \| 'high'>`	✅
actionable	`boolean`	✅
actionSteps	`string[]`	optional
targetModel	`string`	optional
alternativeModel	`string`	optional
affectedUsers	`string[]`	optional
status	`Enum<'pending' \| 'accepted' \| 'rejected' \| 'implemented'>`	✅
implementedAt	`string`	optional

CostQueryFilters

Properties

Property	Type	Required	Description
startDate	`string`	optional	ISO 8601 timestamp
endDate	`string`	optional	ISO 8601 timestamp
modelIds	`string[]`	optional
providers	`string[]`	optional
userIds	`string[]`	optional
agentIds	`string[]`	optional
operations	`string[]`	optional
sessionIds	`string[]`	optional
minCost	`number`	optional
maxCost	`number`	optional
tags	`string[]`	optional
groupBy	`Enum<'model' \| 'provider' \| 'user' \| 'agent' \| 'object' \| 'operation' \| 'date' \| 'hour' \| 'tag'>[]`	optional
orderBy	`Enum<'timestamp' \| 'cost' \| 'tokens'>`	✅
orderDirection	`Enum<'asc' \| 'desc'>`	✅
limit	`integer`	optional
offset	`integer`	optional

CostReport

Properties

Property	Type	Required	Description
id	`string`	✅
name	`string`	✅
generatedAt	`string`	✅	ISO 8601 timestamp
periodStart	`string`	✅	ISO 8601 timestamp
periodEnd	`string`	✅	ISO 8601 timestamp
period	`Enum<'hourly' \| 'daily' \| 'weekly' \| 'monthly' \| 'quarterly' \| 'yearly' \| 'custom'>`	✅
analytics	`Object`	✅
budgets	`Object[]`	optional
alerts	`Object[]`	optional
activeAlertCount	`integer`	✅
recommendations	`Object[]`	optional
previousPeriodCost	`number`	optional
costChange	`number`	optional	Change vs previous period
costChangePercentage	`number`	optional
forecastedCost	`number`	optional
forecastedBudgetStatus	`Enum<'under' \| 'at' \| 'over'>`	optional
format	`Enum<'summary' \| 'detailed' \| 'executive'>`	✅
currency	`string`	✅

TokenUsage

Properties

Property	Type	Required	Description
prompt	`integer`	✅	Input tokens
completion	`integer`	✅	Output tokens
total	`integer`	✅	Total tokens

On this page