Cloud Billing API

The Temporal Cloud Billing API provides Namespace-level cost attribution through on-demand billing reports. These reports are generated asynchronously and can be accessed with an object endpoint or downloaded in CSV format for analysis by FinOps professionals and Temporal Cloud operators.

This API is part of the Cloud Operations API.

Support, stability, and dependency info

The Temporal Cloud Billing API is in Pre-release.

The Billing API allows you to:

• Generate billing reports for specified invoice months
• Retrieve report status and metadata
• Correlate report generation with async operations
• Download CSV reports
• Integrate billing reports into internal analytics tooling and cloud cost management platforms

The Billing API contains:

• Accurate Namespace-level cost attribution
• Down to hourly granularity
• Alignment with the FOCUS schema

For complete request and response schemas, refer to the Protocol Buffer definitions below.

Billing report generation is asynchronous. You initiate report creation, then poll for completion.

Report data granularity

Reports can be generated with hourly granularity only, for the current billing month, and the previous billing month.

Allowed date ranges

Date ranges must use billing-month boundaries (MM/YYYY). Requests may include the current billing month. The data in finalized reports includes usage up to current\_time - 24 hours (rounded up to nearest hour).

Limitiations

Data from the current billing period is not cacheable. Also, recently requested historical date ranges may complete faster due to caching.

Rate limits and concurrency

To ensure system stability, rate limits apply to API usage.

Per-account concurrency

Within a single account:

• Only one billing report per account is processed at a time
• Additional requests are accepted but queued
• Processing occurs serially per account

Global rate limits

Billing report generation depends on shared infrastructure.

Report generation time varies based on:

• Global system load
• Date range size
• Cache availability

Caching behavior

If a previously requested date range is requested again:

• Cached precomputed data is reused
• Global rate limits are skipped
• Generation completes significantly faster

Exception: Data from the current billing period is not cached.

Best practices

Provide an idempotency key (async_operation_id) when retrying requests.

Poll GetBillingReport using exponential backoff.

Download reports immediately after generation (URLs expire).

Reuse previously requested date ranges when possible to benefit from caching.

Avoid frequent generation of large overlapping ranges in the current billing period.

Billing report schema

Billing reports are delivered in CSV format.

Each row represents a charge record.

Column Name	Description	Example
BillingAccountID	Temporal Cloud account ID	a2dd6
BillingAccountName	Temporal Cloud account name	temporal
BillingCurrency	The currency an account is billed in	USD (cents)
BillingPeriodEnd	The exclusive end bound of a billing period	2024-02-01T00:00:00Z
BillingPeriodStart	The inclusive start bound of a billing period	2024-01-01T00:00:00Z
ChargeCategory	The highest level classification of a charge based on how it is billed	Usage
ChargeDescription	A self contained summary of the charge’s purpose	Actions - Tier 1
ChargeFrequency	Indicates how often a charge will occur	Usage-Based
ChargePeriodEnd	Time period end from when this charge took place, correlates to data granularity	2025-10-01T01:00:00.000Z
ChargePeriodStart	Time period start from when this charge took place, correlates to data granularity	2025-10-01T00:00:00.000Z
ContractedCost	Cost calculated by multiplying ContractedUnitPrice and PricingQuantity	100.00
ContractedUnitPrice	The agreed-upon unit price for a single pricing unit of the associated SKU. Inclusive of negotiated discounts	10.00
InvoiceID	The ID of the invoice for this billing period	in_1SPN94JLJETBw2gmYWyQ71xT
InvoiceIssuer	The entity responsible for issuing payable invoices	stripe
PricingQuantity	The volume of a given SKU used or purchased	10.00
PricingUnit	The measurement unit used for PricingQuantity	1 Million Actions
Provider	The provider of purchased resources or services	Temporal Technologies
Publisher	The publisher of purchased resources or services	Temporal Technologies
ResourceID	Namespace name + Temporal Cloud account ID	production.a2dd6
ResourceName	Namespace name + Temporal Cloud account ID	production.a2dd6
ResourceType	The type of resource the charge applies to	Namespace
ServiceCategory	The highest level classification of a service based on the core function of the service	Temporal Cloud
ServiceName	An offering that can be purchased from a provider	Temporal Cloud
ServiceSubcategory	A secondary classification of the service category for a service based on its core function	Actions
SKUID	A unique identifier that represents a specific SKU	essentials-actions
SKUMeter	The functionality being metered or measured by a particular SKU in a charge	Actions
Tags	Provider and customer defined tags associated with resources	{"$tmprl\_project":\["project-id"\],"namespace-tag-key":\["namespace-tag-value"\]}

Generate a report

To generate a report, follow these steps:

1. Create a billing report using CreateBillingReport
2. Receive:
   • billing_report_id (identifies the report artifact)
   • async_operation_id (identifies the background job)
3. Poll GetBillingReport using the billing_report_id
4. When the report state becomes BILLING_REPORT_STATE_GENERATED, retrieve the download URL
5. Download the report before the URL expires

Key identifiers

Identifier	Purpose
billing_report_id	Identifies the billing report artifact and is used to retrieve metadata and download URLs
async_operation_id	Identifies the background operation responsible for generating the report

The async operation follows the standard Cloud Operations async model (see Async Operations.