List invoices

Lists finalized invoices.

Required permission

Organisation > Admin > Billing > Read

Query parameters

cursor
string
The cursor returned from the previous page of results, used to request the next page.
perPage
integer
The number of results to display per request. Maximum of 100 results per page.
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.

Response body

{object}
Response object.

data
{object} required
Result data.

invoices
[array]

{object}

id
string
Identifier for the invoice.
period
{object}

start
number
The start of the billing period, as a Unix timestamp.
end
number
The end of the billing period, as a Unix timestamp.

currency
string
The currency code.
status
string
The invoice payment status, as reported by Stripe. `open` is finalized and awaiting payment — including while a payment is in flight or awaiting authentication — `uncollectible` has been written off, and `void` has been cancelled. `payment_failed` is only reported for invoices with no Stripe status to defer to.
one of
draft, open, payment_failed, paid, uncollectible, void
total
number
The total cost of the invoice, including tax. Omitted for a team-scoped caller.
subTotal
number
The subtotal before tax and discounts. Omitted for a team-scoped caller.
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 price and usage totals for the period. Customer-level, except for a team-scoped caller, where it is that team's own slice — PaaS is the one category with a per-team tier, so it is reported rather than withheld. Drill into it per project and resource on the invoice detail endpoint.

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}
The customer-level BYOC price and usage totals for the period. Omitted for a team-scoped caller: BYOC is aggregated to the customer and has no per-team tier.

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 for the period. Omitted 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 for the period. Omitted 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.

API

CLI

JS Client

GET /v1/billing/invoices

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

Example response

200 OK

A list of invoices.

JSON

{
  "data": {
    "invoices": [
      {
        "currency": "usd",
        "status": "paid",
        "paas": {
          "price": {
            "total": 69.22
          }
        }
      }
    ]
  },
  "pagination": {
    "hasNextPage": false,
    "count": 1
  }
}