Update Budget

Endpoint

PUT /apiops/projects/{projectName}/ai-budgets/

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name

Query Parameters

None

Request Body

Full JSON Body Example

{
  "targetType": "CREDENTIAL_ORGANIZATION",
  "targetId": "665f1a2b3c4d5e6f7a8b9c1a",
  "targetProjectId": "665f1a2b3c4d5e6f7a8b9c0d",
  "budgetSource": "INHERIT",
  "budget": {
    "enabled": true,
    "tokensPerHour": null,
    "tokensPerMinute": null,
    "tokensPerDay": 100000,
    "tokensPerMonth": 2000000,
    "monthlyBudgetUsd": 250.00,
    "usdPerHour": null,
    "usdPerDay": null,
    "softCapPercents": [80, 95],
    "hardCapPercent": 100,
    "overflowAction": "CHEAPER_MODEL",
    "cheaperModelId": "claude-haiku-4-5",
    "modelBudgets": [
      {
        "modelId": "gpt-4o",
        "tokensPerMonth": 500000,
        "monthlyBudgetUsd": 100.00,
        "overflowAction": "BLOCK"
      }
    ],
    "providerBudgets": []
  }
}

Request Body Fields

Field	Type	Required	Default	Description
targetType	string	Yes	-	Owner entity type: `CREDENTIAL_ORGANIZATION`, `API_PROXY`, `PROJECT` or `CREDENTIAL_ALLOWED_API_PROXY`
targetId	string	Yes	-	Entity ID of the owner (org / proxy / project / credential binding). Take it from a scope-rules or hierarchy read
targetProjectId	string	No	path project	Ignored / overwritten. The server forces it to the path project as a cross-tenant guard
budgetSource	string	No	-	Budget source for `CREDENTIAL_ALLOWED_API_PROXY` targets: `CREDENTIAL`, `ORGANIZATION` or `INHERIT`. Ignored for other target types. `null` leaves it unchanged (new bindings default to `INHERIT`)
budget	object	Yes	-	The AI token budget value to apply (see below)

Budget Object Fields

Field	Type	Required	Default	Description
enabled	boolean	No	false	Whether the budget is enabled
tokensPerHour	integer	No	-	Hourly token cap. `null` = no limit; if set, must be `>= 1`
tokensPerMinute	integer	No	-	Per-minute token cap. `null` = no limit; if set, must be `>= 1`
tokensPerDay	integer	No	-	Daily token cap. `null` = no limit; if set, must be `>= 1`
tokensPerMonth	integer	No	-	Monthly token cap. `null` = no limit; if set, must be `>= 1`
monthlyBudgetUsd	number	No	-	Monthly USD cost cap. `null` = no cost limit; if set, must be `> 0`
usdPerHour	number	No	-	Hourly USD cost cap. `null` = no limit; if set, must be `> 0`
usdPerDay	number	No	-	Daily USD cost cap. `null` = no limit; if set, must be `> 0`
softCapPercents	array[integer]	No	[]	Soft-cap warning thresholds. Each element in range `[0, 100]`
hardCapPercent	integer	No	100	Hard-cap percent, range `[1, 100]`
overflowAction	string	No	BLOCK	Action on overflow: `BLOCK`, `FAILOVER`, `ALERT_ONLY` or `CHEAPER_MODEL`
cheaperModelId	string	No	-	Cheaper fallback model id (required behaviour when `overflowAction=CHEAPER_MODEL`)
modelBudgets	array	No	keep	Per-model budget overrides (max 50). See list-semantics note below
providerBudgets	array	No	keep	Per-provider budget overrides (max 50). See list-semantics note below

Model / Provider Budget Entry Fields

Field	Type	Required	Description
modelId	string	Yes (model entry)	Catalog model id the override applies to
providerRef	string	Yes (provider entry)	LLM provider reference (`ConnectionConfigLlm` ID) the override applies to
tokensPerHour / tokensPerDay / tokensPerMonth	integer	No	Token caps for this model/provider. If set, must be `>= 1`
monthlyBudgetUsd / usdPerHour / usdPerDay	number	No	USD cost caps for this model/provider. If set, must be `> 0`
overflowAction	string	No	Per-entry overflow action (defaults to `BLOCK`)

Notes

targetType and targetId are required; a blank value returns 400 Bad Request with targetType and targetId are required!.
An empty body returns 400 Bad Request with AI budget update body can not be empty!.
modelBudgets / providerBudgets list semantics: an empty array [] clears all model-/provider-level overrides; null or an absent field keeps the currently stored overrides.
hardCapPercent defaults to 100 and overflowAction defaults to BLOCK when omitted.
When the budget carries a USD limit (monthlyBudgetUsd, usdPerHour or usdPerDay, including inside modelBudgets / providerBudgets) and a model covered by that budget has no input price in the model catalog, the request is rejected with 400 Bad Request and error key aiQuota.usdBudgetModelPriceMissing (parameters modelCount and models). Add the missing price to the model catalog, or drop the USD limit in favor of a token-based one. The same rule applies to the global default / anonymous-default budgets saved through the AI Gateway Settings endpoint (scope: every AI proxy in the installation). Organization budgets are not validated at save time.

Response

Success Response (200 OK)

The response returns the resulting budget as a single-element resultList.

{
  "status": "SUCCESS",
  "resultList": [
    {
      "enabled": true,
      "tokensPerHour": null,
      "tokensPerMinute": null,
      "tokensPerDay": 100000,
      "tokensPerMonth": 2000000,
      "monthlyBudgetUsd": 250.00,
      "usdPerHour": null,
      "usdPerDay": null,
      "softCapPercents": [80, 95],
      "hardCapPercent": 100,
      "overflowAction": "CHEAPER_MODEL",
      "cheaperModelId": "claude-haiku-4-5",
      "modelBudgets": [
        {
          "modelId": "gpt-4o",
          "tokensPerHour": null,
          "tokensPerDay": null,
          "tokensPerMonth": 500000,
          "monthlyBudgetUsd": 100.00,
          "usdPerHour": null,
          "usdPerDay": null,
          "overflowAction": "BLOCK"
        }
      ],
      "providerBudgets": []
    }
  ],
  "resultCount": 1
}

Response Fields

Field	Type	Description
status	string	Response status: `SUCCESS` or `FAILURE`
resultList	array	Single-element list holding the resulting budget object (same shape as the `budget` request field)
resultCount	integer	Always `1` on success

EnumStatus

SUCCESS - Operation successful
FAILURE - Operation failed

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "targetType and targetId are required!"
}

{
  "status": "FAILURE",
  "resultMessage": "AI budget update body can not be empty!"
}

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/ai-budgets/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "CREDENTIAL_ORGANIZATION",
    "targetId": "665f1a2b3c4d5e6f7a8b9c1a",
    "budgetSource": "INHERIT",
    "budget": {
      "enabled": true,
      "tokensPerDay": 100000,
      "tokensPerMonth": 2000000,
      "monthlyBudgetUsd": 250.00,
      "softCapPercents": [80, 95],
      "hardCapPercent": 100,
      "overflowAction": "CHEAPER_MODEL",
      "cheaperModelId": "claude-haiku-4-5",
      "modelBudgets": [],
      "providerBudgets": []
    }
  }'

Notes and Warnings

No license gate: These endpoints do not check the AI_GATEWAY license module. The API layer of Apinizer applies no module gate at all, so an installation whose license does not name AI Gateway reads and writes AI budgets through this resource exactly like a licensed one. Permission is the only gate: the caller still needs the AI_BUDGETS asset category (VIEW for reads, MANAGE for writes), and a missing permission is reported as a 400 Bad Request validation error like everywhere else in APIops. The AI Gateway screens in the Manager UI remain hidden without the module.
Cross-tenant guard: The body targetProjectId is always overwritten with the authenticated path project. You cannot redirect the write to another tenant by supplying a different targetProjectId; omitting it is fine.
ID-based target: targetId is an entity ID, not a name - this is an exception to the APIops name-based convention. Resolve it from a scope-rules (id / scopeRef) or hierarchy (nodeId) read.
targetType vs hierarchy nodeType: The update uses CREDENTIAL_ALLOWED_API_PROXY for a per-credential proxy binding (the effective-limit endpoint calls the equivalent leaf CREDENTIAL). The other three types (CREDENTIAL_ORGANIZATION, API_PROXY, PROJECT) match.
List clear vs keep: Send modelBudgets: [] / providerBudgets: [] to wipe all model-/provider-level limits. Omit the field (or send null) to preserve the stored overrides - a common source of accidental silent wipes.
Defaults on omission: hardCapPercent falls back to 100 and overflowAction to BLOCK when not supplied.
PROJECT target side-effect: Updating a PROJECT (tenant) budget also pushes a project redeploy to the workers so the new tenant cap takes effect at the gateway.
No secret fields: AI budgets carry no @SecretData fields; nothing is masked in the response.
Permission: Requires AI_BUDGETS + MANAGE permission in the project.

Get Budget Scope Rules - Source of targetId values
Get Budget Hierarchy - Tree of owner nodes
Get Effective Limit - Preview the resolved cap after an update
AI Budgets / Quota API - Resource overview

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Query Parameters​

Request Body​

Full JSON Body Example​

Request Body Fields​

Budget Object Fields​

Model / Provider Budget Entry Fields​

Notes​

Response​

Success Response (200 OK)​

Response Fields​

EnumStatus​

Error Response (400 Bad Request)​

Error Response (401 Unauthorized)​

cURL Example​

Notes and Warnings​

Related Documentation​

Endpoint

Authentication

Header

Request

Headers

Path Parameters

Query Parameters

Request Body

Full JSON Body Example

Request Body Fields

Budget Object Fields

Model / Provider Budget Entry Fields

Notes

Response

Success Response (200 OK)

Response Fields

EnumStatus

Error Response (400 Bad Request)

Error Response (401 Unauthorized)

cURL Example

Notes and Warnings

Related Documentation