# Billing and history

> How both kinds of screen are billed, usage credit, the screen cap, and the record of every call kept for 30 days.

## Persistent screens

Each persistent screen is billed monthly, or yearly at 12 months for the price of 10, whether it is running or stopped, because its disk is kept. Creating one adds it to your bill: the rest of this month is charged first, then the machine is made. Deleting one takes it off the bill, and the unused days are credited to your next invoice. A card that declines or needs 3-D Secure fails the create with `PAYMENT_REQUIRED` and a link to pay.

## Disposable screens and credit

Disposable screens are paid from your organization's **usage credit**, which a person buys ahead in the dashboard. Credit never expires. Saving a card once grants a small trial credit, spent first and never refunded.

- Running time is charged per billing step, rounded up, each step as it starts. A stopped disposable screen pays a small fee for its disk.
- Each disposable screen shows its `spend`: how long it has run and what it has cost so far.
- A person sets a low-balance mark. Under it, the dashboard and email warn, and API replies carry a `Billing-Warning` header.
- Agents never see the amount. `GET /me` tells them `billing.credit_state`: `ok`, `low` or `empty`.
- When credit can't cover the next step, your running disposable screens stop with `stopped_by_credit`, and creating a disposable screen gets `402 CREDIT_EXHAUSTED`. A top-up doesn't start them again; start them yourself. Persistent screens are never touched.

## Limits on spend

Your organization has one screen cap over both kinds, so a runaway agent can't run up the bill. Over it, creating a screen gets `402 QUOTA_EXCEEDED`. If we have no room right now, you get `409 NO_CAPACITY` with a time to retry, and nothing is charged.

## History

Every call on a screen is saved in its history for 30 days: what was called, its parameters and typed text, which key or app called it, the result, how long it took and the screenshot it returned. Account events are there too, such as a key made or revoked.

```bash
curl "https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/history?limit=20" \
  -H "Authorization: Bearer $KUBI_API_KEY"
```

A row with a screenshot carries its `screenshot_id`. Get the exact image back with `GET /screens/{id}/screenshots/{screenshot_id}`.

- **Runs:** send the optional `Kubi-Run` header and history groups your calls into runs; read one run with `?run=`. The SDK sends it for you. It is only a label and never locks anything.
- **Follow live:** pass `since` (a row id) with `wait_s` to get newer rows as they happen.
- **Privacy:** a person can turn detailed history (screenshots and typed text) off for the organization or for one screen in the dashboard; rows then keep only what was called, by whom, when and the result. Typed text that matches one of your saved secrets is replaced by the secret's name. The live view is never recorded.