Usage

Inspect Sume usage ledger entries and the credit balance.

Open the Usage dashboard for a summary of metered Developer API activity that a person can read. Every amount is in credits. You can get programmatic usage reads from:

The live OpenAPI gives the accurate schemas.

Balance

Field	Meaning
available_credits	The whole credits that the workspace can use now.
state	funded when the workspace has credits, empty when it has none.
updated_at	When the balance last changed.
expiration.next_expires_at	When the next credits expire, or null.
expiration.next_expiring_credits	How many credits expire at next_expires_at.
expiration.expiring_soon_days, expiration.expiring_soon_credits	The credits that expire in the next expiring_soon_days days.

Usage ledger

Usage entries can include reservations, captures, refunds, credit purchases, and grants. The entries change with the workspace and the environment. Each row gives its amount as credits.

Status	Meaning
reserved	Sume reserved the estimated credits before provider execution.
captured	Sume captured the credits after a successful completion.
refunded	Sume returned the reserved credits 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 credits 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_credits	The credits that the wallet deducted: captured rows of every operation type (the agent's own turns are included). Quote this figure.
held_credits	Holds that are still open, with parked pending_* rows included. These credits are not used yet.
pending_credits	The part of held_credits in parked pending_* rows that wait to settle.
refunded_credits	Holds that Sume returned after a failure, cancellation or queue_full. These credits were not used.
final	true when no hold is open.
hold_counts, holds	What the open holds wait on, and the newest holds, each with its credits.
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 credits.
by_operation_type, runs	The same credits by operation type. For a thread, also by run.
cap	For a run: limit_credits (its generation cap), counted_credits (the credits that count against the cap: reserved + captured generation rows, without LLM, the same as the receipt's usage.cap.counted_credits), and remaining_credits. counted_credits is never the run's total. Quote debited_credits for that.

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. Read summary. A refunded row keeps its hold amount in credits.

Credits on a job

GET /v1/jobs, GET /v1/jobs/{id} and GET /v1/jobs/{id}/result give each job a usage_summary:

Field	Meaning
status	reserved, captured, or refunded.
reserved_credits	The credits that Sume reserved when it accepted the job.
captured_credits	The credits that the job used.
refunded_credits, released_credits	The credits that Sume returned to the balance.
final	true when these numbers will not change.

The API rate card shows how many credits each capability uses. This page does not include them.

For plan changes and credit purchases, use Billing & subscription. For how credits work, refer to Billing and credits.