List your usage by instance
Returns what each of your org's instances used from start until
end, one line per instance, meter and UTC month, or hour with
granularity=hour: the lines your usage, and your bill, add up to.
Lines come oldest first, then by instance and meter. Each counts as
GET /v1/usage describes, and is final up to closedThrough. Hours
closed before linesFrom have no lines; GET /v1/usage has their
totals.
AuthorizationBearer <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.
Scope: instances:read
start?stringThe first UTC day to return. Without it, the first day of the current month.
dateend?stringThe UTC day after the last to return, at most 93 days after
start. Without it, tomorrow.
dategranularity?stringHow long each line's period is: a UTC month, the default, cut to
start and end, or an hour. Open set: another value is refused
with a 400 that lists the values this version takes.
"month"project?array<>Only instances in these projects. Every org has one project, default, in this version.
items <= 16location?array<>Only these locations.
items <= 16instance?array<>Only these instances.
items <= 16pageSize?integerThe most items to return.
1 <= value <= 10050pageToken?stringThe nextPageToken of the previous page, unchanged. Send the same
filters with it.
1 <= length <= 2048Api-Version*stringThe 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?stringAn 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.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin 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.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin 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.
^[^\x00-\x1F\x7F]+$10 <= length <= 500A page of what your instances used.
application/json- response
A page of what your instances used, line by line.
closedThrough?stringThe end of the last closed hour: lines up to it are final, and use after it is not counted yet. Absent before any hour is closed.
date-timelinesFrom?stringThe start of the first hour closed with its instances' lines.
Hours before it have only the totals of GET /v1/usage. Absent
before any such hour is closed.
date-timeitems*array<>nextPageToken?NextPageTokenPass it back as pageToken for the next page. Absent on the last page.
curl -X GET 'https://api.cloud.confidential.ai/v1/usage/lines?start=2026-10-01&end=2026-11-01&granularity=month&project=default&location=us-west-1&instance=i-7k2m9q4x1bfa&pageSize=50&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'{ "closedThrough": "2026-10-27T23:00:00Z", "linesFrom": "2026-10-26T00:00:00Z", "items": [ { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-10-28T00:00:00Z", "resourceType": "instance", "resourceId": "i-7k2m9q4x1bfa", "resourceName": "train-1", "project": "default", "location": "us-west-1", "meter": "vcpu_hours", "quantity": 12.5, "unit": "vCPU-hours" }, { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-10-28T00:00:00Z", "resourceType": "instance", "resourceId": "i-7k2m9q4x1bfa", "resourceName": "train-1", "project": "default", "location": "us-west-1", "meter": "memory_gib_hours", "quantity": 50, "unit": "GiB-hours" }, { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-10-28T00:00:00Z", "resourceType": "instance", "resourceId": "i-7k2m9q4x1bfa", "resourceName": "train-1", "project": "default", "location": "us-west-1", "meter": "storage_gib_hours", "quantity": 68.75, "unit": "GiB-hours" }, { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-10-28T00:00:00Z", "resourceType": "instance", "resourceId": "i-7k2m9q4x1bfa", "resourceName": "train-1", "project": "default", "location": "us-west-1", "meter": "dedicated_ipv4_hours", "quantity": 6.25, "unit": "address-hours" }, { "periodStart": "2026-10-01T00:00:00Z", "periodEnd": "2026-10-28T00:00:00Z", "resourceType": "instance", "resourceId": "i-7k2m9q4x1bfa", "resourceName": "train-1", "project": "default", "location": "us-west-1", "meter": "egress_gb", "quantity": 1.204, "unit": "GB" } ]}Get your usage GET
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.
Get your cost GET
Returns what your org's use cost in each period from `start` until `end`, in US dollars, summed by what `groupBy` names, with the periods, filters and finality of `GET /v1/usage`. Without `groupBy`, each period is one amount. It covers inference, each request priced at its model's price when it finished. Only people signed in to the console can read it.