SDKCost tracking

Cost tracking for programs

A program that runs Syntic Code can read what each run cost and stop a run that spends too much. This page covers the fields a run reports and the limit flags. For how spend is estimated and how to reduce it, see Manage costs.

Read the cost of a run

With --output-format json, the result object includes the run’s estimated cost in total_cost_usd, along with the token counts, the turn count and the stop reason:

syntic -p "count the TODOs in src" --output-format json | jq '{cost: .total_cost_usd, turns: .num_turns}'

A stream-json run reports the same figure in its final result message.

The figure is an estimate at list price. Usage covered by your plan is not charged again, so it is useful for comparing tasks and setting budgets, not for reproducing an invoice.

Stop a run at a cost limit

FlagEffect
--max-budget-usd <amount>Stops the run once its estimated cost reaches the amount.
--max-turns <n>Stops the run after n agent turns.
syntic -p "fix the failing test in src/parser" \
  --max-budget-usd 2 --max-turns 30 --output-format json

A run stopped by its budget ends with the result subtype error_max_budget_usd. A run stopped by its turn limit ends with error_max_turns. A script can branch on either subtype.

Where each cost figure comes from

The cost is an estimate computed from the token counts in the run. Where no usage data or no known rate is available for a model, the figure is labelled as an estimate that uses a fallback rate. Cached input is billed at a lower rate than fresh input, so a long run that reuses its context costs less than its raw token count suggests.

A subagent can have its own spend cap: set max-budget-usd (or maxBudgetUsd) in its agent file, or maxBudgetUsd in an --agents definition. Bound the whole run with --max-budget-usd.

Suggested pattern for a pipeline

  1. Set --max-budget-usd and --max-turns on every run in the pipeline.
  2. Record total_cost_usd and the stop reason from each result.
  3. Compare the totals per repository or task before tightening the caps.