Skip to main content

Budget Policy

View as Markdown

A serverless usage policy is a set of tags that are applied to the serverless usage of the workloads that use the policy. Each usage record in the billable usage system table carries the policy ID and these tags, so that serverless usage can be attributed to the policy.

BudgetPolicy object​

A serverless usage policy is a set of tags that are applied to the serverless usage of the workloads that use the policy. Each usage record in the billable usage system table carries the policy ID and these tags, so that serverless usage can be attributed to the policy.

policy_idstring^[\\w.-]+$= 36 charactersPublic Preview

The Id of the policy. This field is generated by <Databricks> and globally unique.

policy_namestring[ 1 .. 127 ] charactersPublic Preview

The name of the policy.

  • Must be unique among active policies.
  • Can contain only characters from the ISO 8859-1 (latin1) set.
  • Can't start with reserved keywords such as databricks:default-policy.
custom_tagsarray of objectPublic Preview

A list of tags defined by the customer. At most 20 entries are allowed per policy.

Show child attributesHide child attributes
keystring[ 1 .. 512 ] charactersPublic Preview

The key of the tag.

  • Must be unique among all custom tags of the same policy
  • Cannot be “budget-policy-name”, “budget-policy-id” or "budget-policy-resolution-result" - these tags are preserved.
valuestring<= 256 charactersPublic Preview

The value of the tag.

binding_workspace_idsarray of int64Public Preview

List of workspaces that this budget policy will be exclusively bound to. An empty binding implies that this budget policy is open to any workspace in the account.

Get a budget policy Public Preview​

GET /api/2.1/accounts/{account_id}/budget-policies/{policy_id}

Retrieves a usage policy by its ID.

API scopes: billing

Parameters​

account_idstringRequiredpath

The account Id of the customer

policy_idstring^[\\w.-]+$[ 1 .. 40 ] charactersRequiredpath

The Id of the policy.

Example: 83236d74-1418-3af5-85da-89a4c14985c5

Response​

Returns the BudgetPolicy object.

List policies Public Preview​

GET /api/2.1/accounts/{account_id}/budget-policies

Lists the usage policies that the caller has permission to view. Policies are sorted by name in ascending order unless sort_spec requests a different order.

API scopes: billing

Parameters​

account_idstringRequiredpath

The account Id of the customer

page_sizeint32query

The maximum number of budget policies to return. If unspecified, at most 100 budget policies will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_tokenstringquery

A page token, received from a previous ListBudgetPolicies call. Provide this to retrieve the subsequent page. If unspecified, the first page will be returned.

When paginating, all other parameters provided to ListBudgetPolicies must match the call that provided the page token.

filter_byobjectquery

A filter to apply to the list of policies.

Show child attributesHide child attributes
policy_namestring<= 127 characters

Only policies whose name contains this string are returned. Matching is case-insensitive. If unspecified, all policies are returned.

creator_user_idint64Deprecated

Deprecated: This field is ignored. Creator filtering will be removed in a future version.

creator_user_namestringDeprecated

Deprecated: Do not use this field in new integrations. Creator filtering will be removed in a future version. The policy creator user name to be filtered on. If unspecified, all policies will be returned.

sort_specobjectquery

How to sort the returned policies. If unspecified, policies are sorted by name in ascending order.

Show child attributesHide child attributes
fieldstring

The field to sort by. If unspecified, policies are sorted by name.

Values:

  • POLICY_NAME
descendingboolean

Whether to sort in descending order.

Response​

Returns a list of BudgetPolicy objects.

Create a budget policy Public Preview​

POST /api/2.1/accounts/{account_id}/budget-policies

Creates a new usage policy. The creator is granted the manager role on the new policy.

API scopes: billing

Parameters​

account_idstringRequiredpath

The account Id of the customer

Request body​

request_idstring^[\\w.-]+$= 36 characters

A unique identifier for this request. Restricted to 36 ASCII characters. A random UUID is recommended. This request is only idempotent if a request_id is provided.

policyobject

The policy to create. policy_name must be provided, and custom_tags may be required depending on the cloud provider. Leave policy_id empty because Databricks generates it. All other fields are optional.

Show child attributesHide child attributes
policy_idstring^[\\w.-]+$= 36 characters

The Id of the policy. This field is generated by <Databricks> and globally unique.

policy_namestring[ 1 .. 127 ] characters

The name of the policy.

  • Must be unique among active policies.
  • Can contain only characters from the ISO 8859-1 (latin1) set.
  • Can't start with reserved keywords such as databricks:default-policy.
custom_tagsarray of object

A list of tags defined by the customer. At most 20 entries are allowed per policy.

Show child attributesHide child attributes
keystring[ 1 .. 512 ] charactersRequired

The key of the tag.

  • Must be unique among all custom tags of the same policy
  • Cannot be “budget-policy-name”, “budget-policy-id” or "budget-policy-resolution-result" - these tags are preserved.
valuestring<= 256 characters

The value of the tag.

binding_workspace_idsarray of int64

List of workspaces that this budget policy will be exclusively bound to. An empty binding implies that this budget policy is open to any workspace in the account.

Response​

Returns the BudgetPolicy object.

Update a budget policy Public Preview​

PATCH /api/2.1/accounts/{account_id}/budget-policies/{policy_id}

Updates a usage policy. Changes apply only to serverless usage that starts after the update, not to workloads that are already running.

API scopes: billing

Parameters​

account_idstringRequiredpath

The account Id of the customer

policy_idstring^[\\w.-]+$= 36 charactersRequiredpath

The Id of the policy. This field is generated by <Databricks> and globally unique.

limit_configobjectDeprecatedquery

Deprecated: This field is ignored.

Request body​

The policy to update. creator_user_id cannot be specified in the request. All other fields must be specified even if not changed. The policy_id is used to identify the policy to update.

policy_namestring[ 1 .. 127 ] characters

The name of the policy.

  • Must be unique among active policies.
  • Can contain only characters from the ISO 8859-1 (latin1) set.
  • Can't start with reserved keywords such as databricks:default-policy.
custom_tagsarray of object

A list of tags defined by the customer. At most 20 entries are allowed per policy.

Show child attributesHide child attributes
keystring[ 1 .. 512 ] charactersRequired

The key of the tag.

  • Must be unique among all custom tags of the same policy
  • Cannot be “budget-policy-name”, “budget-policy-id” or "budget-policy-resolution-result" - these tags are preserved.
valuestring<= 256 characters

The value of the tag.

binding_workspace_idsarray of int64

List of workspaces that this budget policy will be exclusively bound to. An empty binding implies that this budget policy is open to any workspace in the account.

Response​

Returns the BudgetPolicy object.

Delete a budget policy Public Preview​

DELETE /api/2.1/accounts/{account_id}/budget-policies/{policy_id}

Deletes a usage policy.

API scopes: billing

Parameters​

account_idstringRequiredpath

The account Id of the customer

policy_idstring^[\\w.-]+$[ 1 .. 40 ] charactersRequiredpath

The Id of the policy.

Example: 83236d74-1418-3af5-85da-89a4c14985c5