Cost of one Sume agent thread or turn: /v1/usage thread_id and job_id

To get what one Studio Agent thread cost on Sume, call GET /v1/usage?thread_id=.... The summary.debited_usd field is the dollar figure the docs tell you to quote. To get one agent turn, pass the turn's job id as job_id: it sums the turn's own row plus every job the turn commissioned.

All of this is in the Usage docs and the OpenAPI schema for /v1/usage.

What does each scope parameter sum?

Each scope parameter folds a different set of ledger rows, and the three can be used one at a time. Choose the narrowest one that matches the thing you want to price, because the summary covers the whole scope.

Which row fields link a job back to a turn?

Rows carry thread_id, run_id, turn_job_id (the agent turn that commissioned the job), and, for jobs dispatched by an MCP script_run call, script_run_id and script_run_call_index. The summary's includes field counts rows by kind, including script_run_children, and by_operation_type splits the same money by operation.

A thread-bound credential may name only its own thread, according to the schema, so a scoped key cannot read another thread's cost.

curl "https://api.sume.com/v1/usage?thread_id=$SUME_THREAD_ID&limit=1" \
  -H "Authorization: Bearer $SUME_API_KEY"

Is the number spend yet?

Only debited_usd_micros is spend. held_usd_micros is holds still open and refunded_usd_micros is money given back after a failure or cancellation, and neither is spend. final turns true once no hold is open. If a thread is still running, read the figure again later.

What should I do with it?

Keep the thread figure and the cap apart in whatever you report.

• Log debited_usd and final next to each thread you bill.
• Use job_id with a turn id when you need the cost of one prompt.
• Keep the cap and the cost apart: for a run, summary.cap shows what counts against its generation cap, and the docs say it is never a cost.