Check credits from a script: sume balance and sume usage get

Run sume balance for the workspace balance and sume usage get --limit 20 for recent ledger rows, or call GET /v1/balance and GET /v1/usage. Both are read-only and scoped to the workspace of the API key. Do this before a paid batch, and still handle 402 insufficient_credits, because a balance is a snapshot.

Everything here is from the Command reference, Usage and Billing and credits, read 2026-09-30.

Which command reads what?

The CLI reads its key from SUME_API_KEY and its API base from SUME_API_BASE_URL (default https://api.sume.com/v1), so a CI job only needs the secret set.

How do I gate a job on it?

Read the balance, compare it with your own estimate for the batch, and stop early if it is short. Top-ups are a dashboard operation: the public API exposes balance and usage reads, not a top-up endpoint.

curl https://api.sume.com/v1/balance \
  -H "Authorization: Bearer $SUME_API_KEY"

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

What if it changes mid-batch?

Estimated usage is reserved at submit, so a later submit can still fail with 402 insufficient_credits before provider work starts. Treat that as a stop, not a retry, and add funds as described in Billing and credits.

How do I total one run or job?

Add run_id, job_id or thread_id to /v1/usage and quote summary.debited_usd. Never sum rows yourself, since a refunded row keeps its hold amount.