Docs
Usage

Get your usage

GET
/v1/usage

Returns what your org used in each period from start until end, a UTC day unless granularity says otherwise, by meter and location, and by inference model and key when groupBy names them, from the hours closed so far. Compute counts while an instance's status is running: vCPUs and memory for a CPU size, GPUs for a spot GPU size, and nothing for a size whose reservation is paid for. Disks count from the instance's first running until it fails or its delete is asked for, so a create that never runs costs nothing, a dedicated IPv4 address while it is held, and egress as the bytes the instance sends. An hour closes 15 minutes after it ends and never changes after, so the totals are final up to closedThrough. Inference counts each request's tokens in the hour it finished: uncached input, cached input and output, each a meter of its own. A period, meter and location with no use is left out. Any valid credential can read it.

Authorization

headerAuthorizationBearer <cc_...>

An API key of your org, sent as Authorization: Bearer cc_.... Keys start with cc_ and are otherwise opaque. Treat a key as a password: anyone holding it can act with its scopes until it expires or is revoked. Each operation's security requirement lists the scopes it needs; an empty list means any valid key. The MCP server at /mcp accepts agent keys and no other kind.

Query Parameters

start?string

The first UTC day to return. Without it, the first day of the current month.

Formatdate
end?string

The UTC day after the last to return, at most 93 days after start. Without it, tomorrow.

Formatdate
granularity?string

How long each item's period is: a UTC day, the default, an hour, or a UTC month cut to start and end. By the hour, end is at most 31 days after start. Open set: another value is refused with a 400 that lists the values this version takes.

Default"day"
groupBy?array<string>

What to sum by besides the period, meter and location: model, the inference model a request named, and inferenceKey, the inference key it was made with. Use that is not inference has neither, and comes without them. Open set: another value is refused with a 400 that lists the values this version takes.

Itemsitems <= 2
meter?array<>

Only these meters.

Itemsitems <= 16
location?array<>

Only these locations.

Itemsitems <= 16
model?array<>

Only inference with these models, by the id a request names.

Itemsitems <= 16
inferenceKey?array<>

Only inference with these inference keys.

Itemsitems <= 16
pageSize?integer

The most items to return.

Range1 <= value <= 10000
Default10000
pageToken?string

The nextPageToken of the previous page, unchanged. Send the same filters with it.

Length1 <= length <= 2048

Header Parameters

Api-Version*string

The API version the request is written against. This document describes 2026-10-15. A missing header returns 400 api_version_required, and a version the API does not serve returns 400 unsupported_api_version.

X-Correlation-ID?string

An id of your own for this request, or for a group of requests, to find them in our logs and yours. Logged with the request and returned unchanged in X-Correlation-ID. The request id itself is always the API's own, in X-Request-ID.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin keys only: the id of the org to act in. Required with an admin key, together with Access-Reason; with any other credential it returns 400 invalid_request. Every request that carries it is recorded in that org's operator-access log.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin keys only: why the operator is acting in the org, such as a support ticket. Required with Org-Context. Recorded, verbatim, in the org's operator-access log.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Response Body

What your org used in each period, by meter and location.

application/json
  1. response

What your org used in each period from start until end.

start*string

The first UTC day.

Formatdate
end*string

The UTC day after the last.

Formatdate
closedThrough?string

The end of the last closed hour: the totals up to it are final, and use after it is not counted yet. Absent before any hour is closed.

Formatdate-time
items*array<>

Each period's use of each meter in each location, and of each model and key that groupBy names, by period, then meter, location, model and key.

nextPageToken?NextPageToken

Pass it back as pageToken for the next page. Absent on the last page.

Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/usage?start=2026-10-01&end=2026-11-01&granularity=day&groupBy=model&meter=output_tokens&location=us-west-1&model=example%2Fmodel-70b&inferenceKey=ik-7k2m9q4x1bfa&pageSize=10000&pageToken=eyJjIjoiMjAyNi0xMC0yMlQxNzowMjoxMVoiLCJpIjoiaS03azJtOXE0eDFiZmEifQ' \  -H 'Api-Version: 2026-10-15' \  -H 'X-Correlation-ID: rollout-2026-10-22' \  -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed'
Example Response
{  "start": "2026-10-26",  "end": "2026-10-28",  "closedThrough": "2026-10-27T23:00:00Z",  "items": [    {      "date": "2026-10-26",      "periodStart": "2026-10-26T00:00:00Z",      "periodEnd": "2026-10-27T00:00:00Z",      "meter": "vcpu_hours",      "location": "us-west-1",      "quantity": 12.5,      "unit": "vCPU-hours"    },    {      "date": "2026-10-26",      "periodStart": "2026-10-26T00:00:00Z",      "periodEnd": "2026-10-27T00:00:00Z",      "meter": "memory_gib_hours",      "location": "us-west-1",      "quantity": 50,      "unit": "GiB-hours"    },    {      "date": "2026-10-26",      "periodStart": "2026-10-26T00:00:00Z",      "periodEnd": "2026-10-27T00:00:00Z",      "meter": "storage_gib_hours",      "location": "us-west-1",      "quantity": 68.75,      "unit": "GiB-hours"    },    {      "date": "2026-10-26",      "periodStart": "2026-10-26T00:00:00Z",      "periodEnd": "2026-10-27T00:00:00Z",      "meter": "dedicated_ipv4_hours",      "location": "us-west-1",      "quantity": 6.25,      "unit": "address-hours"    },    {      "date": "2026-10-26",      "periodStart": "2026-10-26T00:00:00Z",      "periodEnd": "2026-10-27T00:00:00Z",      "meter": "egress_gb",      "location": "us-west-1",      "quantity": 1.204,      "unit": "GB"    },    {      "date": "2026-10-27",      "periodStart": "2026-10-27T00:00:00Z",      "periodEnd": "2026-10-28T00:00:00Z",      "meter": "vcpu_hours",      "location": "us-west-1",      "quantity": 46,      "unit": "vCPU-hours"    }  ]}