# 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](/billing/plans/#what-free-actually-means).

## 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.

**Use the dashboard to set the cap.** Open [Settings → Usage](https://app.hlix.ai/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](/security/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".
  **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.

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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](/billing/plans/) |
| Change the card, cancel, or find a receipt | [Managing your subscription](/billing/subscription/) |
| See per-run cost and why a run was expensive | [Delivery metrics](/running/metrics/) |
| Check who changed the cap | [Audit log](/security/audit-log/) |

## Next steps

[Plans & pricing](/billing/plans/)
  [Managing your subscription](/billing/subscription/)
  [Delivery metrics](/running/metrics/)
  [Audit log](/security/audit-log/)