`client.compute_units`

Read your compute-unit balance and transaction history.

Methods

Method	Endpoint	Returns
`client.compute_units.balance()`	`GET /v1/compute-units/balance`	Current balance per bucket
`client.compute_units.summary()`	`GET /v1/compute-units/summary`	Usage-meter read for the current metering window
`client.compute_units.transactions(credit_type=..., limit=..., cursor=...)`	`GET /v1/compute-units/transactions`	`CursorPager` of transaction events

Read your balance

from thrustlab import Client

client = Client()
balance = client.compute_units.balance()
print(balance)
# {
#   "object": "credit_balance",
#   "total": 500,
#   "breakdown": [
#     {"type": "free",    "balance": 12,  "expires_at": None},
#     {"type": "monthly", "balance": 488, "expires_at": "2026-05-14T00:00:00.000Z"},
#   ],
#   "currency": "credit",
#   "low_balance_threshold": 200,
#   "as_of": "2026-04-25T15:42:11.123Z",
# }

free units are permanent (signup grant + bounties). monthly units expire at the end of each billing period and are consumed first. See the compute units guide for bucket and consumption rules.

Read the usage-meter summary

summary() reads the current metering window — daily for free-tier accounts, weekly for paid tiers — rather than the all-time balance:

summary = client.compute_units.summary()
print(summary)
# {
#   "object": "credit_usage_summary",
#   "tier": "pro",
#   "window": "week",
#   "used": 128,
#   "cap": 400,
#   "remaining": 272,
#   "resets_at": "2026-05-01T00:00:00.000Z",
# }

window is "day" for tiers with a daily_cap and "week" for tiers with a weekly_cap (see client.users.me() for which applies). cap / remaining are null for an uncapped tier. resets_at is when the oldest in-window debit ages out of the rolling window — not a fixed calendar boundary.

Iterate transaction history

transactions() returns a CursorPager that lazily fetches pages as you iterate:

for event in client.compute_units.transactions(limit=50):
    print(event["created_at"], event["amount"], event["type"], event["unit_type"])

Each event:

Field	Meaning
`amount`	Negative for debits, positive for grants/refunds
`type`	`simulation_debit`, `sweep_debit`, `monthly_grant`, `signup_grant`, `bounty_grant`, `refund`, `adjustment` — plus two legacy values, `debit` and `topup`, that only appear on older accounts' pre-migration transactions
`unit_type`	Bucket affected: `free` or `monthly`
`resource`	Linked `simulation` / `component_submission`, or `None` for grants
`balance_after`	`total` immediately after the event

Filter by bucket

# Only monthly-bucket consumption
for event in client.compute_units.transactions(credit_type="monthly"):
    print(event["created_at"], event["amount"])

Valid credit_type values: free, monthly.

Recipe: units left this billing period

balance = client.compute_units.balance()
monthly = next(b for b in balance["breakdown"] if b["type"] == "monthly")
print(f"total usable: {balance['total']}")
print(f"monthly bucket expires: {monthly['expires_at']}")

client.compute_units