Skip to main content

Cloud Ops API

Support, stability, and dependency info

Temporal Cloud Operations API is in Public Preview for Temporal Cloud.

The Temporal Cloud Operations API (Cloud Ops API) is an open source, public gRPC API for managing the automation of Users, Namespaces, and Temporal Cloud Accounts.

In addition to being available on GitHub, the proto files are also hosted on Buf, which provides a clean web interface for browsing and visualizing the APIs, and offers more streamlined dependency management. You can use the provided proto files to generate client libraries in your desired programming language.

SDKs and samples​

We provide a Go SDK that compiles the proto files into Go bindings, offering a more idiomatic interface for Go developers. This SDK eliminates the need to manually compile protobuf files when working with Go.

We also provide Go samples to help you get started with the Cloud Ops API using the Go SDK.

Develop applications with the Cloud Ops API​

This section walks you through the steps to develop applications with the Cloud Ops API, either through the Go SDK or by compiling the protobuf files for other programming languages.

Prerequisites​

For Go developers:

  • Use the Go SDK for the simplest setup experience

For other programming languages:

  • Basic familiarity with gRPC and Protocol Buffers (protobuf)
  • Protocol Buffers
  • gRPC in your preferred programming language

If you're developing in Go, we recommend using the Go SDK which provides pre-compiled Go bindings and a more idiomatic interface. The Go SDK handles all the protobuf compilation and provides ready-to-use Go types and client interfaces.

To start using the Go SDK with the Cloud Ops API, follow these steps:

  1. Install the Go SDK:

    go get github.com/temporalio/cloud-sdk-go

  2. Import and use the SDK:

    import (
        "github.com/temporalio/cloud-sdk-go/client"
    )

  3. The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the Go samples for detailed usage examples.

The Go SDK eliminates the need to work directly with generated protobuf files and provides a more idiomatic Go experience.

Compile the API and use the generated code (For other languages)​

For programming languages other than Go, download the gRPC protobufs from the Cloud Ops API repository and compile them manually.

Use gRPC to compile and generate code in your preferred programming language. The steps below use Python as an example and require Python's gRPC tools to be installed, but the approach can be adapted for other supported programming languages.

  1. Clone the Temporal Cloud API repository:

    git clone https://github.com/temporalio/cloud-api.git
    cd cloud-api

  2. Copy Protobuf files:

    • Navigate to the temporal directory.
    • Copy the protobuf files to your project directory.

  3. Compile the Protobuf files:

    python -m grpc_tools.protoc -I./ --python_out=./ --grpc_python_out=./ *.proto
    • -I specifies the directory of the .proto files.
    • --python_out= sets the output directory for generated Python classes.
    • --grpc_python_out= sets the output directory for generated gRPC service classes.
    • *.proto processes all .proto files.

    After compiling the Protobuf files, you will have generated code files in your project directory. These files enable interaction with the Temporal Cloud API in your chosen programming language.

  4. Import the Generated Files:

    • Locate the Python files (.py) generated in your project directory.
    • Import these files into your Python application where you intend to interact with the Temporal Cloud API.

  5. Use the API:

    • Use the classes and methods defined in the imported files to communicate with the Temporal Cloud services.
    • Ensure to handle any required authentication or configuration as needed for Temporal Cloud.

This approach can be adapted for other programming languages by following their respective import and usage conventions for the generated code files.

Usage guidelines​

When interacting with the Temporal Cloud Ops API, follow these guidelines:

  • API version header:
    • Always include the temporal-cloud-api-version header in your requests, specifying the API version identifier.
    • The current API version can be found here.
  • Connection URL:
    • Connect to the Temporal Cloud using the gRPC URL: saas-api.tmprl.cloud:443.
  • Engagement steps:
    • Generate API key:
    • Set up client:
      • Establish a secure connection to the Temporal Cloud. Refer to the example Client setup in Go for guidance.
    • Execute operations:
      • For operation specifics, refer to the cloudservice/v1/request_response.proto for gRPC messages and cloudservice/v1/service.proto for gRPC services.

These steps provide a structured approach to using the Temporal Cloud Ops API effectively, ensuring proper authentication and connection setup.

Rate limits​

The Temporal Cloud Operations API implements rate limiting to ensure system stability and fair usage across all users. Rate limits are applied based on identity type, with different limits for users and service accounts.

Account-level rate limit​

Total rate limit: 40 requests per second (RPS)

This limit applies to all requests made to the Temporal Cloud control plane by any client (tcld, UI, Cloud Ops API) or identity type (user, service account) within your account. The total account throughput cannot exceed 160 RPS regardless of the number of users or service accounts making requests.

Per-identity rate limits​

User rate limit: 10 RPS per user

This limit applies to all requests made by each user through any client (tcld, UI, Cloud Ops API), regardless of the authentication method used (SSO or API keys).

Service account rate limit: 20 RPS per service account

This limit applies to all requests made by each service account through any client (tcld, Cloud Ops API).

Important considerations​

  • Rate limits are enforced across all Temporal Cloud control plane operations
  • Multiple clients used by the same identity (user or service account) share the same rate limit
  • Authentication method (SSO, API keys) does not affect rate limiting
  • These limits help ensure system stability and prevent any single account or identity from overwhelming the service

Request limit increases​

If your use case requires higher rate limits, you can request an increase by submitting a support ticket. When requesting a limit increase, please provide:

  • Your current usage patterns and requirements
  • The specific limits you need increased
  • A description of your use case and why higher limits are necessary

Provide feedback​

Your input is valuable. While the Temporal Cloud Ops API is in a Public Preview release status, we welcome your feedback.

You can provide feedback through the following channels:

  • Submit request or feedback through a ZenDesk ticket
  • Open an issue in the GitHub Repo