---
sidebar_position: 11
title: Low balance warnings
description: What Lium tells you before your balance runs out, what happens at zero, and how a script reads the same warning from GET /users/me.
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Low balance warnings

Pods are billed every 5 minutes. When a charge takes your balance to zero or below, the platform removes your pods at that check. Before that happens you are warned three times, and the web app shows the warning on every page.

**Runway** is how long your balance lasts at the current burn: `balance ÷ (hourly cost of your pods + hourly cost of your volumes)`, in minutes.

## The three warnings

| When | What you get |
|------|--------------|
| Runway drops below your own threshold (default 24 hours), or the balance drops below your own amount threshold | One email. You set the two thresholds under **Profile → Notifications**. |
| Runway drops to 60 minutes or less | One email, subject `Low balance - about N minutes of runway left`, with the minutes left, the current burn and a top-up button. |
| Runway drops to 15 minutes or less | The same email again, once. |

The threshold email is sent again only after the balance was seen above both thresholds and fell below one of them again.

The 60-minute and 15-minute emails go out once per episode. An episode ends when you top up (the balance is higher than when the warning went out), when the pods are removed, or when nothing is running any more. The next time the runway falls, the two warnings start again, but not within 6 hours of the last one. This stops a small top-up from producing the same pair of emails every 5 minutes. The 6-hour wait does not apply after your pods were stopped for insufficient balance: if you top up and rent again the same day, the 60-minute warning comes again before the next stop.

The 60-minute and 15-minute emails are not sent when a working **Auto Top Up** covers the dip: a card on file with no declines, and a threshold and a top-up amount that each cover at least 10 minutes of burn. A top-up smaller than that does not keep up with the burn, so the warnings still go out. A declined card, or a charge that failed for another reason in the last 24 hours, brings them back. The banner and the API field below do not look at Auto Top Up; they show the runway as it is.

Unticking **Low Balance** under **Profile → Notifications** turns off all three emails. The banner and the API field stay on.

## When the balance reaches zero

The 5-minute charge that empties the balance removes your pods. You get one email, subject `Your pods were stopped - insufficient balance`, naming the pods, the charge that emptied the balance and a top-up link. Volumes keep their storage charges until you delete them, so the balance keeps falling while they exist.

## The banner in the web app

The web app shows one banner at the top of every page while there is something to say:

| Banner | Colour | Shown while |
|--------|--------|-------------|
| `Balance runs out in about 43 mins` (or `less than a minute`) | orange | 60 minutes of runway or less. The text names your burn per hour and says that pods stop at zero while volumes keep charging. |
| `Your pods were stopped - insufficient balance` | red | The pods were removed for insufficient balance and no top-up landed since. |
| `Auto top-up failed` | orange | Your card was declined, and the runway is above 60 minutes or nothing is running. The text carries the bank's reason. |

Every banner links to the **Billing** page (**Top up**). The "pods were stopped" banner ends with `Top up to deploy again.`; the "Auto top-up failed" banner ends with `Update the card on file or top up manually.` The runway warning is computed live from your balance on each request, so it is gone the next time the app reads your profile after a top-up. The app reads your profile about once a minute. The "pods were stopped" banner clears when the balance is above what it was at the teardown, or after 24 hours.

<details>
<summary>For agents and automation: API</summary>

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

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

```json
{
  "balance": 1.8,
  "balance_warning": {
    "kind": "runway",
    "runway_minutes": 43,
    "burn_per_hour": 2.5,
    "detail": null
  }
}
```

| Field | Meaning |
|-------|---------|
| `kind` | `runway` (60 minutes or less left), `pods_stopped` (removed for insufficient balance, no top-up since), `auto_top_up_failed` (card declined; runway above 60 minutes or nothing running). |
| `runway_minutes` | Minutes left at `burn_per_hour`; `0` after a teardown; `null` when nothing is running. |
| `burn_per_hour` | USD per hour for your pods plus your volumes. |
| `detail` | A one-line reason when there is one: the teardown time, pod count and final charge, or the card's decline message. |

A `runway` warning with a declined card carries the decline in `detail` (`Auto top-up failed: …`). A script that watches a long job can poll this field and top up, or stop the job, before the pods are removed.
</details>