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

• 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