Usage
Open the Usage dashboard for a summary of metered Developer API activity that a person can read. You can get programmatic usage reads from:
The live OpenAPI gives the accurate schemas.
Balance
The balance is in USD. Compatibility fields can show rounded cent values as credits.
Usage ledger
Usage entries can include reservations, captures, refunds, top-ups, and grants. The entries change with the workspace and the environment.
| Status | Meaning |
|---|---|
reserved | Sume reserved the estimated usage before provider execution. |
captured | Sume captured the billable usage after a successful completion. |
refunded | Sume released the reserved usage after a failure or a cancellation before capture. |
Use job ids and request ids to correlate usage rows with generation workflows.
One thread, one run, one job
Add thread_id, run_id or job_id to the request. Then the response gives
the accurate cost of one Studio Agent thread, one Format / Action / Agent run,
or one generation job:
The response adds summary. The summary folds over every ledger row that the
scope caused (limit only caps the listed rows):
| Field | Meaning |
|---|---|
debited_usd_micros, debited_usd | The amount that the wallet deducted: captured rows of every operation type (the agent's own turns are included). Quote this figure. |
held_usd_micros | Holds that are still open, with parked pending_* rows included. This is not spend yet. |
refunded_usd_micros | Holds that Sume gave back after a failure, cancellation or queue_full. This is not spend. |
final | true when no hold is open. |
includes | Row counts by kind: LLM turns, sidecars, Browser sessions, generation jobs, script_run_children (jobs that a script_run call dispatched), refunded rows, and BYOK rows. |
script_runs | The script_run calls in the scope. Each call has its rows and money. |
by_operation_type, runs | The same money by operation type. For a thread, also by run. |
cap | For a run: its generation cap, the amount that counts against the cap, and the amount that is left. The amount against the cap is reserved + captured generation rows, without LLM (the receipt's billable_amount_usd_micros). This value is never a cost. |
Rows keep their ledger ids. Rows now also carry thread_id, run_id,
turn_job_id (the agent turn that commissioned the job), script_run_id /
script_run_call_index (when a script_run dispatched the job) and
settle_state. job_id also accepts the job id of a turn. Then the sum
includes the turn's own row and every job that the turn commissioned. Never sum
the rows yourself. A refunded row keeps its hold amount in
billable_amount_usd_micros.
The API pricing page gives the metered rates for each capability. This page does not include them. Sume generates the pricing page from the same pricing constants that the API uses for bills.
For plan changes and top-ups, use Billing & subscription.