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

# Get aggregated billing history

`GET /v2/billing`

Returns time-bucketed total spend across all billable Runpod resources for the authenticated user. Use startTime/endTime with bucketSize for an explicit range, or lastN with bucketSize for the most recent buckets. Each record reports one bucket's total plus pod, serverless, storage, public endpoint, and Instant Cluster cost components. The metadata block echoes the resolved query window, record count, and totals across all returned buckets.

## Query parameters

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

## Response `200`

OK

- ListBillingResponse — Aggregated billing records across all Runpod resources.
  - `records` BillingRecord[], 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 cost in USD for the bucket across all resources.
    - `podGpuAmount` number, double, required — GPU pod compute cost in USD for the bucket.
    - `podCpuAmount` number, double, required — CPU pod compute cost in USD for the bucket.
    - `podDiskAmount` number, double, required — Pod disk cost in USD for the bucket.
    - `serverlessGpuAmount` number, double, required — Serverless GPU compute cost in USD for the bucket.
    - `serverlessCpuAmount` number, double, required — Serverless CPU compute cost in USD for the bucket.
    - `serverlessDiskAmount` number, double, required — Serverless disk cost in USD for the bucket.
    - `serverlessFeeAmount` number, double, required — Serverless platform fee in USD for the bucket.
    - `storageStandardAmount` number, double, required — Standard network volume storage cost in USD for the bucket.
    - `storageHighPerformanceAmount` number, double, required — High-performance network volume storage cost in USD for the bucket.
    - `endpointAmount` number, double, required — Runpod public endpoint cost in USD for the bucket.
    - `clusterGpuAmount` number, double, required — Instant Cluster GPU compute cost in USD for the bucket.
    - `clusterDiskAmount` number, double, required — Instant Cluster disk cost in USD for the bucket.
    - `clusterNetworkingAmount` number, double, required — Instant Cluster inter-node networking cost in USD for the bucket.
  - `metadata` BillingMetadata, required
    - `query` BillingQuery, 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.
    - `recordCount` integer, required — Number of records returned.
    - `totals` BillingAmounts, required — Total spend across all billable Runpod resources with each cost component broken out, fully prefixed by resource. Backs the aggregate record's amounts and the metadata totals.
      - `totalAmount` number, double, required — Total cost in USD for the bucket across all resources.
      - `podGpuAmount` number, double, required — GPU pod compute cost in USD for the bucket.
      - `podCpuAmount` number, double, required — CPU pod compute cost in USD for the bucket.
      - `podDiskAmount` number, double, required — Pod disk cost in USD for the bucket.
      - `serverlessGpuAmount` number, double, required — Serverless GPU compute cost in USD for the bucket.
      - `serverlessCpuAmount` number, double, required — Serverless CPU compute cost in USD for the bucket.
      - `serverlessDiskAmount` number, double, required — Serverless disk cost in USD for the bucket.
      - `serverlessFeeAmount` number, double, required — Serverless platform fee in USD for the bucket.
      - `storageStandardAmount` number, double, required — Standard network volume storage cost in USD for the bucket.
      - `storageHighPerformanceAmount` number, double, required — High-performance network volume storage cost in USD for the bucket.
      - `endpointAmount` number, double, required — Runpod public endpoint cost in USD for the bucket.
      - `clusterGpuAmount` number, double, required — Instant Cluster GPU compute cost in USD for the bucket.
      - `clusterDiskAmount` number, double, required — Instant Cluster disk cost in USD for the bucket.
      - `clusterNetworkingAmount` number, double, required — Instant 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)