Sume GET /v1/balance expiration fields: warn before credits lapse

GET https://api.sume.com/v1/balance returns an expiration object next to your spendable amount: next_expires_at, the amount in that lot, and an expiring_soon amount with the number of days it covers. Poll it once a day and alert when expiring_soon_amount_usd_micros is above zero, so a lot does not lapse unnoticed.

The fields below are from the live OpenAPI document (read 2026-10-10) and the API source in the repository, not from a docs prose page. The Billing and credits page only says that balance and usage are read-only endpoints.

What does the balance object contain?

The response is wrapped in data.balance. Money comes in three shapes that all describe the same amount: available_amount_usd_micros (the exact one), available_amount_usd_cents (rounded down), and available_credits (a legacy rounded cent amount kept for compatibility). Use micros for any arithmetic. One US dollar is 1,000,000 micros.

A daily check in Python

The script uses only the standard library. It prints the state, the next lot, and a warning line you can pipe into whatever alerting you already run. Cents fields are rounded down, so do not sum them across lots; sum micros.

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.sume.com/v1/balance",
    headers={"x-api-key": os.environ["SUME_API_KEY"],
                              "User-Agent": "sume-example/1.0"})
with urllib.request.urlopen(req, timeout=30) as r:
    bal = json.load(r)["data"]["balance"]

exp = bal["expiration"]
usd = lambda micros: micros / 1_000_000
print("state:", bal["state"], "available $%.2f" % usd(bal["available_amount_usd_micros"]))
if exp["next_expires_at"]:
    print("next lot: $%.2f expires %s" % (
        usd(exp["next_expiring_amount_usd_micros"]), exp["next_expires_at"]))
if exp["expiring_soon_amount_usd_micros"] > 0:
    print("WARNING: $%.2f expires within %d days" % (
        usd(exp["expiring_soon_amount_usd_micros"]), exp["expiring_soon_days"]))

How is an empty balance different from a 402?

A missing balance row is reported as an explicit zero with state: "empty", not as an internal error. That is a read. The 402 insufficient_credits error is a different event: it happens on a generation submit when Sume cannot reserve the estimated cost from the workspace balance, and it is raised before any provider work starts.

So the balance read is a cheap preflight, but it is not a guarantee. Another job can reserve funds between your read and your submit, and the estimate for a given request is the thing that must fit. Keep handling 402 on submit. Per the errors page, the fix is to add funds or lower the request cost, not to retry the same call.

What the API cannot do for you

Top-ups are a dashboard operation. The credits page states that the public Developer API gives balance and usage reads and has no endpoint to create a top-up. So your alert should notify a human, or open a ticket, and not try to buy credit on its own.

Also note that the expiry numbers describe credit lots, not your plan's concurrency. Concurrency is plan-only and prepaid top-ups do not raise it, as the generation admission page explains.

• Alert on expiring_soon_amount_usd_micros > 0, not on state alone: a funded balance can still be about to shrink.
• Log next_expires_at as a timestamp so the alert is deduplicated per lot.
• Treat any non-2xx on this read as a monitoring failure, not as an empty wallet.