Agent run cost on Sume: quote debited_usd_micros, not held

To say what an agent run or a job cost on Sume, call usage_get with a thread_id, run_id or job_id and quote summary.debited_usd_micros. The figure is in millionths of a dollar. That is the spend the tool description tells you to report. held_usd_micros and refunded_usd_micros are not spend, and you should not add up the rows yourself. The tool is listed under account and catalog on the MCP tools and gates page.

Which number is which?

Why does final=false matter?

A run reserves money before it spends it. While a hold is open the debited figure can still rise, so reading it early undercounts. When final is false, wait for the job with jobs_wait and call usage_get again. An agent run also has a cap: generation_spend_cap_usd is required on Agent Completions, and the receipt's usage shows the cap in micros. The cap is a ceiling, not the bill. See Agent Completions.

How do I price twenty jobs?

Do it in one call rather than twenty. script_run runs a JavaScript body with sume.tools.usage_get and returns only the numbers you pick, so the model's context holds twenty small values and no raw rows. Inside a script, calls run four at a time, and a script defaults to 32 calls with a ceiling of 64. Check the shape of one result in calls[] before you trust the field path in the sketch.

const rows = [];
for (const id of args.job_ids) {
  const r = await sume.tools.usage_get({ job_id: id });
  rows.push({ id, usage: r });
}
return rows.map((x) => ({
  id: x.id,
  debited: x.usage?.summary?.debited_usd_micros ?? null,
  final: x.usage?.final ?? null,
}));

What should the report say?

Report the debited total only for rows where final is true, and list the rest as pending. Divide micros by 1,000,000 for dollars, so 240000 is $0.24. Do not mix the cap into the sum; a run with a 2-dollar cap that debited 0.24 cost 0.24. The optional limit on usage_get defaults to 20, so pass an id to scope the answer rather than paging a whole wallet.

For long renders, wait first with jobs_wait, which takes up to 20 ids and holds up to 55 seconds, as Jobs and results explains.

Where does the number come from?

The debited figure is the amount Sume actually took from the wallet for that id. Admission checks the wallet before a job starts, which is why a hold exists, and the hold turns into a debit or a refund when the job ends. That lifecycle is the reason a mid-run read can look low, and a read after a failed job can show a refund. Quote the settled value, and say so in the report.