Tensorlake Documentation

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.

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
Python
TypeScript

tl usage
tl usage --last 7d
tl usage -o json

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 │
└──────────────────┴──────────┘

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)

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
Python
TypeScript

tl usage sandboxes
tl usage sandboxes --last 30d
tl usage sandboxes -o json

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)

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,
    )

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.

Overview

Usage and Cost

Prerequisites

Time window

Organization summary

Cost per sandbox

Reading the amounts

Plans with included usage

​Prerequisites

​Time window

​Organization summary

​Cost per sandbox

​Reading the amounts

​Plans with included usage

Prerequisites

Time window

Organization summary

Cost per sandbox

Reading the amounts

Plans with included usage