Skip to main content

Low balance warnings

Pods are billed every 5 minutes. Lium warns you before your balance runs out.

The three warnings​

  • Your own threshold: one email when your runway or balance drops below what you set.
  • 60 minutes left: one email.
  • 15 minutes left: one more email.

Set your thresholds

Open Profile → Notification Settings, tick Low Balance and set the hours or amount. Untick Low Balance to turn off all three emails.

When the balance reaches zero​

Your pods keep running for 2 more minutes. Top up in that time to keep them.

If an hourly volume egress charge takes a positive balance to zero or below, you get 60 minutes instead. Pod time is still charged.

If the balance is still zero or below, your pods are removed and you get an email.

Volumes keep charging until you delete them.

The banner in the web app​

A banner at the top of every page shows when:

  • your balance runs out in 60 minutes or less,
  • your pods were stopped for insufficient balance,
  • your Auto Top Up card was declined.

Each banner links to Billing so you can top up.

For agents and automation: API

GET /users/me returns the same warning as balance_warning. It is null when there is nothing to say.

curl -s https://lium.io/api/users/me -H "X-API-Key: $LIUM_API_KEY" | jq '{balance, balance_warning}'

kind is runway, pods_stopped or auto_top_up_failed.

Low balance webhook​

For agents and scripts: Lium can POST each warning to your own URL.

Set the URL

curl -s -X PUT https://lium.io/api/users/me/low-balance-webhook \
  -H "X-API-Key: $LIUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/lium-hook"}'

The URL must be public HTTPS. The answer has a secret: save it, it is shown only once. Setting the URL again gives a new secret.

GET shows the URL, DELETE removes it. A read-only key can read it; changing it takes a key with rent or manage.

The events

eventWhen
low_balanceYour own threshold is crossed (same as the email, once per dip).
balance_grace_startedThe balance reached zero. data.pods_stop_at is when your pods stop unless you top up.
pods_stopped_insufficient_balanceYour pods were stopped. data.pod_ids lists them.

Each POST is JSON: id, event, created_at, user_id and data (balance and details). It is sent once, with a 10-second timeout and no retry. Answer with any 2xx.

Check the signature

X-Lium-Signature is sha256= + HMAC-SHA256 of <X-Lium-Timestamp>.<raw body> with your secret.

import hashlib, hmac

def is_from_lium(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Reject a timestamp more than 5 minutes old.

Last updated on