Cost Controls
New in v0.9Budget governance and spend tracking for AI operations. Set limits, track spending, and prevent cost overruns.
Overview
Cost Controls provides comprehensive budget management for AI operations. Track spending across providers, set limits at multiple levels, and receive alerts before you exceed budgets.
This is a cloud feature
A budget has to be shared by every process spending against it, so cost controls run server-side. Reach them with
@torknetwork/sdk (npm install @torknetwork/sdk, entry class TorkClient) or the REST API directly. The on-device tork-governance family is a different package — it exports Tork, governs locally, and tracks no spend. There is no Python cloud SDK, so the Python examples below use requests with a Bearer token. Cost APIs require an organization-scoped API key.Budgets
Daily, weekly, monthly, or total spending limits
Transaction Logging
Track every API call with associated cost
Hard Limits
Optionally block requests when budget exceeded
Reports
Breakdown by provider, model, agent, and time
Create a Budget
Create budgets at different levels - per agent, per team, or organization-wide:
python
# Budgets are held server-side by Tork. There is no Python cloud SDK,
# so call the REST API with a Bearer token.
import os, requests
TORK_API = "https://tork.network/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TORK_API_KEY']}"}
# Create daily budget for a specific agent
r = requests.post(f"{TORK_API}/costs/budgets", headers=HEADERS, json={
"budgetName": "Agent-1 Daily Budget",
"budgetType": "daily", # 'daily', 'weekly', 'monthly', 'total'
"budgetAmount": 100.00,
"currency": "USD",
"agentId": "agent-1",
"hardLimit": True, # Block when exceeded
"alertThresholdPercent": 80, # Alert at 80%
})
print(r.json()["budget"])
# Create organization-wide monthly budget
requests.post(f"{TORK_API}/costs/budgets", headers=HEADERS, json={
"budgetName": "Organization Monthly",
"budgetType": "monthly",
"budgetAmount": 5000.00,
"currency": "USD",
"hardLimit": False, # Warn only, don't block
"alertThresholdPercent": 70,
})Check Before Spending
Check if a proposed spend is within budget before making API calls:
python
# Check if proposed spend is allowed
r = requests.post(f"{TORK_API}/costs/check", headers=HEADERS, json={
"agentId": "agent-1",
"proposedCost": 0.05, # Estimated cost of the operation
"proposedTokens": 1200,
})
check = r.json()
if check["allowed"]:
# Make the API call
response = call_llm_api(messages)
# Record the actual transaction
requests.post(f"{TORK_API}/costs/transactions", headers=HEADERS, json={
"agentId": "agent-1",
# 'llm_call', 'embedding', 'tool_call', 'api_call',
# 'storage', 'compute', 'other'
"transactionType": "llm_call",
"totalCost": response.usage.total_cost,
"provider": "openai",
"model": "gpt-4",
"inputTokens": response.usage.prompt_tokens,
"outputTokens": response.usage.completion_tokens,
})
else:
print("Budget exceeded!")
for reason in check["blockingReasons"]:
print(f" {reason}")Get Spend Summary
Get a summary of spending for an agent or the entire organization:
python
# Get spending summary for an agent (agent_id is required)
r = requests.get(f"{TORK_API}/costs/summary", headers=HEADERS, params={
"agent_id": "agent-1",
"period": "monthly", # 'hourly', 'daily', 'weekly', 'monthly'
})
summary = r.json()["summary"]
print(f"Total Spend: ${summary['totalCost']:.2f}")
print(f"Transactions: {summary['transactionCount']}")
print(f"Total tokens: {summary['totalTokens']}")
print(f"Average per transaction: ${summary['averageCostPerTransaction']:.4f}")
print("\nTop providers:")
for provider in summary['topProviders']:
print(f" {provider['provider']}: ${provider['cost']:.2f}")
print("\nTop models:")
for model in summary['topModels']:
print(f" {model['model']}: ${model['cost']:.2f}")
print("\nBudget status:")
for b in summary['budgetStatus']:
print(f" {b['budgetName']}: {b['percentUsed']:.1f}% used, ${b['remaining']:.2f} left")Alert Thresholds
Alerts are triggered at configurable thresholds:
| Alert Type | Severity | Trigger |
|---|---|---|
| threshold_warning | high | 80% of budget used (configurable) |
| budget_exceeded | critical | 100% of budget used |
| anomaly_detected | medium | Unusual spending pattern detected |
| rate_spike | high | Sudden increase in spend rate |
Webhook Notifications
Configure webhooks to receive real-time notifications when budget alerts are triggered. See the Webhooks documentation.
Budget Types
| Type | Reset | Use Case |
|---|---|---|
| daily | Midnight UTC | Prevent runaway costs within a single day |
| weekly | Sunday midnight UTC | Smooth out daily variations |
| monthly | 1st of month UTC | Align with billing cycles |
| total | Never | Lifetime cap for projects or experiments |
MCP Tools
| Tool | Description |
|---|---|
tork_cost_check_budget | Check if a spend is within budget |
tork_cost_record_transaction | Record a cost transaction |
tork_cost_get_summary | Get spending summary |
tork_cost_list_budgets | List all budgets |
tork_cost_get_alerts | Get active budget alerts |