> ## 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 pod billing history > Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family. ## OpenAPI ````yaml get /v2/billing/pods 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/pods: get: tags: - Billing summary: Get pod billing history description: > Returns pod-only billing detail for the authenticated user, split into time buckets by startTime/endTime with bucketSize or by lastN recent buckets. Use podId to narrow the response to one GPU or CPU pod; without it, records are emitted per pod per bucket. Each record includes podId, GPU, CPU, disk, and total amounts, while metadata echoes the resolved query and totals across the pod records. Use listBilling when you need aggregate spend across every billable resource family. operationId: listPodBilling parameters: - $ref: '#/components/parameters/BillingStartTime' - $ref: '#/components/parameters/BillingEndTime' - $ref: '#/components/parameters/BillingBucketSize' - $ref: '#/components/parameters/BillingLastN' - name: podId in: query required: false description: Filter to a specific pod (GPU or CPU). schema: type: string example: pod_abc123 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListPodBillingResponse' examples: podBilling: summary: Successful response value: records: - startTime: '2026-06-01T00:00:00Z' endTime: '2026-06-02T00:00:00Z' podId: 7h9k2m4n6p totalAmount: 12.34 gpuAmount: 11.1 cpuAmount: 0 diskAmount: 1.24 metadata: query: startTime: '2026-06-01T00:00:00Z' endTime: '2026-06-02T00:00:00Z' bucketSize: day podId: 7h9k2m4n6p recordCount: 1 totals: totalAmount: 12.34 gpuAmount: 11.1 cpuAmount: 0 diskAmount: 1.24 uniquePodCount: 1 '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: ListPodBillingResponse: type: object description: Billing records for pods. required: - records - metadata properties: records: type: array items: $ref: '#/components/schemas/PodBillingRecord' metadata: $ref: '#/components/schemas/PodBillingMetadata' 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 PodBillingRecord: description: > A single time-bucketed pod billing record, covering both GPU and CPU pods. Returned by GET /v2/billing/pods. allOf: - $ref: '#/components/schemas/BillingTimeRange' - $ref: '#/components/schemas/PodBillingAmounts' - type: object required: - podId properties: podId: type: string description: > The pod this record bills. When the podId filter is set every record carries that id; otherwise one record is emitted per pod per bucket. examples: - pod_abc123 PodBillingMetadata: type: object required: - query - recordCount - uniquePodCount - totals properties: query: $ref: '#/components/schemas/PodBillingQuery' recordCount: type: integer description: Number of records returned (buckets times distinct pods). uniquePodCount: type: integer description: Number of distinct pods the records span. totals: $ref: '#/components/schemas/PodBillingAmounts' 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' PodBillingAmounts: type: object description: > Pod cost components covering both GPU and CPU pods. Backs a record's amounts and the metadata totals. required: - totalAmount - gpuAmount - cpuAmount - diskAmount properties: totalAmount: type: number format: double description: Total pod cost in USD for the bucket. examples: - 12.34 gpuAmount: type: number format: double description: GPU pod compute cost in USD for the bucket. cpuAmount: type: number format: double description: CPU pod compute cost in USD for the bucket. diskAmount: type: number format: double description: Pod disk cost in USD for the bucket. PodBillingQuery: allOf: - $ref: '#/components/schemas/BillingQuery' - type: object properties: podId: type: - string - 'null' description: The podId filter applied, if any. 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. ````