# See your usage, budgets and credit activity

> See what your services used and cost this month by service and day, download the rows, set a budget, question a charge and follow your credit.

Source: https://www.coritan.com/docs/billing/see-your-usage/

In the dashboard:

- /dashboard/billing/usage: https://www.coritan.com/dashboard/billing/usage

The **Usage** tab of **Billing** shows what every service on your account that is [billed by use](/docs/billing/usage-billing/) used and cost in a month. It splits the month by service and day, shows how much of each free amount you have used, and says what the month is likely to cost if nothing changes. You can also download the hours behind it, set a budget and ask us about a charge.

## Before you begin

- At least one service billed by use: a web service or site on App Deployment, a Cloud Compute instance, a game server or a database. A service you ordered before usage billing keeps its price and is not on this page until you [switch it](/docs/billing/switch-to-usage-billing/).
- On a team, the Billing, Admin or Read only role. The Technical role cannot open Billing, and the Read only role cannot change a budget.

## Open the page {#open}

1. In the dashboard, go to **Billing**.
2. Open the **Usage** tab.
3. To read an earlier month, choose it in **Month**. The page lists the current month and the five before it, and keeps your choice in the address.

An account with no service billed by use sees "Your usage appears here once a service billed by use runs."

## What the page shows {#shows}

**Cost so far**
: What the month has cost up to the last hour that is final. Use is counted by the hour, and the page says which hour it counted to. The slowest meters are up to two hours behind. For an earlier month the figure reads **Cost** and the month is over.

**By month end**
: What the month will cost if each running service keeps using at its own pace ([How the forecast works](#forecast)). It reads a dash until the month has some use to go on, and it is left out for an earlier month.

**Free amounts used**
: How much of the month's free amounts you have used, as one percentage. Each amount counts for what it is worth at the rates, so an hour of memory and a GB of data out count for what they cost. The server amounts count only with the [Paid plan](/docs/billing/usage-billing/#paid-plan).

**Credit left**
: How many days your credit lasts at the pace of the last 7 days ([Follow your credit](#credit)). It reads **By invoice** for an account that pays by invoice, and **No use** when nothing took credit in those days.

**Cost by day** is a bar chart with a bar for each day of the month so far. Pick a meter in **Meter** to chart one meter, or leave **All meters**. A day with no use has no bar.

Under the chart, a card for each product with something to show lists its services:

| Column | What it holds |
| --- | --- |
| **Service** | The deployment or server. A deployment's name opens its **Billing** tab. A server that is switched off says "Stopped: costs its disk only". |
| **Meter** | Memory, CPU, disk, requests, data out by region, builds or logs. A web service has no disk meter, and a static site has builds and logs only. |
| **Used** | The quantity used this month, in the meter's unit. |
| **Free or included** | The part of it the month's free amounts paid for. |
| **Billed** | The part that is billed at the meter's rate. |
| **Cost** | What the billed part cost, in your currency. |

The three products are App Deployment (web services, hybrid sites and static sites), Cloud Compute (instances) and Container Apps (game servers and databases). A product with no service billed by use is left out.

The cards **Free each month for App Deployment** and **Free each month for Cloud Compute and Container Apps** show each free amount against everything that draws on it. A bar that is full means the free amount is used up, and the card adds that the rest is billed. The server amounts are yours only while your account has the [Paid plan](/docs/billing/usage-billing/#paid-plan), and the page says so when it does not. [Usage rates](/docs/billing/usage-rates/#included) lists the amounts.

> [!NOTE]
> One free amount serves every service of its kind. Two web services on the account share the same 100 GiB-hours of memory, and an instance and a game server share the server amounts.

## Download the rows {#csv}

Select **Download rows (CSV)** to save the hourly rows behind the month you chose. Each row is one meter of one service in one hour, newest hour first, with these columns: `hour`, `service_id`, `service`, `meter`, `unit`, `quantity`, `included`, `billable`, `rate`, `amount`, `currency` and `status`.

`status` says what happened to the hour: `rated` (priced, not yet paid), `charged` (paid from credit), `invoiced` (on an invoice), `blocked` or `waived`. A file holds at most 100000 rows. A service name that a spreadsheet would run as a formula, one that starts with `=`, `+`, `-` or `@`, is written with a quote in front so it stays text.

## Ask about a charge {#query}

If an hour looks wrong, select **Query a charge…** at the top of the page, on a service's row, or beside **Refunds** on the **Refunds** tab. The dialog works like this:

1. Choose the hour in **Which hour**. It lists the latest 100 hours with use, narrowed to one service and meter when you started from a row.
2. Say what looks wrong in **What looks wrong**, in up to 2000 characters.
3. Select **Send question**.

We open a support conversation that names the service, meter, hour, quantity and amount, and the dialog links to it with **Open the conversation**. The answer comes in that conversation and by email ([Contact support](/docs/support/conversations/)). You can send 10 questions an hour. Only an hour of a service billed by use on your account can be questioned. To ask for money back on a paid invoice, use [Ask for a refund](/docs/billing/refund-requests/).

## Set a budget {#budgets}

The **Budgets** card keeps a monthly limit across the account, and one on each deployment you choose. We email you at 80% and at 100% of a budget. At 100% its action applies:

**Block new use**
: Previews sleep, and builds, bursts and use past a free amount wait. Your running production service keeps serving.

**Pause**
: Every instance stops until you raise the budget or the month turns.

1. In the **Budgets** card, select **Add a budget…**.
2. In **Applies to**, choose **The whole account** or a deployment.
3. Enter the amount in **Budget for a month**, with up to two decimal places.
4. Choose what happens **At 100%**, then select **Save budget**.

Select **Edit…** on a row to change it and **Remove…** to lift it, with whatever it held back. The account budget counts every service billed by use, a virtual machine's included, and its action applies to all of them. A deployment budget covers a web service, a static site, a game server or a database. A virtual machine has no budget of its own: only the account budget covers it. A deployment that is billed by its own service's plan cannot have a budget. Object Storage keeps a separate budget on its **Billing** tab ([How Object Storage is billed](/docs/object-storage/usage-and-billing/)).

## Follow your credit {#credit}

The **Credit activity** card lists every time use took credit, newest first: the service and what it paid for, the date and the balance after. Hourly use that took credit is here too. Select **Show older** for more, and **Add credit** to top up. Above the list, the card says how many days your credit lasts and the date it runs out, and warns when that is less than 7 days. A top-up starts the hourly servers that stopped for want of credit ([How hourly billing works](/docs/billing/hourly-billing/#when-your-credit-runs-out)).

The **Billing events** card lists what changed in how you are billed: a price change (we email you when a rate you use changes, and the email names the day it applies), a service moved to another billing term, and a budget cap applied.

## Open an invoice's usage {#invoice}

On the **Invoices** tab, open an invoice that has usage lines. **Usage detail** lists each line with its meter, the service, the period and hours it covers, the quantity, the rate and the amount. **Download rows (CSV)** saves the hours the invoice bills, and the question mark on a line opens **Query a charge** for that service and meter ([Pay an invoice](/docs/billing/invoices/)).

## How the forecast works {#forecast}

The forecast follows each running service's own use:

1. A service that has used a meter for a day or more is carried to the end of the month at the pace it has used it since its first use this month. A younger service is not carried forward, so a build in its first hour does not turn into a month of builds.
2. A service that has ended or is suspended keeps what it used and adds nothing.
3. The free amounts are taken off what all the services of a kind would use, and the rest is priced at the average rate its hours were billed at. A Performance server's hours were billed at 1.5 times, so its forecast is too.
4. A forecast is never lower than what is already billed.

A forecast assumes the next days look like the last ones. A service that gets busier, or a meter that has not been used yet, makes the real bill higher.

## With the API {#api}

[`GET /api/v1/billing/usage/summary`](/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-usage-summary) answers the page's figures in one call. `month` takes `YYYY-MM` and defaults to this month.

```bash
curl "https://api.coritan.com/api/v1/billing/usage/summary?month=2026-10" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

The answer is shortened here:

```json
{
  "month": "2026-10",
  "currency": "USD",
  "through": "2026-10-12T10:00:00",
  "forecast_basis": "pace",
  "total": "0.4200",
  "forecast": "1.6550",
  "included_share": 0.31,
  "paid_plan": {"active": false, "price": "4.50"},
  "services": [
    {
      "service_id": 311, "name": "web", "group": "app_deployment", "group_label": "App Deployment",
      "status": "active", "deployment_uuid": "5e8a1c3f-2b7d-4e9a-8c6f-1d3b5a7e9c02", "stopped": false, "total": "0.4200",
      "meters": [
        {"meter": "memory_gib_hours", "unit": "GiB-hour", "quantity": "240", "included": "100", "billable": "140", "cost": "0.4200"}
      ]
    }
  ],
  "daily": [
    {"day": "2026-10-01", "meter": "memory_gib_hours", "unit": "GiB-hour", "quantity": "24", "cost": "0.0720"}
  ],
  "spend_limit": {"monthly_limit": "50.00", "policy": "block", "used": "0.42", "reached": false}
}
```

`services`
: Each service billed by use with use in the month, the dearest first, with a line for each meter: its `quantity`, what the free amounts covered (`included`), what was `billable` and its `cost`. `stopped` is true for a server that is switched off.

`daily`
: One row for each day and meter, summed over the services, so a chart can draw cost or use by day.

`included_share`
: How much of the free amounts you used, from `0` to `1`, weighted by their rates. It is `null` when no amount applies.

`groups`, `pools`, `forecast`, `forecast_basis`, `through` and `spend_limit`
: As [`GET /api/v1/billing/compute-usage`](/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-compute-usage) answers them. `pools` shows the free amounts against use: the `web` pool is every account's and covers `app_deployment`, and the `server` pool covers `cloud_compute` and `container_apps` together and is `active` only with the Paid plan. `forecast_basis` is `pace` for the current month, `final` for an earlier month (its `forecast` is what it cost), and `none` in the first hours of a month, when every `forecast` is `null`.

[`GET /api/v1/billing/usage/rows`](/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-usage-rows) lists the hourly rows. Filter with `month`, `service_id`, `meter` and `status`, and page with `limit` and `offset`. Send `?format=csv` or `Accept: text/csv` for the file. A JSON page holds at most 1000 rows, and a CSV at most 100000.

```bash
curl "https://api.coritan.com/api/v1/billing/usage/rows?month=2026-10&meter=memory_gib_hours&format=csv" \
  -H "Authorization: Bearer $CORITAN_TOKEN" -o usage-2026-10.csv
```

[`GET /api/v1/billing/invoices/{invoice_id}/usage`](/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-invoices-invoice-id-usage) opens an invoice's usage lines with their `meter`, `unit`, `from`, `to` and `hours`, and `?format=csv` gives the rows the invoice bills. It answers `404` for an invoice that is not yours.

[`GET`, `PUT` and `DELETE /api/v1/billing/budgets`](/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-budgets) read, set and remove budgets. `PUT` takes `scope` (`account` or `deployment`), `deployment_uuid` for a deployment, `monthly_limit` and `policy` (`block` or `pause`):

```bash
curl -X PUT "https://api.coritan.com/api/v1/billing/budgets" \
  -H "Authorization: Bearer $CORITAN_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope": "account", "monthly_limit": "50.00", "policy": "pause"}'
```

`DELETE` takes `scope` and `deployment_uuid` in the query and answers `204`.

[`POST /api/v1/billing/charge-queries`](/docs/api/reference/client/usage-and-budgets/#op-post-api-v1-billing-charge-queries) takes `service_id`, `hour`, `meter` and `message`, finds that hour's row and opens a support conversation. It answers `201` with `ticket_id`, `404` when your account has no usage for that service, meter and hour, and `429` after 10 questions in an hour.

These routes are for your own account. A member of your team reaches them with the Billing role. An organization's owner reads what its customers cost on the organization's own **Usage and cost** page ([Usage and cost](/docs/organizations/billing/usage-and-cost/)).

## Result

The page lists each product's services and meters with their use and cost, the cost of each day, the free amounts with their bars, your budgets, your credit activity and a forecast for the month.

## Troubleshooting

The page is empty
: No service is billed by use yet, or none used anything in that month. A service shows up within the hour it first uses a meter.

A service is missing
: A free server, a service that keeps a flat price and a service one of an organization's customers ordered are not billed by use on your account, so they are not here. [Switch a service to usage billing](/docs/billing/switch-to-usage-billing/) moves one of yours.

The forecast is a dash
: The month has no use to go on yet, or it is an earlier month. A service needs a day of use before the forecast carries it forward.

**Query a charge…** lists no hours
: There is no use to question yet, or the service and meter you started from have none this month.

`409` when you set a deployment budget
: The deployment is billed by its own service's plan, which a budget would never apply to.

`422` from the API
: `month` is not `YYYY-MM`, a `meter` or `status` is not one this page names, a JSON `limit` is above 1000, or a budget amount is not more than 0 and at most 1000000 with two decimal places.

## Next steps

- [Usage rates and included amounts](/docs/billing/usage-rates/) lists every rate.
- [How usage billing works](/docs/billing/usage-billing/) explains what each meter measures and how limits work.
- [Ask for a refund](/docs/billing/refund-requests/) when money should go back on a paid invoice.

## API

- `GET /api/v1/billing/usage/summary`: A month of usage by service, meter and day (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-usage-summary)
- `GET /api/v1/billing/usage/rows`: The hourly rows behind a month of usage (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-usage-rows)
- `GET /api/v1/billing/invoices/{invoice_id}/usage`: An invoice's usage lines, opened to their hours and meters (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-invoices-invoice-id-usage)
- `GET /api/v1/billing/compute-usage`: What the account's compute used and cost in a month, by product group (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-compute-usage)
- `GET /api/v1/billing/budgets`: The account's budget and each deployment's (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-get-api-v1-billing-budgets)
- `PUT /api/v1/billing/budgets`: Set the account's budget or a deployment's (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-put-api-v1-billing-budgets)
- `DELETE /api/v1/billing/budgets`: Remove the account's budget or a deployment's (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-delete-api-v1-billing-budgets)
- `POST /api/v1/billing/charge-queries`: Ask us about one hour of usage (https://www.coritan.com/docs/api/reference/client/usage-and-budgets/#op-post-api-v1-billing-charge-queries)