List usage

Lists hourly usage entries.

Required permission

Organisation > Admin > Billing > Read

Query parameters

teamId
string
The ID of the team to filter by. Not accepted from a token that can only read one team — a team billed in its own right, or a team token reading an org's billing — since those responses already cover that team and no other, and start at the project level without it.
projectId
string
The ID of the project to filter by.
resourceType
string
The resource type to filter by (e.g. service, job, harness, addon, volume).
one of
job, service, harness, addon, volume
removeLegacyFields
boolean
For a billing entity temporarily receiving the legacy billing API contract, return the current contract instead. Use the current query parameters with this option.
cursor

The cursor returned from the previous page of results — a Unix timestamp: the last emitted hour for `granularity=hour`, the last emitted bucket otherwise. Pass it back as returned rather than constructing one.
perPage
integer
The number of results to display per request. Maximum of 100, or 12 when `granularity=month` — a monthly page covers far more billing hours than the other granularities. Defaults to 12 for `granularity=month`, 50 otherwise.
startTime
integer
The Unix timestamp to start from (inclusive).
endTime
integer
The Unix timestamp to end at (exclusive). Requires startTime.
granularity
string
The size of each returned entry. `hour` (default) returns raw billing hours. `day` and `month` roll hours into UTC calendar buckets and page over those buckets with `perPage` + `cursor`, walking back to the start of the account's usage history when no `startTime` is given. `total` sums the whole window into one entry, so it reads every hour at once and requires both `startTime` and `endTime`, no more than 366 days apart.
one of
total, hour, day, month

Response body

{object}
Response object.

data
{object} required
Result data.

granularity
string
The granularity each entry represents.
one of
total, hour, day, month
window
{object}
The span the entries on this page cover, on bucket boundaries — not the full range paging will reach. Entries carry only their start, so this is what states where the newest one ends; the newest bucket is usually still in progress, so `end` is normally in the future. Returned for the bucketed granularities, and omitted by a page past the end of the usage history, which covers no buckets.

start
number
The oldest returned bucket's start, inclusive, as a Unix timestamp.
end
number
The newest returned bucket's end, exclusive, as a Unix timestamp.

scope
{object}
Present when the response is narrowed to the caller's own entity.

entityType
string
The entity the response is limited to.
one of
team
entityId
string
Identifier of that entity.

usage
[array]
An array of usage entries, newest first.

{object}

timestamp
number
The Unix timestamp of the entry. For bucketed granularities this is the start of the bucket.
currency
string
The currency code.
total
number
Total spend for this entry, across every category it reports. Summed before rounding, so it can differ from adding the categories below by a sub-cent amount. When a team, project or resourceType filter is active — or for a team-scoped caller — the customer-level categories are absent, so this is the spend in that scope rather than what the period cost the customer.
paas
{object}
The PaaS usage for this entry.

price
{object}

total
number
The total PaaS price, rounded to 2 decimal places.
cpu
number
The CPU usage price.
memory
number
The memory usage price.
storage
number
The storage usage price.
gpu
number
The GPU usage price.

usage
{object}

vcpuHours
number
vCPU hours consumed.
memoryGiBHours
number
Memory GiB-hours consumed.
storageGiBHours
number
Storage GiB-hours consumed.
gpuSpotHours
number
Spot GPU hours consumed.
gpuOnDemandHours
number
On-demand GPU hours consumed.
build
{object}
The share of the usage attributable to builds.

vcpuHours
number
memoryGiBHours
number

run
{object}
The share of the usage attributable to running workloads.

vcpuHours
number
memoryGiBHours
number

byoc
{object}
Customer-level BYOC usage. Omitted when a team, project or resourceType filter is active, or for a team-scoped caller.

price
{object}
The customer-level BYOC price total. Always reflects the full customer total, regardless of drill-down filters.

total
number
The total BYOC price, rounded to 2 decimal places.
vcpu
number
The vCPU usage price.
memory
number
The memory usage price.
gpuMemory
number
The GPU memory usage price.
cluster
number
The cluster usage price.

usage
{object}
Customer-level BYOC usage hours.

vcpuHours
number
vCPU hours consumed.
memoryGiBHours
number
Memory GiB-hours consumed.
clusterHours
number
Cluster hours consumed.
gpuMemoryGiBHours
number
GPU memory GiB-hours consumed.

egressIp
{object}
Egress IP spend. Customer-level, so omitted when a team, project or resourceType filter is active, or for a team-scoped caller.

price
{object}

total
number
The total price, rounded to 2 decimal places.

usage
{object}

hours
number
Hours consumed.

loadBalancer
{object}
Load balancer spend. Customer-level, so omitted when a team, project or resourceType filter is active, or for a team-scoped caller.

price
{object}

total
number
The total price, rounded to 2 decimal places.

usage
{object}

hours
number
Hours consumed.

pagination
{object} required
Data about the endpoint pagination.

hasNextPage
boolean required
Is there another page of results available?
cursor
string
The cursor to access the next page of results.
count
number required
The number of results returned by this request.
unit
string
What this page counts.
one of
teams, projects, resources, hours, days, months, total

API

CLI

JS Client

GET /v1/billing/usage

GET /v1/teams/{teamId}/billing/usage

Example response

200 OK

A list of usage entries.

JSON

{
  "data": {
    "usage": [
      {
        "currency": "usd",
        "total": 69.22,
        "paas": {
          "price": {
            "total": 69.22
          }
        }
      }
    ]
  },
  "pagination": {
    "hasNextPage": false,
    "count": 1,
    "unit": "days"
  }
}