Update Budget

Endpoint

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

Authentication

Requires a Personal API Access Token.

Header

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.

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!"
}

or

{
  "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

• 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.

Related Documentation

• 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