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

# Billing

> Credits, invoices, and execution history

Lyceum Cloud is credit-based. You top up your balance through Stripe and the platform deducts credits as you run jobs, host VMs, or serve models. Credits don't expire and there's no monthly minimum, what you put in is what you have to spend.

## Credits live on the organization

Every billable resource, a serverless run, a VM hour, an inference replica hour, is billed against an [organization](/docs/account/organizations). New accounts get an org created automatically at signup; credits granted to your account live on that org. If you belong to several orgs, each one has its own balance and history.

The org a request bills against is resolved by:

1. The `org_id` carried by an API key created under `/orgs/{slug}/api-keys`.
2. The `X-Org-Slug` header on a JWT request.
3. Otherwise, your default org.

The dashboard sets `X-Org-Slug` automatically based on the org switcher.

## How charging works

Every billable action generates an entry in the org's history with the credit cost attached. Charges are pulled against the org's balance in real time, so you can watch your spend during long jobs and abort if needed.

Two convenience views layer on top of the org ledger:

* **Activities**, Combined timeline of debits and credit top-ups for the active org.
* **History**, Per-execution breakdown for runs that have been billed.

## Topping up

`POST /billing/checkout` creates a Stripe Checkout session for the active org. The session metadata captures the org id at creation time, so the webhook routes the credits to the right org even if you switch the active org before the payment completes.

In the dashboard, the **Billing** page has both preset packages and a custom-amount input.

## REST API

Top-level billing endpoints (active-org aware):

| Method | Endpoint                   | Purpose                                                     |
| ------ | -------------------------- | ----------------------------------------------------------- |
| `GET`  | `/billing/credits`         | Current credit balance for the active org                   |
| `GET`  | `/billing/credits/details` | Detailed breakdown (free vs purchased, total used)          |
| `POST` | `/billing/checkout`        | Create a Stripe Checkout session for the active org         |
| `GET`  | `/billing/history`         | Per-execution billing history for the active org            |
| `GET`  | `/billing/activities`      | Combined timeline of charges and top-ups for the active org |
| `GET`  | `/billing/invoices`        | Stripe invoices (still scoped to your user, not the org)    |

Org-scoped reads, the underlying ledger pulled straight from the credit system:

| Method | Endpoint                              | Purpose                                                                                        |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET`  | `/orgs/{slug}/balance`                | Org balance and suspension status                                                              |
| `GET`  | `/orgs/{slug}/transactions`           | Newest-first ledger with `kind`, `source`, cursor, and `limit` filters                         |
| `GET`  | `/orgs/{slug}/transactions/aggregate` | Group debits by `vm_id`, `hardware_profile`, `execution_id`, or `deployment_id` for a category |

See [Organizations, Billing](/docs/account/organizations#billing) for the category and `group_by` reference.