---
title: "Get Instant Cluster billing history"
method: GET
path: "/v2/billing/clusters"
tags: ["Billing"]
---

# Get Instant Cluster billing history

`GET /v2/billing/clusters`

Returns Instant Cluster billing history for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use clusterId to filter to one cluster; without it, records are emitted per cluster per bucket. Each record includes GPU compute, disk, inter-node networking, and total amounts. Instant Clusters are GPU-only, so no CPU cost component is returned.

## Query parameters

- `startTime` string, date-time
- `endTime` string, date-time
- `bucketSize` 'hour' | 'day' | 'week' | 'month' | 'year' — Length of each billing time bucket.
- `lastN` integer
- `clusterId` string

## Response `200`

OK

- ListClusterBillingResponse — Time-bucketed Instant Cluster billing records plus metadata for the resolved query, record count, distinct cluster count, and compute totals.
  - `records` ClusterBillingRecord[], required
    - `startTime` string, date-time, required — Start of the range, inclusive (RFC 3339).
    - `endTime` string, date-time, required — End of the range, exclusive (RFC 3339).
    - `totalAmount` number, double, required — Total Instant Cluster cost in USD for the bucket.
    - `gpuAmount` number, double, required — Cluster GPU compute cost in USD for the bucket.
    - `diskAmount` number, double, required — Cluster disk cost in USD for the bucket.
    - `networkingAmount` number, double, required — Cluster inter-node networking cost in USD for the bucket.
    - `clusterId` string, required — The Instant Cluster this record bills. When the clusterId filter is set every record carries that id; otherwise one record is emitted per cluster per bucket.
  - `metadata` ClusterBillingMetadata, required
    - `query` ClusterBillingQuery, required — Half-open time range [startTime, endTime) in RFC 3339. On a record it is the time bucket; on a query echo it is the resolved window.
      - `startTime` string, date-time, required — Start of the range, inclusive (RFC 3339).
      - `endTime` string, date-time, required — End of the range, exclusive (RFC 3339).
      - `bucketSize` 'hour' | 'day' | 'week' | 'month' | 'year', required — Length of each billing time bucket.
      - `clusterId` string, nullable — The clusterId filter applied, if any.
    - `recordCount` integer, required — Number of records returned (buckets times distinct clusters).
    - `uniqueClusterCount` integer, required — Number of distinct clusters the records span.
    - `totals` ClusterBillingAmounts, required — Instant Cluster cost components (GPU-only, no CPU). Backs a record's amounts and the metadata totals.
      - `totalAmount` number, double, required — Total Instant Cluster cost in USD for the bucket.
      - `gpuAmount` number, double, required — Cluster GPU compute cost in USD for the bucket.
      - `diskAmount` number, double, required — Cluster disk cost in USD for the bucket.
      - `networkingAmount` number, double, required — Cluster inter-node networking cost in USD for the bucket.

## Other responses

- `401` — Authentication failed because the bearer token is missing, malformed, expired, or invalid.
- `403` — The bearer token is valid, but it does not grant access to the requested resource or action.
- `429` — The caller exceeded its per-user rate limit. The response identifies the window that was exceeded and how long to wait. The `RateLimit` and `RateLimit-Policy` headers (per the IETF ratelimit-headers draft) also accompany successful responses, so clients can track quota before a 429.
- `default` — Error

---

[API](https://skmtc.net/runpod/apis/runpod-rest-api.md) · [All operations](https://skmtc.net/runpod/apis/runpod-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runpod/runpod-rest-api/versions/504cd0394ed6/schema)