--- title: "Create or update usage quotas" method: POST path: "/api/v2/usage/quotas/{quota_namespace}" tags: ["Usage Metering"] --- # Create or update usage quotas `POST /api/v2/usage/quotas/{quota_namespace}` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/usage/quotas/{quota_namespace}` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `billing_edit` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates or updates one or more usage quotas by scope. If a quota already exists for a supplied scope, it is updated. Otherwise, a quota is created only when `usage_limit` and `enforced` are provided. For the organization-wide quota, `pending_usage_limit` schedules a limit for the next usage period and can accompany an immediate limit or update an existing quota by itself. Scheduled changes follow `include_descendants` like the other fields. Requires the `billing_edit` permission. ### Quota namespaces and scope keys The `quota_namespace` path parameter selects the product whose usage quotas are managed. Each namespace supports its own scope keys, described below. Omit `scope` for the organization-wide quota. #### `ai_credits` scope keys Each item's `scope` contains exactly one of the following keys. **`user_handle`** - **Value:** The handle of a user, for example `jane@example.com`, or `"*"` for the default quota applied to users without a specific quota. User handles are returned in the `data[].attributes.handle` field by the [Users API](https://docs.datadoghq.com/api/latest/users/#list-all-users). - **Validation:** A specific handle must identify an existing user in the caller's organization when `include_descendants` is false. When `include_descendants` is true, the handle must exist in the caller's organization or in at least one targeted descendant organization. The quota is then applied only to the organizations where the handle exists, and the item fails only if the handle exists in none of them. **`role_uuid`** - **Value:** The UUID of a role, for example `12345678-1234-1234-1234-123456789012`. `"*"` is not accepted because there is no default role quota. Role UUIDs are returned in the `data[].id` field by the [Roles API](https://docs.datadoghq.com/api/latest/roles/#list-roles). - **Validation:** The role must exist in the caller's organization. Role UUIDs are unique, so `include_descendants` has no effect on a `role_uuid` scope: the role is validated against the caller's organization only. ## Path parameters - `quota_namespace` string, required ## Query parameters - `include_descendants` boolean ## Request body - UsageQuotasCreateRequest: A JSON:API bulk request containing an array of usage quota resources rather than a single resource. - `data` UsageQuotaCreateData[], required: A bulk list of usage quota resources to create or update by scope. - `attributes` UsageQuotaCreateAttributes, required: Attributes for creating or updating a usage quota by scope. Each item must provide `usage_limit`, `pending_usage_limit`, or both. Providing only `pending_usage_limit` updates an existing organization-wide quota, never creates one, requires `enforced` to be omitted, and fails if the quota does not exist. - `enforced` boolean: Whether to actively block usage above `usage_limit` instead of only tracking or alerting on it. Required when `usage_limit` is provided and must be omitted when only `pending_usage_limit` is provided. - `pending_usage_limit` integer: The non-negative, whole-number limit to schedule for the organization-wide quota in the usage units defined by the quota namespace. It is not checked against current usage. Each write schedules the value for 00:00 UTC on the first day of the next calendar month and replaces any previously scheduled change; the server computes `pending_effective_from`. Omit this field to leave any scheduled change unchanged, including when raising `usage_limit`. Cancel a scheduled change only by deleting the quota's `/pending` sub-resource. - `scope` UsageQuotaRequestScope: A namespace-specific key and value identifying what the quota applies to within an organization. See the endpoint description for the supported scope keys, values, and validation rules. - `usage_limit` integer: The non-negative, whole-number quota limit to set in the usage units defined by the quota namespace. For an organization-wide quota (scope omitted), the limit must be greater than usage already recorded in the current period. When this field is provided, `enforced` is required. - `type` 'quotas', required: The JSON:API resource type for a usage quota. ## Response `200` OK. The response includes each item's result; see each item's `error` attribute for any that failed to write. - UsageQuotasBulkResponse: Response containing the result of a bulk usage quota create-or-update request. Returned with a `200` status regardless of whether individual items succeeded or failed; check each item's `error` attribute to determine its outcome. - `data` UsageQuotaBulkResultData[], required: The results of writing each usage quota in a bulk create-or-update request, in the same order as the request. - `attributes` UsageQuotaBulkResultAttributes, required: Attributes of a usage quota bulk write result. On success, quota fields are present as applicable, and pending fields are present only when a change is scheduled. On failure, only `error` is present and the other fields are omitted. - `enforced` boolean: Whether usage above the limit is actively blocked instead of only tracked or alerted on. Omitted if this item failed to write. - `error` string: An error message describing why this item failed to write. Omitted if this item was written successfully. - `org_public_id` string: The public ID of the organization that owns the quota. Omitted if this item failed to write. - `pending_effective_from` string: The future UTC month when the scheduled limit takes effect, formatted as `YYYY-MM`, starting at 00:00 UTC on its first day. Present only together with `pending_usage_limit` and omitted when no change is scheduled or this item failed to write. - `pending_usage_limit` number, double: The usage limit scheduled for the organization-wide quota in the usage units defined by the quota namespace. A value of `0` is valid. At the start of the effective month, this value becomes `usage_limit` and both pending fields are omitted. Omitted when no change is scheduled or this item failed to write. - `scope` UsageQuotaResponseScope: A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A `user_handle` value of `"*"` identifies the default quota applied to users without a specific quota. This field is omitted for an organization-wide quota. - `usage_limit` number, double: The quota limit in the usage units defined by the quota namespace. May be fractional for quotas configured before public writes required whole units. Omitted if this item failed to write. - `id` string, required: An opaque usage quota identifier. Clients must pass this value back verbatim in update and delete requests and must not infer any structure from it. - `type` 'quotas', required: The JSON:API resource type for a usage quota. ## Other responses - `400`: Bad Request. Returned if the request is malformed, including when an item sets `pending_usage_limit` on a scoped quota, provides `enforced` without `usage_limit`, or provides neither limit. A pending-only item for a quota that does not exist is reported in that item's `error`; when only the caller's organization is targeted, this failure returns `400`. - `403`: Forbidden - `429`: Too many requests - `500`: Internal Server Error. Every item in the batch failed to write. --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)