Repository Public
1# Rate limits and spend with Terraform23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use this guide to manage an existing project rate limit and create a monthly spend alert. Rate limits constrain a project's model usage over time. Spend alerts notify your team when monthly usage reaches a threshold, but they don't stop API requests or enforce a spending cap.67After completing the main workflow, you will have a repeatable configuration that:89- Reads the rate-limit records available to an existing project.10- Manages the request and token limits for one model.11- Sends an email alert when the project's monthly spend reaches a threshold.1213## Before you begin1415Complete the [Terraform provider setup](https://developers.openai.com/api/docs/guides/terraform) and export an Admin API key as `OPENAI_ADMIN_KEY`. You also need:1617- The ID of an existing project.18- At least one email address that should receive spend alerts.1920Use a test project when evaluating the workflow. You will identify the rate-limit record for a text model in the next section. OpenAI creates the rate-limit records available to a project; Terraform updates those records rather than creating new ones.2122## Discover project rate limits2324Read the rate-limit records available to a project:2526```terraform27data "openai_project_rate_limits" "current" {28 project_id = "proj_123"29}3031output "project_rate_limits" {32 value = data.openai_project_rate_limits.current.rate_limits33}34```3536The data source makes a read-only request:3738- `project_id` selects the project to inspect.39- `rate_limits` contains one object for each available model rate limit, including its `id`, `model`, and applicable limit values.40- The output makes the records visible after `terraform plan` or `terraform apply`.4142Use the record whose `model` matches the model you want to control. Copy its `id`; the next resource uses that value as `rate_limit_id`. Keep the ID as an explicit input to prevent a provider or API change from selecting a different record.4344## Manage an existing rate limit4546Manage the request and token limits for the selected text-model record:4748```terraform49resource "openai_project_rate_limit" "application" {50 project_id = "proj_123"51 rate_limit_id = "rl-gpt-3.5-turbo"52 max_requests_per_1_minute = 50053 max_tokens_per_1_minute = 20000054}55```5657Each argument has a specific role:5859- `project_id` identifies the project whose rate limit will change.60- `rate_limit_id` identifies an existing model rate-limit record. It isn't a model ID.61- `max_requests_per_1_minute` limits the number of requests the project can send for that model each minute.62- `max_tokens_per_1_minute` limits the number of tokens the project can process for that model each minute.6364Set only the fields that apply to the selected record. Other record types can expose limits for images per minute, audio megabytes per minute, requests per day, or Batch input tokens per day. A configured value can't exceed the limit available to the organization and project.6566Although the first Terraform plan shows this resource as an addition, the provider updates the existing rate-limit record and then stores it in Terraform state. Changing a configured limit sends another update.6768Removing `openai_project_rate_limit` from the configuration removes the record69 from Terraform state, but it doesn't reset or delete the remote rate limit.70 Set the desired remote values before removing the resource if another workflow71 will manage the record.7273## Configure a project spend alert7475Create a monthly project spend alert:7677```terraform78resource "openai_project_spend_alert" "monthly" {79 project_id = "proj_123"80 threshold_amount = 2000081 currency = "USD"82 interval = "month"83 notification_channel_type = "email"84 notification_channel_recipients = ["platform-alerts@example.com"]85 notification_channel_subject_prefix = "OpenAI project spend"86}87```8889The alert definition combines the spend condition and its notification channel:9091- `project_id` limits the alert to spend from one project.92- `threshold_amount` is the monthly threshold in cents. `20000` represents USD 200.93- `currency` must be `USD`.94- `interval` must be `month`.95- `notification_channel_type` must be `email`.96- `notification_channel_recipients` must contain at least one recipient.97- `notification_channel_subject_prefix` is optional text added to alert email subjects.9899Terraform creates the alert and stores its generated `alert_id`. Changing the threshold or notification fields updates the alert. Removing the resource deletes the remote alert.100101Spend alerts are notifications, not hard limits. Define an incident or administrative response for each threshold, and use rate limits to constrain request volume independently.102103## Configure an organization spend alert104105Use an organization alert when the threshold should cover spend across the organization:106107```terraform108resource "openai_organization_spend_alert" "monthly" {109 threshold_amount = 100000110 currency = "USD"111 interval = "month"112 notification_channel_type = "email"113 notification_channel_recipients = ["platform-alerts@example.com"]114}115```116117This resource uses the same threshold units, interval, currency, and notification fields as a project alert. It doesn't take a `project_id` because it measures organization-wide spend. The example sends an email after monthly organization spend reaches USD 1,000.118119You can manage project and organization alerts together. Use distinct thresholds and recipients when different teams own the response at each scope.120121## Run the complete example122123The focused examples use concrete values to explain each resource. The complete configuration replaces environment-specific values with variables and combines project rate-limit discovery, one managed rate limit, and one project spend alert.124125Save the following configuration as `main.tf`:126127```terraform128terraform {129 required_version = ">= 1.0"130131 required_providers {132 openai = {133 source = "openai/openai"134 version = ">= 1.0.0"135 }136 }137}138139provider "openai" {}140141variable "project_id" {142 type = string143}144145variable "rate_limit_id" {146 type = string147 description = "Existing rate-limit record for the text model to manage."148}149150variable "max_requests_per_minute" {151 type = number152}153154variable "max_tokens_per_minute" {155 type = number156}157158variable "project_spend_threshold_cents" {159 type = number160 description = "Monthly project spend threshold in cents."161162 validation {163 condition = var.project_spend_threshold_cents > 0164 error_message = "The project spend threshold must be greater than zero."165 }166}167168variable "alert_recipients" {169 type = list(string)170171 validation {172 condition = length(var.alert_recipients) > 0173 error_message = "Provide at least one spend-alert recipient."174 }175}176177data "openai_project_rate_limits" "current" {178 project_id = var.project_id179}180181resource "openai_project_rate_limit" "application" {182 project_id = var.project_id183 rate_limit_id = var.rate_limit_id184 max_requests_per_1_minute = var.max_requests_per_minute185 max_tokens_per_1_minute = var.max_tokens_per_minute186}187188resource "openai_project_spend_alert" "monthly" {189 project_id = var.project_id190 threshold_amount = var.project_spend_threshold_cents191 currency = "USD"192 interval = "month"193 notification_channel_type = "email"194 notification_channel_recipients = var.alert_recipients195 notification_channel_subject_prefix = "OpenAI project spend"196}197198output "available_rate_limits" {199 value = data.openai_project_rate_limits.current.rate_limits200}201202output "managed_rate_limit_model" {203 value = openai_project_rate_limit.application.model204}205206output "project_spend_alert_id" {207 value = openai_project_spend_alert.monthly.alert_id208}209```210211Create `terraform.tfvars` with an existing project ID, the rate-limit record ID you discovered for a text model, approved limits, a threshold in cents, and the alert recipients:212213```terraform214project_id = "proj_123"215rate_limit_id = "rl-gpt-3.5-turbo"216217max_requests_per_minute = 500218max_tokens_per_minute = 200000219220project_spend_threshold_cents = 20000221alert_recipients = ["platform-alerts@example.com"]222```223224Choose request and token values that don't exceed the limits currently available to the project. The `available_rate_limits` output in the plan shows the current records and values for comparison.225226Initialize Terraform, then review and apply a saved plan:227228```bash229terraform init230terraform fmt231terraform validate232terraform plan -out=tfplan233terraform show tfplan234terraform apply tfplan235```236237The first plan should contain two resources to add. Terraform describes the rate-limit resource as an addition to state, but applying it updates the existing OpenAI rate-limit record. The other addition creates the project spend alert. After the apply, `terraform output` prints the available rate limits, the model associated with the managed record, and the alert ID.238239Run `terraform plan` again to confirm that the configuration produces no further changes. If it shows drift, determine whether another administrator or automation changed the rate limit or spend alert before applying another update.