Get Budget Hierarchy

Endpoint

GET /apiops/projects/{projectName}/ai-budgets/hierarchy/

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name

Query Parameters

None

Response

Success Response (200 OK)

resultList contains a single root node (the Project / Tenant). Each node carries its own budget fields and a children array. The tree shape is: TENANT → APP nodes (AI proxies) and ORG nodes (recursive) → CREDENTIAL leaf nodes.

{
  "status": "SUCCESS",
  "resultList": [
    {
      "nodeId": "665f1a2b3c4d5e6f7a8b9c0d",
      "nodeType": "TENANT",
      "name": "MyProject",
      "enabled": true,
      "tokensPerMonth": 10000000,
      "tokensPerDay": 500000,
      "tokensPerMinute": null,
      "monthlyBudgetUsd": 500.00,
      "softCapPercents": [80, 95],
      "hardCapPercent": 100,
      "overflowAction": "BLOCK",
      "cheaperModelId": null,
      "usagePercent": null,
      "status": "NORMAL",
      "inheritedFrom": null,
      "effectiveLimitPreview": null,
      "children": [
        {
          "nodeId": "665f1a2b3c4d5e6f7a8b9c2b",
          "nodeType": "APP",
          "name": "ai-deepseek-proxy",
          "enabled": true,
          "tokensPerMonth": 3000000,
          "tokensPerDay": null,
          "tokensPerMinute": null,
          "monthlyBudgetUsd": null,
          "softCapPercents": [],
          "hardCapPercent": 100,
          "overflowAction": "BLOCK",
          "cheaperModelId": null,
          "usagePercent": null,
          "status": "NORMAL",
          "inheritedFrom": null,
          "effectiveLimitPreview": null,
          "children": []
        },
        {
          "nodeId": "665f1a2b3c4d5e6f7a8b9c1a",
          "nodeType": "ORG",
          "name": "engineering-team",
          "enabled": true,
          "tokensPerMonth": 2000000,
          "tokensPerDay": null,
          "tokensPerMinute": null,
          "monthlyBudgetUsd": null,
          "softCapPercents": [90],
          "hardCapPercent": 100,
          "overflowAction": "CHEAPER_MODEL",
          "cheaperModelId": "claude-haiku-4-5",
          "usagePercent": 42.7,
          "status": "NORMAL",
          "inheritedFrom": null,
          "effectiveLimitPreview": null,
          "children": [
            {
              "nodeId": "665f1a2b3c4d5e6f7a8b9c3c",
              "nodeType": "CREDENTIAL",
              "name": "api-user-1",
              "tokensPerMonth": null,
              "usagePercent": null,
              "status": "INHERITED",
              "inheritedFrom": "engineering-team",
              "effectiveLimitPreview": null,
              "children": []
            }
          ]
        }
      ]
    }
  ],
  "resultCount": 1
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE
resultList	array	Contains the single root (Tenant) node
resultCount	integer	Always 1 when a hierarchy exists, 0 otherwise

Hierarchy Node Fields

Field	Type	Description
nodeId	string	Node entity ID (use with the effective-limit / update endpoints)
nodeType	string	Node type: TENANT, APP, ORG or CREDENTIAL
name	string	Node display name
enabled	boolean	Whether the node's own budget is enabled (own-budget nodes only)
tokensPerMonth	integer	Monthly token cap at this node. null = inherited / unconfigured
tokensPerDay	integer	Daily token cap at this node. null = inherited / unconfigured
tokensPerMinute	integer	Per-minute token cap at this node. null = inherited / unconfigured
monthlyBudgetUsd	number	Monthly USD cost cap. null = no cost limit
softCapPercents	array[integer]	Soft-cap warning thresholds (percent). Empty when unconfigured
hardCapPercent	integer	Hard-cap percent. null = default (100)
overflowAction	string	Action on overflow: BLOCK, FAILOVER, ALERT_ONLY or CHEAPER_MODEL
cheaperModelId	string	Cheaper fallback model id (used when overflowAction=CHEAPER_MODEL)
usagePercent	number	Approximate usage percent. null until usage data exists or limit unset
status	string	Node status: NORMAL, AT_CAPACITY, LOCKED, DISABLED or INHERITED
inheritedFrom	string	Name of the ancestor node this node inherits its limit from. null if the node has its own limit
effectiveLimitPreview	integer	Lazy effective-limit preview. null on initial load (computed only when a node is expanded in the UI)
children	array	Child hierarchy nodes (recursive)

EnumStatus

• SUCCESS - Operation successful
• FAILURE - Operation failed

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Project with name (MyProject) is not found!"
}

Error Response (401 Unauthorized)

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

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/ai-budgets/hierarchy/" \
  -H "Authorization: Bearer YOUR_TOKEN"

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.
• Single root: resultList holds exactly one node - the Project / Tenant root. Everything else is nested under children.
• Tree shape: TENANT → APP (AI proxies, type=AI) and ORG (root credential organizations, recursive sub-orgs) → CREDENTIAL leaf nodes.
• Cycle guard: The traversal is bounded by a visited-ID set (max 10 iterations) to protect against malformed org parent cycles.
• No _class: The response DTO carries no MongoDB _class discriminator.
• effectiveLimitPreview is lazy: It is null in the tree read. Use the effective-limit endpoint with a node's nodeId to compute the resolved cap.
• Inheritance: A null tokensPerMonth with status = INHERITED means the node has no own cap and inherits from inheritedFrom.
• Permission: Requires AI_BUDGETS + VIEW in the project.

Related Documentation

• Get Budget Scope Rules - Same data flattened to a table
• Get Effective Limit - Resolve the effective cap for one node
• Update Budget - Change an owner budget
• AI Budgets / Quota API - Resource overview