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

# Billing

> Prepaid credits, metered per second of video.

Your organization holds a **prepaid credit balance** in cents. Processing is metered at a per-hour rate (see `GET /v1/balance` → `rate_cents_per_hour`, currently \$5.00/hour), billed per second of video actually processed and rounded up to the cent.

## How a job is charged

<Steps>
  <Step title="Hold at submit">
    `POST /v1/sessions` places a **hold** for the estimated cost (from `duration_seconds` if you sent it, otherwise from the file size, otherwise 2 hours). The response headers tell you what was held and what remains:

    ```
    X-Hooper-Cost-Cents: 752
    X-Hooper-Balance-Cents: 49248
    ```

    If the balance can't cover the estimate you get `402`:

    ```json theme={null}
    { "error": { "type": "insufficient_credits", "code": "insufficient_credits",
                 "message": "Not enough credits to process this video",
                 "needed_cents": 752, "available_cents": 100 } }
    ```
  </Step>

  <Step title="Settle on success">
    When the job finishes, the hold is **settled for the measured length** — the estimate is replaced by the real duration, and credits are drawn from the oldest-expiring balance first. `cost_cents` on the session is the final figure.
  </Step>

  <Step title="Void on failure">
    If processing fails for any reason — including a video over the [size/resolution limit](/sessions#limits) or a job that never reports back — the hold is **voided** and nothing is charged.
  </Step>
</Steps>

## Balance

```bash theme={null}
curl https://api.hooper.gg/v1/balance -H "Authorization: Bearer $HOOPER_API_KEY"
```

```json theme={null}
{ "object": "balance", "currency": "usd",
  "available_cents": 49248, "held_cents": 752, "credit_cents": 50000,
  "rate_cents_per_hour": 500, "soonest_expiry": 1787702400 }
```

* `available_cents` = `credit_cents` − `held_cents`. This is what a new submit is checked against.
* Credits **expire one year** after purchase; `soonest_expiry` is the next date the balance shrinks on its own.

## Usage

`GET /v1/usage` lists one usage event per billable job:

```json theme={null}
{ "id": "ue_91", "object": "usage_event", "session": "sess_18234", "status": "settled",
  "held_seconds": 7200, "quantity_seconds": 5412, "rate_cents_per_hour": 500, "cost_cents": 752,
  "created": 1756220000, "settled_at": 1756224000, "voided_at": null }
```

`status` is `held`, `settled` or `voided`. Filter by `status`, `api_key`, and `created[gte]` / `created[lte]`.

## Topping up

Credits are added by Hooper — on invoice, or through a card top-up link your Hooper contact can send you. Organizations with a saved card can also enable **auto-recharge**: when a settle drops the balance below your threshold, Hooper charges a fixed amount off-session (at most once an hour). Contact Hooper to set it up.