For the complete documentation index, see llms.txt. This page is also available as Markdown.

Budgets

List Budgets

get

List the deployment's budgets and the caller's organization's, with pagination.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
skipintegerOptionalDefault: 0
limitinteger · min: 1 · max: 1000OptionalDefault: 100
Responses
200

Successful Response

application/json

Response model for budget information.

max_budget, token_limit and request_limit are the per-user ceilings, each independent and each unlimited when null, and multiple users can share one budget, so the usage rollup is an aggregate over the users assigned to this budget: how many there are and their combined spend / reserved. Assigning users to a budget is done through the users API (dashboard support lands with user management), so a fresh gateway reports zeros here.

budget_duration_secinteger · nullableRequired
budget_idstringRequired
created_atstringRequired
max_budgetnumber · nullableRequired
namestring · nullableRequired
organization_idstring · uuid · nullableRequired
originstring · nullableOptional

'config' while config.yml declares this budget, in which case a start writes the declared values back over any change made through the API when the budget's entry in config.yml changed, and once on the first start after upgrading to a version that tracks this; null otherwise

request_limitinteger · nullableRequired
reset_alignmentstring · nullableRequired
rpm_limitinteger · nullableOptional
token_limitinteger · nullableRequired
total_reservednumberOptionalDefault: 0
total_spendnumberOptionalDefault: 0
tpm_limitinteger · nullableOptional
updated_atstringRequired
user_countintegerOptionalDefault: 0
get/api/v1/budgets
GET /api/v1/budgets HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
  {
    "budget_duration_sec": 1,
    "budget_id": "text",
    "created_at": "text",
    "max_budget": 1,
    "name": "text",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "origin": "text",
    "request_limit": 1,
    "reset_alignment": "text",
    "rpm_limit": 1,
    "token_limit": 1,
    "total_reserved": 0,
    "total_spend": 0,
    "tpm_limit": 1,
    "updated_at": "text",
    "user_count": 0
  }
]

Create Budget

post

Create a new budget.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

Request model for creating a new budget.

budget_duration_secinteger · nullableOptional

Budget duration in seconds (e.g., 86400 for daily, 604800 for weekly)

max_budgetnumber · max: 999999999999 · nullableOptional

Maximum spending limit

namestring · nullableOptional

Admin-facing label for the budget

request_limitinteger · max: 1000000000000000 · nullableOptional

Maximum requests over the period. Independent of max_budget; null is unlimited

reset_alignmentstring · enum · nullableOptional

Reset on a UTC calendar boundary instead of a fixed number of seconds, which is the only way to express a calendar month. Mutually exclusive with budget_duration_sec

Possible values:
rpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Requests per minute for each user on this budget, across replicas; null is unlimited

token_limitinteger · max: 1000000000000000 · nullableOptional

Maximum tokens over the period. Independent of max_budget; null is unlimited

tpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Tokens per minute for each user on this budget, counted on what requests used: a request is admitted while the user's minute is under the limit. Null is unlimited

Responses
200

Successful Response

application/json

Response model for budget information.

max_budget, token_limit and request_limit are the per-user ceilings, each independent and each unlimited when null, and multiple users can share one budget, so the usage rollup is an aggregate over the users assigned to this budget: how many there are and their combined spend / reserved. Assigning users to a budget is done through the users API (dashboard support lands with user management), so a fresh gateway reports zeros here.

budget_duration_secinteger · nullableRequired
budget_idstringRequired
created_atstringRequired
max_budgetnumber · nullableRequired
namestring · nullableRequired
organization_idstring · uuid · nullableRequired
originstring · nullableOptional

'config' while config.yml declares this budget, in which case a start writes the declared values back over any change made through the API when the budget's entry in config.yml changed, and once on the first start after upgrading to a version that tracks this; null otherwise

request_limitinteger · nullableRequired
reset_alignmentstring · nullableRequired
rpm_limitinteger · nullableOptional
token_limitinteger · nullableRequired
total_reservednumberOptionalDefault: 0
total_spendnumberOptionalDefault: 0
tpm_limitinteger · nullableOptional
updated_atstringRequired
user_countintegerOptionalDefault: 0
post/api/v1/budgets
POST /api/v1/budgets HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "budget_duration_sec": 1,
  "max_budget": 1,
  "name": "text",
  "request_limit": 1,
  "reset_alignment": "calendar_day",
  "rpm_limit": 1,
  "token_limit": 1,
  "tpm_limit": 1
}
{
  "budget_duration_sec": 1,
  "budget_id": "text",
  "created_at": "text",
  "max_budget": 1,
  "name": "text",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "origin": "text",
  "request_limit": 1,
  "reset_alignment": "text",
  "rpm_limit": 1,
  "token_limit": 1,
  "total_reserved": 0,
  "total_spend": 0,
  "tpm_limit": 1,
  "updated_at": "text",
  "user_count": 0
}

Get Budget

get

Get details of a specific budget.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
budget_idstringRequired
Responses
200

Successful Response

application/json

Response model for budget information.

max_budget, token_limit and request_limit are the per-user ceilings, each independent and each unlimited when null, and multiple users can share one budget, so the usage rollup is an aggregate over the users assigned to this budget: how many there are and their combined spend / reserved. Assigning users to a budget is done through the users API (dashboard support lands with user management), so a fresh gateway reports zeros here.

budget_duration_secinteger · nullableRequired
budget_idstringRequired
created_atstringRequired
max_budgetnumber · nullableRequired
namestring · nullableRequired
organization_idstring · uuid · nullableRequired
originstring · nullableOptional

'config' while config.yml declares this budget, in which case a start writes the declared values back over any change made through the API when the budget's entry in config.yml changed, and once on the first start after upgrading to a version that tracks this; null otherwise

request_limitinteger · nullableRequired
reset_alignmentstring · nullableRequired
rpm_limitinteger · nullableOptional
token_limitinteger · nullableRequired
total_reservednumberOptionalDefault: 0
total_spendnumberOptionalDefault: 0
tpm_limitinteger · nullableOptional
updated_atstringRequired
user_countintegerOptionalDefault: 0
get/api/v1/budgets/{budget_id}
GET /api/v1/budgets/{budget_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
  "budget_duration_sec": 1,
  "budget_id": "text",
  "created_at": "text",
  "max_budget": 1,
  "name": "text",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "origin": "text",
  "request_limit": 1,
  "reset_alignment": "text",
  "rpm_limit": 1,
  "token_limit": 1,
  "total_reserved": 0,
  "total_spend": 0,
  "tpm_limit": 1,
  "updated_at": "text",
  "user_count": 0
}

Put Budget

put

Create a budget under an id you choose, or replace the one with that id.

Every field takes the value in the body, and a field left out is cleared, so the same request always leaves the same budget. Answers 201 when it created the budget. Users on a budget it replaces stay on it, and its ceilings follow a change of reset period. A budget an organization owns is not replaced.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
budget_idstringRequired

An id you choose: up to 128 letters, digits, '.', '_' and '-', starting with a letter or digit

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
Body

Request model for creating a new budget.

budget_duration_secinteger · nullableOptional

Budget duration in seconds (e.g., 86400 for daily, 604800 for weekly)

max_budgetnumber · max: 999999999999 · nullableOptional

Maximum spending limit

namestring · nullableOptional

Admin-facing label for the budget

request_limitinteger · max: 1000000000000000 · nullableOptional

Maximum requests over the period. Independent of max_budget; null is unlimited

reset_alignmentstring · enum · nullableOptional

Reset on a UTC calendar boundary instead of a fixed number of seconds, which is the only way to express a calendar month. Mutually exclusive with budget_duration_sec

Possible values:
rpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Requests per minute for each user on this budget, across replicas; null is unlimited

token_limitinteger · max: 1000000000000000 · nullableOptional

Maximum tokens over the period. Independent of max_budget; null is unlimited

tpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Tokens per minute for each user on this budget, counted on what requests used: a request is admitted while the user's minute is under the limit. Null is unlimited

Responses
200

Successful Response

application/json

Response model for budget information.

max_budget, token_limit and request_limit are the per-user ceilings, each independent and each unlimited when null, and multiple users can share one budget, so the usage rollup is an aggregate over the users assigned to this budget: how many there are and their combined spend / reserved. Assigning users to a budget is done through the users API (dashboard support lands with user management), so a fresh gateway reports zeros here.

budget_duration_secinteger · nullableRequired
budget_idstringRequired
created_atstringRequired
max_budgetnumber · nullableRequired
namestring · nullableRequired
organization_idstring · uuid · nullableRequired
originstring · nullableOptional

'config' while config.yml declares this budget, in which case a start writes the declared values back over any change made through the API when the budget's entry in config.yml changed, and once on the first start after upgrading to a version that tracks this; null otherwise

request_limitinteger · nullableRequired
reset_alignmentstring · nullableRequired
rpm_limitinteger · nullableOptional
token_limitinteger · nullableRequired
total_reservednumberOptionalDefault: 0
total_spendnumberOptionalDefault: 0
tpm_limitinteger · nullableOptional
updated_atstringRequired
user_countintegerOptionalDefault: 0
put/api/v1/budgets/{budget_id}
PUT /api/v1/budgets/{budget_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "budget_duration_sec": 1,
  "max_budget": 1,
  "name": "text",
  "request_limit": 1,
  "reset_alignment": "calendar_day",
  "rpm_limit": 1,
  "token_limit": 1,
  "tpm_limit": 1
}
{
  "budget_duration_sec": 1,
  "budget_id": "text",
  "created_at": "text",
  "max_budget": 1,
  "name": "text",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "origin": "text",
  "request_limit": 1,
  "reset_alignment": "text",
  "rpm_limit": 1,
  "token_limit": 1,
  "total_reserved": 0,
  "total_spend": 0,
  "tpm_limit": 1,
  "updated_at": "text",
  "user_count": 0
}

Update Budget

patch

Update a budget.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
budget_idstringRequired
Body

Request model for updating a budget.

budget_duration_secinteger · nullableOptional
max_budgetnumber · max: 999999999999 · nullableOptional
namestring · nullableOptional
request_limitinteger · max: 1000000000000000 · nullableOptional

Maximum requests over the period. Independent of max_budget; null is unlimited

reset_alignmentstring · enum · nullableOptionalPossible values:
rpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Requests per minute for each user on this budget, across replicas; null is unlimited

token_limitinteger · max: 1000000000000000 · nullableOptional

Maximum tokens over the period. Independent of max_budget; null is unlimited

tpm_limitinteger · min: 1 · max: 2147483647 · nullableOptional

Tokens per minute for each user on this budget, counted on what requests used: a request is admitted while the user's minute is under the limit. Null is unlimited

Responses
200

Successful Response

application/json

Response model for budget information.

max_budget, token_limit and request_limit are the per-user ceilings, each independent and each unlimited when null, and multiple users can share one budget, so the usage rollup is an aggregate over the users assigned to this budget: how many there are and their combined spend / reserved. Assigning users to a budget is done through the users API (dashboard support lands with user management), so a fresh gateway reports zeros here.

budget_duration_secinteger · nullableRequired
budget_idstringRequired
created_atstringRequired
max_budgetnumber · nullableRequired
namestring · nullableRequired
organization_idstring · uuid · nullableRequired
originstring · nullableOptional

'config' while config.yml declares this budget, in which case a start writes the declared values back over any change made through the API when the budget's entry in config.yml changed, and once on the first start after upgrading to a version that tracks this; null otherwise

request_limitinteger · nullableRequired
reset_alignmentstring · nullableRequired
rpm_limitinteger · nullableOptional
token_limitinteger · nullableRequired
total_reservednumberOptionalDefault: 0
total_spendnumberOptionalDefault: 0
tpm_limitinteger · nullableOptional
updated_atstringRequired
user_countintegerOptionalDefault: 0
patch/api/v1/budgets/{budget_id}
PATCH /api/v1/budgets/{budget_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 149

{
  "budget_duration_sec": 1,
  "max_budget": 1,
  "name": "text",
  "request_limit": 1,
  "reset_alignment": "calendar_day",
  "rpm_limit": 1,
  "token_limit": 1,
  "tpm_limit": 1
}
{
  "budget_duration_sec": 1,
  "budget_id": "text",
  "created_at": "text",
  "max_budget": 1,
  "name": "text",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "origin": "text",
  "request_limit": 1,
  "reset_alignment": "text",
  "rpm_limit": 1,
  "token_limit": 1,
  "total_reserved": 0,
  "total_spend": 0,
  "tpm_limit": 1,
  "updated_at": "text",
  "user_count": 0
}

Delete Budget

delete

Delete a budget the deployment owns.

Refused with 409 for an organization's budget: the operator may edit one (PATCH retimes its ceilings) but deleting it would take a budget the tenant defined out from under them.

Refused with 409, too, while anything still names this budget: a workspace handing it to its members, or a scoped ceiling enforcing it. The refusal says which, and where.

Gateway users assigned to the budget are left uncapped, as the dashboard's confirmation says, its reset history is deleted with it, and it is taken off every service key's end_user_budget_ids. A budget that is a key's end_user_budget_id is refused (409) until that key's default changes.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
budget_idstringRequired
Responses
204

Successful Response

No content

delete/api/v1/budgets/{budget_id}
DELETE /api/v1/budgets/{budget_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*

No content

List Budget Reset Logs

get

List per-user reset events for a budget, newest first.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
budget_idstringRequired
Query parameters
skipintegerOptionalDefault: 0
limitinteger · min: 1 · max: 1000OptionalDefault: 100
Responses
200

Successful Response

application/json

Response model for one budget reset event (per user).

budget_idstringRequired
idintegerRequired
next_reset_atstring · nullableRequired
previous_spendnumberRequired
reset_atstringRequired
user_idstring · nullableRequired
get/api/v1/budgets/{budget_id}/reset-logs
GET /api/v1/budgets/{budget_id}/reset-logs HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
  {
    "budget_id": "text",
    "id": 1,
    "next_reset_at": "text",
    "previous_spend": 1,
    "reset_at": "text",
    "user_id": "text"
  }
]

Last updated

Was this helpful?