> ## Documentation Index > Fetch the complete documentation index at: https://docs.runpod.io/llms.txt > Use this file to discover all available pages before exploring further. # Get aggregated billing history > 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. ## OpenAPI ````yaml get /v2/billing openapi: 3.1.0 info: title: Runpod REST API version: 2.0.0 description: Runpod public REST API — v2 servers: - url: https://api.runpod.io description: Runpod API v2 production server security: - bearerAuth: [] tags: - name: Pods description: GPU and CPU pod lifecycle, configuration, actions, and log streaming. - name: Serverless description: >- Serverless endpoint lifecycle, worker visibility, releases, and worker log streaming. - name: Templates description: Reusable pod and endpoint configuration templates. - name: Network Volumes description: Persistent network storage volumes for workloads. - name: Registries description: Container registry credentials used to pull private images. - name: Catalog description: Available GPU, CPU, and data center catalog metadata. - name: Billing description: Billing history and usage cost records across resource types. paths: /v2/billing: get: tags: - Billing summary: Get aggregated billing history description: > 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. operationId: listBilling parameters: - $ref: '#/components/parameters/BillingStartTime' - $ref: '#/components/parameters/BillingEndTime' - $ref: '#/components/parameters/BillingBucketSize' - $ref: '#/components/parameters/BillingLastN' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListBillingResponse' examples: billing: summary: Successful response value: records: - startTime: '2026-06-01T00:00:00Z' endTime: '2026-06-02T00:00:00Z' totalAmount: 42.34 podGpuAmount: 18.2 podCpuAmount: 0 podDiskAmount: 1.1 serverlessGpuAmount: 12.6 serverlessCpuAmount: 0 serverlessDiskAmount: 0.44 serverlessFeeAmount: 1.25 storageStandardAmount: 0 storageHighPerformanceAmount: 2.5 endpointAmount: 3.21 clusterGpuAmount: 2.5 clusterDiskAmount: 0.3 clusterNetworkingAmount: 0.24 metadata: query: startTime: '2026-06-01T00:00:00Z' endTime: '2026-06-02T00:00:00Z' bucketSize: day recordCount: 1 totals: totalAmount: 42.34 podGpuAmount: 18.2 podCpuAmount: 0 podDiskAmount: 1.1 serverlessGpuAmount: 12.6 serverlessCpuAmount: 0 serverlessDiskAmount: 0.44 serverlessFeeAmount: 1.25 storageStandardAmount: 0 storageHighPerformanceAmount: 2.5 endpointAmount: 3.21 clusterGpuAmount: 2.5 clusterDiskAmount: 0.3 clusterNetworkingAmount: 0.24 '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '429': $ref: '#/components/responses/TooManyRequestsError' default: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: BillingStartTime: name: startTime in: query required: false description: > Start of the billing period (RFC 3339). Defaults to 30 days ago. Snapped down to the start of its bucketSize bucket so the window aligns with the returned records; provide a boundary-aligned value (e.g. midnight for bucketSize=day) to avoid widening. schema: type: string format: date-time example: '2026-05-01T00:00:00Z' BillingEndTime: name: endTime in: query required: false description: > End of the billing period (RFC 3339), exclusive. Defaults to now. Snapped up to the end of the bucketSize bucket it lands in (unless already on a boundary) so the window aligns with the returned records. schema: type: string format: date-time example: '2026-06-01T00:00:00Z' BillingBucketSize: name: bucketSize in: query required: false description: Length of each billing time bucket. Defaults to day. schema: $ref: '#/components/schemas/BillingBucketSize' BillingLastN: name: lastN in: query required: false description: > Return the last N buckets of bucketSize, ending with the current (in-progress) bucket — e.g. lastN=100 with bucketSize=day is "last 100 days". The resolved window is aligned to bucket boundaries: startTime is the start of the earliest bucket (e.g. midnight of the earliest day) and endTime is the end of the current bucket. Mutually exclusive with startTime/endTime; provide one or the other, not both. schema: type: integer minimum: 1 example: 30 schemas: ListBillingResponse: type: object description: Aggregated billing records across all Runpod resources. required: - records - metadata properties: records: type: array items: $ref: '#/components/schemas/BillingRecord' metadata: $ref: '#/components/schemas/BillingMetadata' ErrorResponse: type: object required: - title - status - detail properties: title: type: string description: Short human-readable summary examples: - Not Found status: type: integer description: HTTP status code examples: - 404 detail: type: string description: Human-readable explanation examples: - pod not found errors: type: array description: Individual request-validation failures. items: type: string examples: - - '$: additional properties ''bogus'' not allowed' BillingBucketSize: type: string enum: - hour - day - week - month - year x-enum-varnames: - BillingBucketSizeHour - BillingBucketSizeDay - BillingBucketSizeWeek - BillingBucketSizeMonth - BillingBucketSizeYear default: day description: Length of each billing time bucket. examples: - day BillingRecord: description: > A single time-bucketed record of total spend across all billable Runpod resources, with each cost component broken out. Returned by GET /v2/billing. allOf: - $ref: '#/components/schemas/BillingTimeRange' - $ref: '#/components/schemas/BillingAmounts' BillingMetadata: type: object required: - query - recordCount - totals properties: query: $ref: '#/components/schemas/BillingQuery' recordCount: type: integer description: Number of records returned. totals: $ref: '#/components/schemas/BillingAmounts' BillingTimeRange: type: object description: > 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. required: - startTime - endTime properties: startTime: type: string format: date-time description: Start of the range, inclusive (RFC 3339). examples: - '2026-06-01T00:00:00Z' endTime: type: string format: date-time description: End of the range, exclusive (RFC 3339). examples: - '2026-06-02T00:00:00Z' BillingAmounts: type: object description: > 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. required: - totalAmount - podGpuAmount - podCpuAmount - podDiskAmount - serverlessGpuAmount - serverlessCpuAmount - serverlessDiskAmount - serverlessFeeAmount - storageStandardAmount - storageHighPerformanceAmount - endpointAmount - clusterGpuAmount - clusterDiskAmount - clusterNetworkingAmount properties: totalAmount: type: number format: double description: Total cost in USD for the bucket across all resources. examples: - 42.34 podGpuAmount: type: number format: double description: GPU pod compute cost in USD for the bucket. podCpuAmount: type: number format: double description: CPU pod compute cost in USD for the bucket. podDiskAmount: type: number format: double description: Pod disk cost in USD for the bucket. serverlessGpuAmount: type: number format: double description: Serverless GPU compute cost in USD for the bucket. serverlessCpuAmount: type: number format: double description: Serverless CPU compute cost in USD for the bucket. serverlessDiskAmount: type: number format: double description: Serverless disk cost in USD for the bucket. serverlessFeeAmount: type: number format: double description: Serverless platform fee in USD for the bucket. storageStandardAmount: type: number format: double description: Standard network volume storage cost in USD for the bucket. storageHighPerformanceAmount: type: number format: double description: High-performance network volume storage cost in USD for the bucket. endpointAmount: type: number format: double description: Runpod public endpoint cost in USD for the bucket. clusterGpuAmount: type: number format: double description: Instant Cluster GPU compute cost in USD for the bucket. clusterDiskAmount: type: number format: double description: Instant Cluster disk cost in USD for the bucket. clusterNetworkingAmount: type: number format: double description: Instant Cluster inter-node networking cost in USD for the bucket. BillingQuery: description: Resolved query window and granularity (routes without a filter). allOf: - $ref: '#/components/schemas/BillingTimeRange' - type: object required: - bucketSize properties: bucketSize: $ref: '#/components/schemas/BillingBucketSize' responses: UnauthorizedError: description: >- Authentication failed because the bearer token is missing, malformed, expired, or invalid. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingBearerToken: summary: Missing bearer token value: title: Unauthorized status: 401 detail: missing bearer token ForbiddenError: description: >- The bearer token is valid, but it does not grant access to the requested resource or action. content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientAccess: summary: Insufficient access value: title: Forbidden status: 403 detail: access denied TooManyRequestsError: description: > 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. headers: Retry-After: description: Seconds to wait before retrying, per the exceeded window. schema: type: integer example: 12 RateLimit: description: > Live per-window state as a structured-field list — one member per window (`minute`, `hour`, `day`) with remaining count `r` and seconds-until-reset `t`. schema: type: string example: '"minute";r=0;t=12, "hour";r=2800;t=1812, "day";r=49500;t=45012' RateLimit-Policy: description: > Static quota policy as a structured-field list — one member per window with quota `q` and window length `w` (seconds). schema: type: string example: '"minute";q=60;w=60, "hour";q=3000;w=3600, "day";q=50000;w=86400' content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Rate limit exceeded value: title: Too Many Requests status: 429 detail: rate limit exceeded for the minute window securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Runpod API Key description: > Runpod API key authentication. Generate an API key in the Runpod console and send it in the `Authorization` header as `Bearer `. Keys are scoped to the permissions granted when created; requests may return `403` when a valid key lacks access to the requested resource or action. ````