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)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scope: {kind: 'organization', organization_id: '<string>'},
name: '<string>',
limit_usd: 1
})
};
fetch('https://app.langwatch.ai/api/gateway/v1/budgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://app.langwatch.ai/api/gateway/v1/budgets \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"scope": {
"kind": "organization",
"organization_id": "<string>"
},
"name": "<string>",
"limit_usd": 1
}
'{
"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": 123,
"spent_usd": "<string>",
"spent_nano_usd": 123,
"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": 123,
"end_users_seen": 123,
"end_users_over": 123,
"scope_reach": "reachable"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}Create budget
Creates an organization-owned budget. The scope discriminates which resource the budget covers, across all seven scope types (organization / team / project / virtual_key / principal / group / attributed_user). group budgets are per-member allowances and attributed_user budgets are per-end-user templates; both require a deployment with the ClickHouse spend ledger (group_budget_requires_clickhouse otherwise). provider_key optionally pins the budget to one model provider. cycle_anchor_at optionally phases the window off a chosen instant instead of the calendar, for budgets that have to line up with a billing date. A team, project or group budget that none of the organization’s active keys can produce traffic for is refused with gateway_budget_scope_unreachable, since it would never spend and never block; send allow_unreachable to keep it anyway, and note that an organization with no active keys is never refused. Send Idempotency-Key to make a retry safe.
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)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scope: {kind: 'organization', organization_id: '<string>'},
name: '<string>',
limit_usd: 1
})
};
fetch('https://app.langwatch.ai/api/gateway/v1/budgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://app.langwatch.ai/api/gateway/v1/budgets \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"scope": {
"kind": "organization",
"organization_id": "<string>"
},
"name": "<string>",
"limit_usd": 1
}
'{
"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": 123,
"spent_usd": "<string>",
"spent_nano_usd": 123,
"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": 123,
"end_users_seen": 123,
"end_users_over": 123,
"scope_reach": "reachable"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"meta": {},
"trace_id": "<string>",
"span_id": "<string>"
}
}Authorizations
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
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.
8 - 255Body
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
Show child attributes
Show child attributes
1 - 128minute, hour, day, week, month, total, manual x > 0block, warn 1 - 128Show child attributes
Show child attributes
Phases the budget's cycle off this instant instead of the calendar, so a month budget anchored 2026-01-17T09:00:00Z starts a fresh period every 17th at 09:00 UTC. Omit for calendar alignment, which is the default and unchanged behaviour. A month cycle anchored past the 28th clamps into shorter months and springs back: anchored on the 31st gives Feb 28, then Mar 31. Immutable after create, since moving it would redraw periods the budget has already reported and enforced on. Rejected with gateway_budget_cycle_anchor_invalid on total and manual, which do not cycle.
Keeps a team, project or group budget that no active key can produce traffic for, which is otherwise refused with gateway_budget_scope_unreachable. Send it to provision ahead of the keys that will use the budget. An organization with no active keys is never refused, so this is not needed during first setup.
Response
Budget created
Show child attributes
Show child attributes
Was this page helpful?