Get usage

Gets usage details for a given billing hour.

Required permission

Organisation > Admin > Billing > Read

Path parameters

timestamp
string required
Unix timestamp of the billing hour

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.
teamsPage
integer
The page number of teams to access.
teamsPerPage
integer
The number of teams to return per page. Maximum of 100.
projectsPage
integer
The page number of projects to access.
projectsPerPage
integer
The number of projects to return per page. Maximum of 100.
resourcesPage
integer
The page number of resources to access.
resourcesPerPage
integer
The number of resources to return per page. Maximum of 100.

Response body

{object}
Response object.

data
{object} required
Result data.

timestamp
number
The Unix timestamp of the billing hour.
currency
string
The currency code.
total
number
Total spend for this hour, across every category it reports. Summed before rounding, so it can differ from adding the categories below by a sub-cent amount. It tracks `paas.price`, so a `teamId`/`projectId`/`resourceType` filter does NOT reduce it — the filter narrows the breakdown under `paas.teams[]` while `paas.price` stays the hour's full PaaS total, and only the customer-level categories drop out. For a team-scoped caller it is that team's own spend, since no customer-level figures are reported at all. (The `/usage` list differs: a filter there replaces the PaaS figure with the filtered slice.)
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.

paas
{object}
The PaaS usage breakdown for this hour. The drill-down depth follows the active filters, but `price` and `usage` above the breakdown remain the customer-level totals — a filter narrows `teams[]`, not the figures it sits under. A team-scoped caller instead gets its own team as those totals.

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

teams
[array] required
An array of teams with price and usage totals. Projects are included when a teamId, projectId or resourceType filter is applied. Resources are included when a projectId or resourceType filter is applied. Depth and the paged unit follow the active filters alone, never the number of teams, so an unfiltered response is always teams-only. The paged unit is reported as `pagination.unit`; page through it with that level's page parameters (e.g. `teamsPage`/`teamsPerPage`) until `pagination.hasNextPage` is false.

{object}

id
string
Identifier for the team.
name
string
The name of the team.
price
{object}
The team's PaaS price. When a projectId or resourceType filter is applied, this reflects only the filtered slice (e.g. one project, or one resource type across the team).

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

projects
[array]
An array of projects for this team. Present when a teamId, projectId or resourceType filter is applied.

{object}

id
string
Identifier for the project.
name
string
The name of the project.
price
{object}
The project's PaaS price. When a resourceType filter is applied, this reflects only that resource type's spend within the project.

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

resources
[array]
Resources grouped by type. Present when a projectId or resourceType filter is applied.

{object}

resourceType
string
The type of the resource (service, job, harness, addon, volume, etc.).
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

items
[array]
The resources of this type.

{object}

id
string
Identifier for the resource.
name
string
The name of the resource.
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

duration
number
Seconds the resource was billed for.

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.

clusters
[array]
Cluster-level BYOC usage and allocated spend. Present on invoice and hourly usage detail responses.

{object}

id
string
Identifier for the cluster.
name
string
The cluster name.
price
{object}
Allocated BYOC spend for this cluster. The customer-level rate is apportioned by each resource component’s share of the customer total, so this is a reporting allocation rather than an independently billed cluster price. Its total is not rounded so all cluster totals remain reconcilable with the customer total.

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.
total
number
The allocated cluster BYOC price. Kept unrounded so cluster totals reconcile with the customer BYOC total.

usage
{object}
BYOC resource-hours consumed by this cluster.

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/{timestamp}

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

Example response

200 OK

Hourly usage detail.

JSON

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