Create a budget
curl --request POST \
--url https://{host}/api/llm-gateway/admin/budgets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"period": "<string>",
"scope_type": "<string>",
"token_limit": 123,
"action_on_exhaust": "<string>",
"alert_thresholds": [
123
],
"change_note": "<string>",
"cost_limit": 123,
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"traffic_type": "<string>"
}
'import requests
url = "https://{host}/api/llm-gateway/admin/budgets"
payload = {
"name": "<string>",
"period": "<string>",
"scope_type": "<string>",
"token_limit": 123,
"action_on_exhaust": "<string>",
"alert_thresholds": [123],
"change_note": "<string>",
"cost_limit": 123,
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"traffic_type": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
period: '<string>',
scope_type: '<string>',
token_limit: 123,
action_on_exhaust: '<string>',
alert_thresholds: [123],
change_note: '<string>',
cost_limit: 123,
currency: '<string>',
member_of_group: '<string>',
scope_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
scope_value: '<string>',
target_mcp_server_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
target_model_alias: '<string>',
target_provider_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
target_upstream_model: '<string>',
traffic_type: '<string>'
})
};
fetch('https://{host}/api/llm-gateway/admin/budgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/llm-gateway/admin/budgets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'period' => '<string>',
'scope_type' => '<string>',
'token_limit' => 123,
'action_on_exhaust' => '<string>',
'alert_thresholds' => [
123
],
'change_note' => '<string>',
'cost_limit' => 123,
'currency' => '<string>',
'member_of_group' => '<string>',
'scope_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'scope_value' => '<string>',
'target_mcp_server_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'target_model_alias' => '<string>',
'target_provider_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'target_upstream_model' => '<string>',
'traffic_type' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/api/llm-gateway/admin/budgets"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/api/llm-gateway/admin/budgets")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/llm-gateway/admin/budgets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"action_on_exhaust": "block",
"alert_thresholds": [
123
],
"enabled": true,
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"period": "daily",
"scope_type": "org",
"token_limit": 123,
"traffic_type": "all",
"cost_limit": 123,
"created_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"created_by_email": "<string>",
"created_by_name": "<string>",
"created_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_change_note": "<string>",
"last_modified_at": "2023-11-07T05:31:56Z",
"last_modified_by_email": "<string>",
"last_modified_by_name": "<string>",
"last_modified_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}LLM Gateway: Budgets
Create a budget
Creates a token and/or cost ceiling for a scope over a daily, weekly, or monthly period. Set token_limit, cost_limit, or both; use token_limit: 0 with a cost_limit for a cost-only budget.
Use the target_* fields to count only the traffic that goes to a specific provider, upstream model, model alias, or MCP server.
POST
/
admin
/
budgets
Create a budget
curl --request POST \
--url https://{host}/api/llm-gateway/admin/budgets \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"period": "<string>",
"scope_type": "<string>",
"token_limit": 123,
"action_on_exhaust": "<string>",
"alert_thresholds": [
123
],
"change_note": "<string>",
"cost_limit": 123,
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"traffic_type": "<string>"
}
'import requests
url = "https://{host}/api/llm-gateway/admin/budgets"
payload = {
"name": "<string>",
"period": "<string>",
"scope_type": "<string>",
"token_limit": 123,
"action_on_exhaust": "<string>",
"alert_thresholds": [123],
"change_note": "<string>",
"cost_limit": 123,
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"traffic_type": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
period: '<string>',
scope_type: '<string>',
token_limit: 123,
action_on_exhaust: '<string>',
alert_thresholds: [123],
change_note: '<string>',
cost_limit: 123,
currency: '<string>',
member_of_group: '<string>',
scope_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
scope_value: '<string>',
target_mcp_server_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
target_model_alias: '<string>',
target_provider_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
target_upstream_model: '<string>',
traffic_type: '<string>'
})
};
fetch('https://{host}/api/llm-gateway/admin/budgets', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/llm-gateway/admin/budgets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'period' => '<string>',
'scope_type' => '<string>',
'token_limit' => 123,
'action_on_exhaust' => '<string>',
'alert_thresholds' => [
123
],
'change_note' => '<string>',
'cost_limit' => 123,
'currency' => '<string>',
'member_of_group' => '<string>',
'scope_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'scope_value' => '<string>',
'target_mcp_server_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'target_model_alias' => '<string>',
'target_provider_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'target_upstream_model' => '<string>',
'traffic_type' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/api/llm-gateway/admin/budgets"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{host}/api/llm-gateway/admin/budgets")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/llm-gateway/admin/budgets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"period\": \"<string>\",\n \"scope_type\": \"<string>\",\n \"token_limit\": 123,\n \"action_on_exhaust\": \"<string>\",\n \"alert_thresholds\": [\n 123\n ],\n \"change_note\": \"<string>\",\n \"cost_limit\": 123,\n \"currency\": \"<string>\",\n \"member_of_group\": \"<string>\",\n \"scope_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"scope_value\": \"<string>\",\n \"target_mcp_server_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_model_alias\": \"<string>\",\n \"target_provider_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"target_upstream_model\": \"<string>\",\n \"traffic_type\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"action_on_exhaust": "block",
"alert_thresholds": [
123
],
"enabled": true,
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"period": "daily",
"scope_type": "org",
"token_limit": 123,
"traffic_type": "all",
"cost_limit": 123,
"created_at": "2023-11-07T05:31:56Z",
"currency": "<string>",
"member_of_group": "<string>",
"scope_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scope_value": "<string>",
"target_mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_model_alias": "<string>",
"target_provider_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_upstream_model": "<string>",
"created_by_email": "<string>",
"created_by_name": "<string>",
"created_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_change_note": "<string>",
"last_modified_at": "2023-11-07T05:31:56Z",
"last_modified_by_email": "<string>",
"last_modified_by_name": "<string>",
"last_modified_by_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}{
"error": {
"message": "retry_on_429_count must be between 0 and 10",
"type": "invalid_request_error"
}
}Authorizations
An access token from Barndoor's identity provider, sent as Authorization: Bearer <token>. Use a service-account token from the OAuth 2.0 client-credentials grant for scripts and CI, or a signed-in user's token. The caller needs the admin role in the organization. Gateway API keys (bd-...) are not accepted here.
Body
application/json
daily, weekly, or monthly. Periods reset at UTC boundaries.
Who the policy applies to: org (everyone), or one of team, user, project, api_key, mcp_server, agent, role, group. Select the entity with scope_id (UUID-keyed types) or scope_value (name-keyed types such as role and group).
Tokens allowed per period. Use 0 together with cost_limit for a cost-only budget.
What happens when the budget is exhausted: block, throttle, or warn. Defaults to block.
Usage percentages (0–100) at which alerts are raised. Defaults to [80, 90].
Optional note explaining why this was created. Shown with the record and in the audit log.
Spending cap per period in currency, enforced on estimated cost. Optional.
ISO 4217 currency code for cost_limit. Defaults to USD.
Give each member of this IdP group their own allowance from this one policy. Only valid with scope_type: user and no scope_id or scope_value. A group-scoped policy, by contrast, shares one allowance across all members.
UUID of the scoped entity, for UUID-keyed scope types such as user, team, or api_key.
Name of the scoped entity, for name-keyed scope types, such as a role or IdP group name.
Only apply to requests to this MCP server. Requires traffic_type mcp or all, and cannot be combined with the LLM target fields.
Only apply to requests whose model is this alias. Cannot be combined with the other target fields.
Only apply to requests routed to this provider. Can be combined with target_upstream_model; cannot be combined with target_model_alias or target_mcp_server_id.
Only apply to requests routed to this upstream model. Requires target_provider_id.
Traffic the policy applies to: all, llm (model traffic), or mcp (MCP tool traffic). Defaults to all.
Response
Created
A budget.
Available options:
block, throttle, warn How often a budget resets. All boundaries are UTC: daily at 00:00, weekly on Monday at 00:00, monthly on the 1st at 00:00.
Available options:
daily, weekly, monthly Who a policy applies to. llm_provider and model remain for compatibility only; to limit a budget or rate limit to a provider or model, use its target_* fields.
Available options:
org, team, user, project, api_key, mcp_server, llm_provider, model, agent, role, group Tokens allowed per period. 0 on a cost-only budget.
Available options:
all, llm, mcp Spending cap per period in currency, enforced on estimated cost in addition to tokens.
When the budget was created.
ISO 4217 currency code (e.g. "USD"). Defaults to "USD".
Give each member of this IdP group their own allowance from this one policy. Only valid with scope_type: user and no scope_id or scope_value. A group-scoped policy, by contrast, shares one allowance across all members.
Only apply to requests to this MCP server. Requires traffic_type mcp or all, and cannot be combined with the LLM target fields.
Only apply to requests whose model is this alias. Cannot be combined with the other target fields.
Only apply to requests routed to this provider. Can be combined with target_upstream_model; cannot be combined with target_model_alias or target_mcp_server_id.
Only apply to requests routed to this upstream model. Requires target_provider_id.
Note explaining the last change.
When the last attributed change was made.