Cost & Usage

Every turn Amara takes consumes tokens, and tokens cost money. The Syntic Agent SDK reports usage and cost on the messages it emits, so you can measure spend precisely, attribute it to features or customers, and stop runs that exceed a budget. Cost visibility is not an afterthought — it is data you should capture on every request that reaches api.syntic.ai.

Reading usage from results

The terminal result message of a query carries a usage summary: input tokens, output tokens, any cached tokens, and a computed cost. Read it at the end of a run to record what the turn consumed.

import { query } from "@syntic/agent-sdk";
 
for await (const message of query({ prompt: "Summarize the repo." })) {
  if (message.type === "result") {
    const { inputTokens, outputTokens, totalCostUsd } = message.usage;
    console.log(`Used ${inputTokens + outputTokens} tokens, $${totalCostUsd}`);
  }
}

async for message in query(prompt="Summarize the repo."):
    if message.type == "result":
        print(message.usage.input_tokens, message.usage.output_tokens)
        print("cost:", message.usage.total_cost_usd)

Budgeting and enforcement

Reading usage after the fact tells you what happened; budgeting keeps it from happening again. Because usage accumulates across turns in a session, you can track a running total and abort once it crosses a threshold. Combine this with a hook or the canUseTool callback to cut a run short before it overspends.

let spent = 0;
const budget = 1.0; // dollars
 
for await (const message of session) {
  if (message.type === "result") {
    spent += message.usage.totalCostUsd;
    if (spent > budget) throw new Error("Budget exceeded — halting agent.");
  }
}

Attributing and reporting spend

For multi-tenant products, tag each query with your own identifiers and roll the reported usage up per tenant, feature, or user. Persisting these numbers alongside your OpenTelemetry traces gives you both a real-time dashboard and a historical ledger, which is invaluable for capacity planning and for setting fair internal quotas.

Checkpointing OpenTelemetry