Usage & runtime credit

Usage is agent runtime: the model spend of every run hlix makes on your behalf. It is the one thing that is metered, the one thing a plan caps, and the one thing that can stop a dispatch. Storage, projects, seats and integrations are not metered.

Prerequisites

• A Workspace, and any agency role to read usage. Setting or clearing the cap needs owner or admin; a client collaborator cannot see usage at all.
• Some completed runs. A Workspace with no runs reports zeros.
• For the API examples: an API key and your Workspace ID.

What is counted

Every agent run records the tokens it consumed and what those tokens cost. That cost is what the ceilings compare against.

Two ceilings can stop a run, and the tighter one wins:

1. Your plan’s allowance — the free tier’s monthly credit, or Basic’s hard cap. Pro and Ultra meter past the plan instead of stopping.
2. A cap you set yourself — a monthly maximum you choose, honoured on every plan including Free.

When a run is refused, the message names which ceiling was reached.

On the free plan, a failed run still counts

The free credit is measured from every run, including runs that failed. On a paid plan the opposite rule applies: only work that actually landed is metered, so you are never charged for a run that produced nothing.

The free credit is the only limit on an unpaid Workspace, so retries count against it. A paying customer is never charged for a failed run.

The free plan’s monthly credit

$5.00 of metered agent spend per calendar month, measured in UTC.

• The window starts at 00:00 UTC on the 1st and the grant resets at 00:00 UTC on the 1st of the next month.
• There is no rollover. An unused month is not saved credit.
• A run belongs to the month it started in.
• The date in a refusal message is exactly when the credit resets.

Once a payment method is on the Workspace, the same $5.00 arrives as a monthly credit and spend beyond it is billed rather than refused. See Plans & pricing.

Set your own spend cap

The cap is a monthly maximum you choose. It applies on every plan, and it is checked against the same spend figure as the plan cap, so what the usage screen shows as remaining is exactly what is enforced.

Dashboard

Use the dashboard to set the cap. Open Settings → Usage. Set an amount to cap the Workspace, or clear it to remove the cap entirely. Both actions are recorded in the audit log.

Setting a cap lower than your current month’s spend stops dispatch immediately — the check is “has this ceiling been reached”, not “was it crossed today”.

API

The Workspace usage roll-up and its cap are not in the published contract. There is no generated SDK method for them; use the dashboard. What the contract does publish is usage per project, per cycle, and the Workspace usage report.

curl -sS "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/usage" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected output — totals plus two breakdowns of the same runs:

{
  "totals": { "count": 42, "tokensIn": 918400, "tokensOut": 130220, "cost": 3.87 },
  "byRole": [
    { "role": "builder", "count": 30, "tokensIn": 720100, "tokensOut": 104900, "cost": 3.01 },
    { "role": "reviewer", "count": 12, "tokensIn": 198300, "tokensOut": 25320, "cost": 0.86 }
  ],
  "byPersona": [
    { "persona": "qa-engineer", "count": 12, "tokensIn": 198300, "tokensOut": 25320, "cost": 0.86 },
    { "persona": null, "count": 30, "tokensIn": 720100, "tokensOut": 104900, "cost": 3.01 }
  ]
}

cost is USD. A role that never ran is absent from byRole. byPersona has a null entry for runs not attributed to a named persona, so both breakdowns sum to totals.

For the whole Workspace over a rolling window:

curl -sS "$HLIX_BASE_URL/v1/api/reports/usage?period=30d" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected output:

{
  "generatedAt": "2026-08-28T09:14:02.118Z",
  "period": { "from": "2026-07-29", "to": "2026-08-28", "days": 30 },
  "usage": { "runs": 613, "tokensIn": 14822910, "tokensOut": 1904220, "costUsd": 61.44 }
}

period is clamped to 1–365 days. Note this is a rolling window, not the calendar month the free credit uses — the two answer different questions and will not match.

What your plan state can say

Reading billing or usage returns an entitlement with one of these kinds:

kind	What it means
subscription	An active plan, with its cap and the meter reading behind it.
free	No subscription — the free plan, carrying this month’s credit state.
none	Billing is not available on this server. Nothing can be bought and nothing is capped.
unknown	Your plan could not be read at that moment.

unknown is never shown as “no subscription”. The billing screen says it could not load your plan, and a refresh usually resolves it.

If a run is refused

Every refusal below is 402 and carries {"error": "…"} with the message quoted.

• Your free credit is used for this month (5.00 of 5.00). Add a payment method in Settings → Billing to continue pay-as-you-go, or wait for the reset on 2026-09-01. — the free grant is spent. The date is when it resets.
• Monthly usage limit reached (25.00 of your workspace's own cap). Raise or remove it in Settings → Usage to continue. — your own cap, not the plan. It fires the same way on Free and on a paid plan.
• Plan cap reached on Hlix-Basic. Upgrade to Hlix-Pro or Hlix-Ultra to continue. — Basic’s hard cap.
• A run went through when you expected a refusal. If spend cannot be checked at the moment a run starts, the run proceeds rather than being blocked by an outage, and its cost still counts toward your ceilings.
• Usage shows less than you expect on a paid plan. Only dispatches that landed are metered there. Failed runs still appear in the run history and still cost real model spend — they are simply not billed to you.
• The cap you set had no effect, and entitlement.kind is none. Billing is not available on this server, so no cap is enforced.

Where to go next

If you want to…	Read
Compare the plans and their allowances	Plans & pricing
Change the card, cancel, or find a receipt	Managing your subscription
See per-run cost and why a run was expensive	Delivery metrics
Check who changed the cap	Audit log

Next steps

Plans & pricingThe four plans, the free credit, and the one tier with a hard cap.

Managing your subscriptionCheckout, the billing portal, cancelling, and receipts.

Delivery metricsWhat each cycle and task cost, and where the time went.

Audit logWho set or cleared the spend cap, and when.