---
title: "Query compute usage"
description: "Retrieve billed vCPU usage for your organization"
source: "https://docs.craci.com/api/usage/"
---

Use the usage endpoint to retrieve the vCPU seconds recorded by CRACI's billing
system for completed jobs across your organization during a time range.

## Query organization usage

Supply an inclusive `start` timestamp and an exclusive `end` timestamp in RFC
3339 format:

```sh
curl \
  --header "Authorization: Bearer $CRACI_API_TOKEN" \
  "https://api.craci.dev/v1preview1/usage?start=2026-08-01T00%3A00%3A00Z&end=2026-09-01T00%3A00%3A00Z"
```

The response always contains the total usage in scope:

```json
{
  "start": "2026-08-01T00:00:00Z",
  "end": "2026-09-01T00:00:00Z",
  "total": {
    "vcpuSeconds": 7407
  }
}
```

A vCPU-second is one second of job execution multiplied by the number of vCPUs
assigned to the runner. For example, running a job for 60 seconds on a 4-vCPU
runner records 240 vCPU-seconds.

When no completed jobs fall in the requested period, `vcpuSeconds` is zero.

## When usage becomes available

CRACI sends usage to the billing system after a job finishes. New usage normally
appears shortly afterward, but delivery is asynchronous and may take longer
during retries or service disruption. A previous response for the same period
can therefore change when delayed usage arrives.

Each completed job is assigned wholly to the period containing its billing end
time. Jobs that have not finished are not included.

The endpoint reports metered usage. Usage from before your billing contract
started may be visible even though it was not included in an invoice.