Compute units

Compute units record simulation and sweep work per physical rotor. Free uses them for its rolling daily allowance. Pro usage is unlimited: ledger entries remain visible for history, refunds, and cost attribution, but accumulated usage never blocks a paid run. Three read-only endpoints expose the meter:

• GET /v1/compute-units/balance — remaining Free allowance, or an explicit unlimited paid balance.
• GET /v1/compute-units/summary — rolling usage and cap status.
• GET /v1/compute-units/transactions — the full debit/grant ledger.

All three are owner-scoped: they read the calling key's account, take no path parameters, and never mutate.

The wire keeps its original object names (credit_balance, credit_usage_event) and currency ("credit") for backward compatibility. Only the public field vocabulary moved: a transaction's bucket is reported as unit_type.

Metering and allowance

A compute unit is one physical rotor solved. A four-rotor static run records four units. Historical transaction rows retain free and monthly unit types for compatibility:

These labels no longer represent stored paid balances. Free allowance is computed from its rolling 24-hour usage. Paid accounts are unlimited and return no bucket balance.

GET /v1/compute-units/balance

Returns a point-in-time allowance snapshot.

curl https://thrustlab.com/v1/compute-units/balance \
-H "Authorization: Bearer key_..."

Balance response

{
  "object": "credit_balance",
  "total": null,
  "unlimited": true,
  "breakdown": [],
  "currency": "credit",
  "low_balance_threshold": null,
  "as_of": "2026-04-25T15:42:11.123Z"
}

GET /v1/compute-units/summary

Returns rolling usage. Free reports its daily allowance; paid tiers report seven-day usage with cap and remaining set to null.

curl https://thrustlab.com/v1/compute-units/summary \
-H "Authorization: Bearer key_..."

Summary response

{
  "object": "credit_usage_summary",
  "tier": "pro",
  "window": "week",
  "used": 1240,
  "cap": null,
  "remaining": null,
  "resets_at": "2026-04-26T00:00:00.000Z"
}

GET /v1/compute-units/transactions

Returns your ledger: every debit and grant, newest first, cursor-paginated. Legacy pre-ledger rows are not exposed.

curl "https://thrustlab.com/v1/compute-units/transactions" \
-H "Authorization: Bearer key_..."

Event shape

{
  "object": "credit_usage_event",
  "id": "cue_2c5tQ...",
  "amount": -25,
  "type": "simulation_debit",
  "unit_type": "monthly",
  "resource": {"object": "simulation", "id": "sim_2c5tQ..."},
  "balance_after": null,
  "created_at": "2026-04-25T15:42:11.123Z"
}

Current simulation usage writes one ledger event. Older accounts may still have grant and debit rows carrying either compatibility unit type.

Query parameters

The response wraps events in a cursor-paginated list:

{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJwIjoiY3VlXzJ..."
}

Pass cursor=<next_cursor> on the next request. Cursors encode (created_at, id) and stay stable while the underlying rows exist.

Examples

Simulation debits since a date:

curl "https://thrustlab.com/v1/compute-units/transactions?type=simulation_debit&created_at[gte]=2026-04-18T00:00:00Z" \
  -H "Authorization: Bearer key_..."

Free-bucket activity only:

curl "https://thrustlab.com/v1/compute-units/transactions?credit_type=free" \
  -H "Authorization: Bearer key_..."

Low-balance webhook compatibility

low_balance_threshold remains in the resource for compatibility but is null under the current rolling-allowance model, so no paid low-balance event is emitted.

Free allowance exceeded (HTTP 402)

Only Free can exhaust a compute-unit allowance. Paid tiers never receive a usage-cap 402. A Free over-cap submit returns the typed daily-limit upgrade error documented in Errors.

{
  "error": {
    "type": "upgrade_required",
    "code": "upgrade_required",
    "message": "You have reached the free daily simulation limit.",
    "details": {"gate": "daily_cap", "required_tier": "hobbyist"}
  }
}