Create budget

Creates an organization-owned budget across all seven scope types. Spend is counted from the moment the budget is created, so spend earlier in the current window is not included. Requires gatewayBudgets:create at the organization; a project key or an organization key may call it.

POST /api/gateway/v1/budgets

Create budget

Python

import requests

url = "https://app.langwatch.ai/api/gateway/v1/budgets"

payload = {
    "scope": {
        "kind": "organization",
        "organization_id": "<string>"
    },
    "name": "<string>",
    "limit_usd": 1
}
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

201

{
  "budget": {
    "id": "<string>",
    "organization_id": "<string>",
    "scope_type": "organization",
    "scope_id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "window": "minute",
    "on_breach": "block",
    "limit_usd": "<string>",
    "limit_nano_usd": 0,
    "spent_usd": "<string>",
    "spent_nano_usd": 0,
    "timezone": "<string>",
    "provider_key": "<string>",
    "external_id": "<string>",
    "metadata": {},
    "current_period_started_at": "<string>",
    "resets_at": "<string>",
    "cycle_anchor_at": "<string>",
    "last_reset_at": "<string>",
    "archived_at": "<string>",
    "created_at": "<string>",
    "member_count": 0,
    "end_users_seen": 0,
    "end_users_over": 0,
    "scope_reach": "reachable"
  }
}

Authorizations

X-Auth-Token · string · header · required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Headers

Idempotency-Key · string

A caller-chosen key, 8 to 255 characters, that makes this create safe to retry. The first request to use a key runs normally and its response is stored for 24 hours. A later request with the same key and the same body is not executed again: it returns the stored response, marked with X-Idempotent-Replay: true. The same key with a different body is refused 409 idempotency_error, as is a retry sent while the original is still running. Only successful responses are stored, so a create that failed can simply be retried with the same key.

Required string length: 8 - 255

Body

application/json

scope · object · required

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Show child attributes

name · string · required

Required string length: 1 - 128

window · enum<string> · required

Available options: minute, hour, day, week, month, total, manual

limit_usd · number string · required

Required range: x > 0

description · string

on_breach · enum<string>

Available options: block, warn

timezone · string | null

provider_key · string | null

external_id · string | null

Required string length: 1 - 128

metadata · object

Show child attributes

cycle_anchor_at · string<date-time>

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

allow_unreachable · boolean

Response

201

application/json

Success

budget · object · required

Show child attributes