Compute units

Accessor: client.compute_units

Read your compute-unit balance and transaction history.

Methods

Methods
Method	Endpoint	Returns
`client.compute_units.balance()`	`GET /v1/compute-units/balance`	Free allowance or explicit unlimited paid balance
`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": None,
#   "unlimited": True,
#   "breakdown": [],
#   "currency": "credit",
#   "low_balance_threshold": None,
#   "as_of": "2026-04-25T15:42:11.123Z",
# }

Free reports its rolling daily allowance. Pro returns unlimited=True, total=None, and an empty balance breakdown. Usage is still recorded in the transaction ledger.

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": None,
#   "remaining": None,
#   "resets_at": "2026-05-01T00:00:00.000Z",
# }

window is "day" for Free and "week" for paid usage reporting. Pro always returns cap=None and remaining=None; resets_at is only the oldest event age-out for the reporting window, not a paid allowance reset.

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:

Iterate transaction history
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`	Remaining Free allowance immediately after the event, or `None` for unlimited Pro usage

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: detect unlimited paid usage

balance = client.compute_units.balance()
if balance["unlimited"]:
    print("Unlimited simulations")
else:
    print(f"Free units remaining today: {balance['total']}")