---
type: api
title: Create a budget for the organization.
description: Create a new budget for an organization
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/cloud-billing/operation/operation-createbudgetv1
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/cloud-billing/operation/operation-createbudgetv1
products:
  - Elastic Cloud Hosted
---

# Create a budget for the organization.

- Server: `https://cloud.elastic.co` (Public)

## Paths

- `POST` `/api/v1/billing/organization/{organization_id}/budget`

#### Path parameters

- `organization_id` (string) — required
  The organization ID

## Description

Create a new budget for an organization

## Request body

`application/json`

- `active` (boolean · default: true) — optional
  Whether the budget is active
- `alerts` (object[]) — required
  List of budget alerts. The service enforces a server-side limit on the number of alerts per budget.
  - `operator` (enum) — required
    Alert operator
    Values: `gte`
  - `threshold` (integer) — required
    Alert threshold value
  - `threshold_type` (enum · default: percentage) — optional
    Type of alert threshold; only percentage is supported
    Values: `percentage`
- `amount` (integer) — required
  Budget amount in ECU
- `name` (string) — optional
  Optional name for the budget
- `period` (enum) — optional — deprecated
  Deprecated, use window instead. period=monthly is equivalent to a monthly window with reset_on.day=1. If both period and window are sent they must describe the same schedule.
  Values: `monthly`
- `recipient_group` (enum[]) — optional
  Optional list of recipient types who receive budget alerts (organization-admins, billing-admins, resource-viewers, resource-editors, resource-admins). resource-viewers, resource-editors and resource-admins cannot be used with scope_type=organization. organization-admins, billing-admins are included by default if recipient_group is not provided.
  Values: `organization-admins`, `billing-admins`, `resource-viewers`, `resource-editors`, `resource-admins`
- `scope_type` (enum) — required
  The scope type of the budget
  Values: `organization`, `cloud_resource`
- `scope_values` (string[]) — required
  List of scope values
- `window` (object) — optional
  Recurring budget window. Allowed (repeat_unit, repeat_every) pairs and the reset_on fields each one requires: daily (day, 1) with no reset_on; weekly (week, 1) with reset_on.weekday; monthly (month, 1) with reset_on.day; quarterly (month, 3) with reset_on.month, resetting on the 1st; yearly (year, 1) with reset_on.month and reset_on.day. Any other combination, or a missing or extra reset_on field, returns 400. Windows reset at 00:00 UTC. Days 29-31 clamp to the last day of shorter months, recomputed every period (day 31 resets on Jan 31, Feb 28, Mar 31, Apr 30).
  - `repeat_every` (integer · min: 1) — required
    Number of units between resets
  - `repeat_unit` (enum) — required
    Calendar unit between resets
    Values: `day`, `week`, `month`, `year`
  - `reset_on` (object) — optional
    The user's reset selection. Only the fields required by the window frequency are set: weekly uses weekday, monthly uses day, quarterly uses month, yearly uses month and day. Days 29-31 clamp to the last day of shorter months, recomputed every period from this selection (day 31 resets on Jan 31, Feb 28, Mar 31, Apr 30; Feb 29 resets on Feb 28 in non-leap years).
    - `day` (integer) — optional
      Day of the month, 1 to 31.
    - `month` (enum) — optional
      Values: `jan`, `feb`, `mar`, `apr`, `may`, `jun`, `jul`, `aug`, `sep`, `oct`, `nov`, `dec`
    - `weekday` (enum) — optional
      Values: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`

## Responses

#### `200`

Budget created successfully

`application/json`

- `id` (integer)
  The created budget ID
#### `400`

Invalid request

#### `403`

Not allowed to create this budget

#### `500`

Internal Server Error

## Code examples

#### curl

```curl
curl -X POST "https://cloud.elastic.co/api/v1/billing/organization/${ORGANIZATION_ID}/budget" \
  -H "Content-Type: application/json" \
  -d '{
    "alerts": [
      {
        "operator": "gte",
        "threshold": 0
      }
    ],
    "amount": 0,
    "scope_type": "organization",
    "scope_values": [
      "string"
    ]
  }'
```

## Response examples

#### 200

```json
{
  "id": 432433423
}
```