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

# Usage and Cost

> Read your organization's sandbox usage and cost, in total and per sandbox, from the CLI, Python, or TypeScript.

You can read your organization's sandbox usage and what it costs without opening the dashboard. Use the summary to see totals for the organization. Use the sandbox list to see the cost of each sandbox and project.

> [!NOTE]
>
> Requires `tensorlake` 0.5.160 or later for the CLI, Python SDK, and TypeScript SDK.

## Prerequisites

* You must be a member of the organization. Use an API key or a `tl login` session.
* The SDKs need the organization ID. Pass it to the client or set `TENSORLAKE_ORGANIZATION_ID`.
* The CLI reads the organization from your current context, from `tl init`, or from `--organization`.

## Time window

Every read covers the current billing period by default. Set `last` to read the last `1d`, `7d`, or `30d` instead, ending now. There are no other windows.

## Organization summary

The summary shows the organization's charge for the window, split by resource.

**CLI**

```bash theme={null}
tl usage
tl usage --last 7d
tl usage -o json
```

```text theme={null}
Window:            2026-10-26T18:56:53.000Z to 2026-10-29T22:15:32.150Z
Charge:            0.16 USD
Running sandboxes: 0
┌──────────────────┬──────────┐
│ Resource         ┆ Charge   │
╞══════════════════╪══════════╡
│ CPU              ┆ 0.13 USD │
│ Memory           ┆ 0.03 USD │
│ Disk             ┆ 0.00 USD │
│ Snapshot storage ┆ 0.00 USD │
└──────────────────┴──────────┘
```

**Python**

```python theme={null}
from tensorlake import UsageClient

# Reads TENSORLAKE_API_KEY and TENSORLAKE_ORGANIZATION_ID by default.
with UsageClient(organization_id="org_...") as client:
    summary = client.summary(last="7d")

if summary.usage_charge is not None:
    charge = summary.usage_charge
    print(f"{charge.amount_minor / 100:.2f} {charge.currency.upper()}")
    print("CPU:", charge.resources.cpu_amount_minor)
print("Running sandboxes:", summary.running_sandboxes)
```

**TypeScript**

```typescript theme={null}
import { UsageClient } from "@tensorlakeai/tensorlake";

// Reads TENSORLAKE_API_KEY and TENSORLAKE_ORGANIZATION_ID by default.
const client = new UsageClient({ organizationId: "org_..." });
const summary = await client.summary({ last: "7d" });

if (summary.usageCharge) {
  const { amountMinor, currency } = summary.usageCharge;
  console.log(`${(Number(amountMinor) / 100).toFixed(2)} ${currency.toUpperCase()}`);
}
console.log("Running sandboxes:", summary.runningSandboxes);
```

## Cost per sandbox

The sandbox list shows each sandbox that ran in the window. For each one you get the resources it used and its share of the organization's charge. The CLI also totals the charge per project.

**CLI**

```bash theme={null}
tl usage sandboxes
tl usage sandboxes --last 30d
tl usage sandboxes -o json
```

```text theme={null}
Window: 2026-10-22T22:15:32.271Z to 2026-10-29T22:15:32.271Z
┌───────────────────────┬─────────────────┬────────────────┬──────────────────┬────────────────┬────────────────────┬────────────┬──────────┐
│ Sandbox               ┆ Project         ┆ vCPU-hours     ┆ Memory GiB-hours ┆ Disk GiB-hours ┆ Snapshot GiB-hours ┆ Egress GiB ┆ Charge   │
╞═══════════════════════╪═════════════════╪════════════════╪══════════════════╪════════════════╪════════════════════╪════════════╪══════════╡
│ gtlqov7i2jskbmnr23kfc ┆ Default Project ┆ 0.333042777778 ┆ 0.339308888889   ┆ 0.848272222222 ┆ 0                  ┆ 0          ┆ 0.04 USD │
│ r3y0tv9k88rcqaezrbxbr ┆ Default Project ┆ 0.305422222222 ┆ 0.338067777778   ┆ 0.845169444444 ┆ 0                  ┆ 0          ┆ 0.03 USD │
└───────────────────────┴─────────────────┴────────────────┴──────────────────┴────────────────┴────────────────────┴────────────┴──────────┘
┌─────────────────┬───────────┬──────────┐
│ Project         ┆ Sandboxes ┆ Charge   │
╞═════════════════╪═══════════╪══════════╡
│ Default Project ┆ 2         ┆ 0.07 USD │
└─────────────────┴───────────┴──────────┘
2 sandboxes, 0.07 USD charge (estimated)
```

**Python**

```python theme={null}
from tensorlake import UsageClient

with UsageClient(organization_id="org_...") as client:
    export = client.sandboxes(last="30d")

total = export.attributed_usage_charge
if total is not None:
    print(f"Total: {total.amount_minor / 100:.2f} {total.currency.upper()} ({total.basis})")

for sandbox in export.sandboxes:
    project = sandbox.project.project_name if sandbox.project else "-"
    print(
        sandbox.sandbox_id,
        project,
        sandbox.resources.cpu.quantity,
        sandbox.attributed_amount_minor,
    )
```

**TypeScript**

```typescript theme={null}
import { UsageClient } from "@tensorlakeai/tensorlake";

const client = new UsageClient({ organizationId: "org_..." });
const { attributedUsageCharge, sandboxes } = await client.sandboxes({ last: "30d" });

if (attributedUsageCharge) {
  const { amountMinor, currency, basis } = attributedUsageCharge;
  console.log(`Total: ${(Number(amountMinor) / 100).toFixed(2)} ${currency.toUpperCase()} (${basis})`);
}

for (const sandbox of sandboxes) {
  console.log(
    sandbox.sandboxId,
    sandbox.project?.projectName ?? "-",
    sandbox.resources.cpu.quantity,
    sandbox.attributedAmountMinor,
  );
}
```

The sandboxes' amounts add up exactly to the organization total. `project` is empty for usage whose project was deleted.

## Reading the amounts

* **Money is in minor units**, such as cents. Python returns `int`. TypeScript and the CLI's JSON return strings, so large amounts don't lose precision. Quantities are `Decimal` in Python and strings in TypeScript.
* **Units** are `vCPU-hour` for CPU, `GiB-hour` for memory, disk, and snapshot storage, and `GiB` for network egress.
* **The charge** is metered usage only. It doesn't include subscription fees or tax.
* **`basis`** says where the total comes from. It is `invoice` for a finalized invoice and `current_price_estimate` otherwise. The CLI shows the second as "estimated".
* **In the CLI JSON**, the Charge column is `attributedAmountMinor` on each sandbox, and the total is `attributedUsageCharge`.

### Plans with included usage

On plans that include usage, such as Pro, the charge only covers what you use beyond the included amount. Two more fields help here:

* **Included usage** (`included_usage`) shows the allowance for the current billing period and how much of it you've used.
* **Usage value** (`usage_value` in the summary, `attributed_usage_value` and `usage_value_amount_minor` in the sandbox list) is your usage priced at the plan's overage rate, before the allowance. It's set for every window.

The charge is empty when the window isn't inside the current billing period, for example a 30-day lookback that started in the previous period. Use the usage value then. The CLI does this for you and shows a Usage value column.

The charge is also empty when the organization has no metered price. In that case the CLI shows compute units instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.