Get Budget Scope Rules

Endpoint

GET /apiops/projects/{projectName}/ai-budgets/scope-rules/

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)

Each element of resultList is one row of the Scope Rules table. Rows are aggregated from four owner sources; entityType identifies the source. Unconfigured caps are null. usagePercent is null until the usage-aggregation job has produced data.

{
  "status": "SUCCESS",
  "resultList": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "entityType": "PROJECT",
      "entityName": "MyProject",
      "scope": "project",
      "scopeRef": "665f1a2b3c4d5e6f7a8b9c0d",
      "tokensPerMonth": 10000000,
      "tokensPerDay": 500000,
      "tokensPerMinute": null,
      "overflowAction": "BLOCK",
      "sourceType": null,
      "enabled": true,
      "usagePercent": null,
      "budgetSource": null,
      "monthlyBudgetUsd": 500.00,
      "usdPerHour": null,
      "usdPerDay": null,
      "softCapPercents": [80, 95],
      "hardCapPercent": 100,
      "cheaperModelId": null,
      "modelBudgets": [],
      "providerBudgets": []
    },
    {
      "id": "665f1a2b3c4d5e6f7a8b9c1a",
      "entityType": "CREDENTIAL_ORG",
      "entityName": "engineering-team",
      "scope": "credential_organization",
      "scopeRef": "665f1a2b3c4d5e6f7a8b9c1a",
      "tokensPerMonth": 2000000,
      "tokensPerDay": null,
      "tokensPerMinute": null,
      "overflowAction": "CHEAPER_MODEL",
      "sourceType": "LDAP_GROUP",
      "enabled": true,
      "usagePercent": 42.7,
      "budgetSource": null,
      "monthlyBudgetUsd": null,
      "usdPerHour": null,
      "usdPerDay": null,
      "softCapPercents": [90],
      "hardCapPercent": 100,
      "cheaperModelId": "claude-haiku-4-5",
      "modelBudgets": [],
      "providerBudgets": []
    }
  ],
  "resultCount": 2
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE
resultList	array	List of scope-rule row objects
resultCount	integer	Total number of scope-rule rows returned

Scope Rule Object Fields

Field	Type	Description
id	string	Owner entity ID
entityType	string	Owner source: CREDENTIAL_ORG, API_PROXY, PROJECT or CREDENTIAL_BINDING
entityName	string	Human-readable owner name (org / proxy / project / credential name)
scope	string	Rate-limit scope string (e.g. project, credential_organization, credential)
scopeRef	string	Scope reference entity ID (used as scopeRef in usage records)
tokensPerMonth	integer	Monthly token cap. null = no limit configured
tokensPerDay	integer	Daily token cap. null = no limit configured
tokensPerMinute	integer	Per-minute token cap. null = no limit configured
overflowAction	string	Action on cap overflow: BLOCK, FAILOVER, ALERT_ONLY or CHEAPER_MODEL. null when budget unconfigured
sourceType	string	Budget source for CREDENTIAL_BINDING rows: MANUAL, LDAP_OU, LDAP_GROUP, CREDENTIAL, ORGANIZATION or INHERIT
enabled	boolean	Whether the budget rule is enabled
usagePercent	number	Approximate usage percent (last-30-day tokens / tokensPerMonth × 100). null until usage data exists or tokensPerMonth is unset
budgetSource	string	Budget source for binding rows: CREDENTIAL, ORGANIZATION or INHERIT
monthlyBudgetUsd	number	Monthly USD cost cap. null = no cost limit
usdPerHour	number	Hourly USD cost cap. null = no limit
usdPerDay	number	Daily USD cost cap. null = no limit
softCapPercents	array[integer]	Soft-cap warning thresholds (percent). Empty when unconfigured
hardCapPercent	integer	Hard-cap percent. null = default (100)
cheaperModelId	string	Cheaper fallback model id (used when overflowAction=CHEAPER_MODEL)
modelBudgets	array	Per-model budget overrides. Empty when unconfigured
providerBudgets	array	Per-provider budget overrides. Empty when unconfigured

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/scope-rules/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Notes and Warnings

• Aggregated view: Rows come from four owner sources - credential bindings (CREDENTIAL_BINDING), credential organizations (CREDENTIAL_ORG), AI proxies (API_PROXY) and the project tenant cap (PROJECT). entityType tells you which.
• No _class: The response DTO carries no MongoDB _class discriminator.
• Unconfigured caps are null: A null tokensPerMonth / tokensPerDay / tokensPerMinute means no limit is set at that owner, not zero.
• Usage may be null: usagePercent is derived from AiTokenUsageDaily (last 30 days / tokensPerMonth); it is null until the usage-aggregation job has produced data.
• IDs, not names: id / scopeRef are entity IDs. Use them with the effective-limit and update endpoints.
• Empty List: A project with no configured AI budgets returns an empty resultList with resultCount = 0.
• Permission: Requires AI_BUDGETS + VIEW in the project.

Related Documentation

• Get Budget Hierarchy - Same data as a tree
• Get Effective Limit - Resolve the effective cap for one node
• Update Budget - Change an owner budget
• AI Budgets / Quota API - Resource overview