> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> How usage is measured and how to query the account billing summary

This page explains **how your usage is measured** and the endpoints to track the cycle. Enterprise billing is usage-based, so it helps to understand what counts and how the cycle's total is formed.

## What is measured

The unit of measure is the **active instance-day**. For each billable instance, the API counts the days committed in the cycle, and the cycle's total is the sum of those days across all your instances.

* An instance active for the whole cycle counts the full cycle.
* An instance that becomes billable mid-cycle commits the days from that point until renewal.
* Deleting an instance does not reduce the days already committed. See [How billing works](/en/enterprise/how-billing-works).
* An instance still on trial does not count while it is in that state.

## Account billing summary

**`GET /api/account/billing/summary`**

Returns the summary of the account's current cycle. Authenticate with the account **TokenAccount**, or with the global token passing `?account=<account-name>`.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://ryzeapi.cloud/api/account/billing/summary" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/account/billing/summary", {
    headers: { "token": process.env.Token_Account }
  });
  ```
</CodeGroup>

```json 200 OK theme={null}
{
  "enterprise": true,
  "baseCents": 50000,
  "committedCents": 42000,
  "projectedChargeCents": 50000,
  "billableInstanceDays": 210,
  "billableCount": 8,
  "cycleStart": "2026-08-01T00:00:00Z",
  "cycleEnd": "2026-09-01T00:00:00Z",
  "nextChargeAt": "2026-09-01T00:00:00Z"
}
```

<ResponseField name="enterprise" type="boolean">
  `true` when the account is Enterprise. If it comes `false`, the other fields do not appear.
</ResponseField>

<ResponseField name="baseCents" type="integer">
  Your contract's monthly credit (base), in cents. It is the invoice floor.
</ResponseField>

<ResponseField name="committedCents" type="integer">
  The usage amount already committed in the cycle, in cents, proportional to the instance-days.
</ResponseField>

<ResponseField name="projectedChargeCents" type="integer">
  The projected charge for the cycle, in cents: the greater of `baseCents` and `committedCents`.
</ResponseField>

<ResponseField name="billableInstanceDays" type="integer">
  The sum of billable instance-days in the cycle.
</ResponseField>

<ResponseField name="billableCount" type="integer">
  The peak of simultaneous billable instances in the cycle.
</ResponseField>

<ResponseField name="cycleStart" type="string">
  Start of the current cycle.
</ResponseField>

<ResponseField name="cycleEnd" type="string">
  End of the current cycle.
</ResponseField>

<ResponseField name="nextChargeAt" type="string">
  When the next charge happens (the end of the cycle).
</ResponseField>

<Note>
  Before the first renewal, the cycle window may not be filled in yet, and the summary shows the `base` as the projected floor.
</Note>

## Per-instance billing in the listing

**`GET /api/instance/list`** already brings, for each instance, a `billing` block with the billing state. It appears only on calls with an account or global token, never with an instance token.

```json theme={null}
{
  "billing": {
    "billingMode": "trial",
    "trialEndsAt": "2026-08-25T12:00:00Z",
    "billableSince": null,
    "trialDaysLeft": 5,
    "willBeCharged": false
  }
}
```

<ResponseField name="billingMode" type="string">
  `trial` or `billable`.
</ResponseField>

<ResponseField name="trialEndsAt" type="string | null">
  When the trial ends. `null` when the instance is already billable.
</ResponseField>

<ResponseField name="billableSince" type="string | null">
  Since when the instance is billed. `null` while on trial.
</ResponseField>

<ResponseField name="trialDaysLeft" type="integer">
  Days left on the trial, rounded up. `0` outside the trial.
</ResponseField>

<ResponseField name="willBeCharged" type="boolean">
  `true` when the instance is already billable.
</ResponseField>

## Tracking in real time

To react to each state change, use the [Enterprise webhooks](/en/enterprise/webhooks). They notify you when a trial starts, when it is about to end and when an instance becomes billable, which lets you mirror that state in your own dashboard.

## Next

<CardGroup cols={2}>
  <Card title="Usage statement" icon="receipt" href="/en/enterprise/statement">
    The itemized invoice for the period, instance by instance.
  </Card>

  <Card title="Connection history" icon="link" href="/en/enterprise/connections">
    The timeline of when each number was connected.
  </Card>

  <Card title="How billing works" icon="calculator" href="/en/enterprise/how-billing-works">
    Credit, trial and the committed model in detail.
  </Card>

  <Card title="Enterprise webhooks" icon="webhook" href="/en/enterprise/webhooks">
    Track the state changes in real time.
  </Card>
</CardGroup>