List usage

Lists usage entries at hourly, daily, monthly, or total granularity.

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.
min length
24
max length
24
projectId
string
A project ID, or a comma-separated list of project IDs.
resourceType
string
A resource type, or a comma-separated list of resource types to filter by (e.g. service,job,addon).
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
(multiple options: anyOf)
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.

string required

min length

max length

string required

pattern

^\d+$

perPage
integer
The number of results to display per request. Maximum of 100 normally, 24 when `breakdown=true`, or 12 when `granularity=month` — a monthly page covers far more billing hours than the other granularities. Defaults to 12 for `granularity=month`, 24 for other breakdown requests, and 50 otherwise.
min
1
max
100
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
breakdown
boolean
Include the PaaS team, project, resource type and resource hierarchy for each hourly or monthly entry. Only supported with granularity=hour or granularity=month, and caps perPage at 24 (or 12 for monthly entries).
projectsCursor
string
The cursor returned from the previous breakdown project page. Use it with breakdown=true.
min length
24
max length
24
projectsPerPage
integer
The number of projects selected for each usage entry when breakdown=true. With an explicit projectId list, it is the maximum allowed list size. Maximum of 100.
min
1
max
100
fields
string
Set to usage to omit price and monetary total fields from the response.
one of
usage
order
string
The timeline order. Defaults to desc (newest first).
one of
asc, desc

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. 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.

breakdownPagination
{object} required
The shared project page used by every hourly or monthly entry when breakdown=true. Omitted when an explicit projectId filter selects the projects.

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

usage
[array]
An array of usage entries in the requested order.

{object}

timestamp
number
The Unix timestamp of the entry. Hourly entries use the end of their represented period; day and month entries use the start of their UTC bucket.
period
{object}
The time span represented by this entry. Hourly entries end at timestamp; day and month entries use UTC calendar boundaries, clamped to the requested time range.

start
number
The inclusive start of the usage entry, as a Unix timestamp.
end
number
The exclusive end of the usage entry, as a Unix timestamp.

currency
string
The currency code.
total
number
Total spend for this entry, across every category it reports. Omitted when fields=usage. 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 is omitted when fields=usage.

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
duration
number
Seconds attributable to builds.

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

vcpuHours
number
memoryGiBHours
number
duration
number
Seconds attributable to running workloads.

teams
[array]
PaaS hierarchy, present when breakdown=true for hourly or monthly entries.

{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 selected resource types 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
duration
number
Seconds attributable to builds.

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

vcpuHours
number
memoryGiBHours
number
duration
number
Seconds attributable to running workloads.

projects
[array]
An array of projects for this team. Present when a teamId, projectId or resourceType filter is applied, or when a usage-list request uses breakdown=true.

{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 the selected resource type or types' 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
duration
number
Seconds attributable to builds.

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

vcpuHours
number
memoryGiBHours
number
duration
number
Seconds attributable to running workloads.

resources
[array]
Resources grouped by type. Present when a projectId or resourceType filter is applied, or when a usage-list request uses breakdown=true.

{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
duration
number
Seconds attributable to builds.

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

vcpuHours
number
memoryGiBHours
number
duration
number
Seconds attributable to running workloads.

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
duration
number
Seconds attributable to builds.

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

vcpuHours
number
memoryGiBHours
number
duration
number
Seconds attributable to running workloads.

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.

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

GET /v1/billing/usage

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

Example response

200 OK

A list of usage entries.

JSON

{
  "data": {
    "breakdownPagination": {
      "hasNextPage": false,
      "count": 1,
      "unit": "days"
    },
    "usage": [
      {
        "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"
  }
}