DAdatadog
Usage Metering

Create or update usage quotas

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.
  • 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.
  • 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.
post/api/v2/usage/quotas/{quota_namespace}

Request

Path parameters

quota_namespacestring required
Example:ai_credits

The product-specific namespace whose usage quotas are being managed.

Query parameters

include_descendantsboolean

Whether to write every item in the request to the caller's organization and all of its descendant organizations, instead of only the caller's organization. Only descendants in the same datacenter are supported. For a user-handle scope, the quota is applied only to the caller's organization and to descendant organizations where that user handle exists; the item fails only if the handle exists in none of them.

Request body

Example request

{
  "data": [
    {
      "attributes": {
        "enforced": true,
        "pending_usage_limit": 100000,
        "usage_limit": 600000
      },
      "type": "quotas"
    }
  ]
}

Response

OK. The response includes each item's result; see each item's error attribute for any that failed to write.

Example response

{
  "data": [
    {
      "attributes": {
        "enforced": true,
        "error": "usage_limit is out of range",
        "org_public_id": "abcdef12345",
        "pending_effective_from": "2026-11",
        "pending_usage_limit": 50000,
        "scope": {
          "user_handle": "jane@example.com"
        },
        "usage_limit": 100000
      },
      "id": "MTIzNB9haV9jcmVkaXRzH3VzZXJfaGFuZGxlOl9fQUxMX18",
      "type": "quotas"
    }
  ]
}

Changes

Changes to this operation have not been checked yet.