The Problem
AI agents with web search tools can run up costs quickly. A poorly constrained agent loop might execute 500 search queries to answer a single question, costing $2.50 at $0.005/query. Without budget guardrails, agents in production can generate unexpected API bills. Most search APIs do not provide per-session or per-task budget controls, leaving teams to build their own usage tracking and enforcement.
The Scavio Solution
Wrap Scavio API calls in a budget-aware function that tracks cumulative cost per agent session and refuses to execute searches once the budget is exhausted. Set per-task budgets (e.g., $0.50 max per user query) and per-day budgets. The wrapper returns a clear error when the budget is hit, allowing the agent to gracefully fall back to its training data instead of failing silently.
Before
Before guardrails, one production agent session accidentally executed 2,000 search queries in a loop, costing $10 for a single user question. The team only discovered it when the monthly bill was unexpectedly high.
After
After adding budget guardrails, per-session costs are capped at $0.50. Runaway loops hit the budget limit and return a clear message. Monthly costs became predictable and controllable.
Who It Is For
AI engineers running agents in production who need cost controls on search API usage. Platform teams building agent infrastructure where per-user or per-session budgets are required.
Key Benefits
- Per-session and per-day budget caps prevent runaway costs
- Clear error message when budget is exhausted enables graceful fallback
- Cost tracking per task enables usage analytics and billing attribution
- Works with any agent framework or plain function-calling patterns
- At $0.005/query, a $0.50 session budget allows 100 searches per task
Python Example
import requests
from dataclasses import dataclass, field
API_KEY = "your_scavio_api_key"
COST_PER_QUERY = 0.005
@dataclass
class BudgetTracker:
max_budget: float = 0.50
spent: float = 0.0
queries: int = 0
def can_search(self) -> bool:
return self.spent + COST_PER_QUERY <= self.max_budget
def record(self):
self.spent += COST_PER_QUERY
self.queries += 1
def budget_search(query: str, budget: BudgetTracker, platform: str = "google") -> dict:
if not budget.can_search():
return {"error": "budget_exhausted", "spent": budget.spent, "queries": budget.queries}
res = requests.post(
"https://api.scavio.dev/api/v1/search",
headers={"x-api-key": API_KEY},
json={"platform": platform, "query": query},
timeout=15,
)
res.raise_for_status()
budget.record()
return {"results": [r.get("title", "") for r in res.json().get("organic", [])[:5]], "spent": budget.spent, "remaining": budget.max_budget - budget.spent}
budget = BudgetTracker(max_budget=0.10)
for i in range(25):
result = budget_search(f"query {i}", budget)
if "error" in result:
print(f"Budget exhausted after {budget.queries} queries (${budget.spent:.3f})")
break
print(f"Query {i}: ${budget.spent:.3f} spent, ${result['remaining']:.3f} remaining")JavaScript Example
const API_KEY = "your_scavio_api_key";
const COST = 0.005;
class BudgetTracker {
constructor(max = 0.50) { this.max = max; this.spent = 0; this.queries = 0; }
canSearch() { return this.spent + COST <= this.max; }
record() { this.spent += COST; this.queries++; }
}
async function budgetSearch(query, budget, platform = "google") {
if (!budget.canSearch()) return { error: "budget_exhausted", spent: budget.spent };
const res = await fetch("https://api.scavio.dev/api/v1/search", {
method: "POST",
headers: { "x-api-key": API_KEY, "content-type": "application/json" },
body: JSON.stringify({ platform, query }),
});
if (!res.ok) throw new Error(`scavio ${res.status}`);
budget.record();
return { results: ((await res.json()).organic ?? []).slice(0, 5).length, remaining: budget.max - budget.spent };
}
const budget = new BudgetTracker(0.10);
for (let i = 0; i < 25; i++) {
const r = await budgetSearch(`query ${i}`, budget);
if (r.error) { console.log(`Budget exhausted after ${budget.queries} queries ($${budget.spent.toFixed(3)})`); break; }
console.log(`Query ${i}: $${budget.spent.toFixed(3)} spent`);
}Platforms Used
Web search with knowledge graph, PAA, and AI overviews
Community, posts & threaded comments from any subreddit