Budgets API

listBudgets

GET /api/v2/budgets

Requires: invoke role

Budgets visible to the caller (every budget of the namespace for admins, otherwise the caller's own), newest first, optionally filtered by scope. Definitions only; read budgetUsage or budgetStatus for consumption.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.list_budgets()

Parameters

Responses

Example response 200

{
  "items": [
    {
      "action": "string",
      "created_at": 0,
      "enabled": false,
      "id": "string",
      "limit": 0.0,
      "metric": "tokens",
      "name": "string",
      "principal": "string",
      "revision": 0,
      "scope": "string",
      "subject": "string",
      "updated_at": 0,
      "window": "string"
    }
  ]
}

createBudget

POST /api/v2/budgets

Requires: invoke role

Create an admission-time budget: one metric (tokens or cost_usd from usage receipts, or runs = admitted root executions) over a rolling window (1h, 24h, 7d, 30d) for one scope. subject is the principal, agent label or label.capability the scope binds and is absent for namespace. A deny budget (the default) refuses traversers.submit with 429 budget_exceeded once consumption in the window has reached the limit; a warn budget never blocks and only adds warnings to access decisions. Namespace budgets and budgets over another principal require admin; label and target budgets require owning the label. The creating principal owns the budget; admins see every budget in the namespace, other callers only their own. Namespaces hold at most 256 budgets (422 budgets_full).

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.create_budget()

Request body

BudgetCreate (required)

{
  "limit": 0.0,
  "metric": "tokens",
  "name": "string",
  "scope": "string",
  "window": "string"
}

Responses

Example response 201

{
  "action": "string",
  "created_at": 0,
  "enabled": false,
  "id": "string",
  "limit": 0.0,
  "metric": "tokens",
  "name": "string",
  "principal": "string",
  "revision": 0,
  "scope": "string",
  "subject": "string",
  "updated_at": 0,
  "window": "string"
}

budgetStatus

GET /api/v2/budgets/status

Requires: invoke role

Every enabled budget that would apply to an admission by principal (the caller unless an admin names another; 403 otherwise) of target (label.capability; without it only principal and namespace budgets apply), each with its headroom. allowed is false when a deny budget is exceeded, exactly as traversers.submit would refuse. Warn budgets are listed but never affect allowed.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.budget_status()

Parameters

Responses

Example response 200

{
  "allowed": false,
  "items": [
    {
      "action": "string",
      "as_of": 0,
      "budget_id": "string",
      "consumed": 0.0,
      "enabled": false,
      "exceeded": false,
      "limit": 0.0,
      "metric": "tokens",
      "name": "string",
      "remaining": 0.0,
      "scope": "string",
      "subject": "string",
      "window": "string",
      "window_start": 0
    }
  ],
  "principal": "string",
  "target": "string"
}

getBudget

GET /api/v2/budgets/{id}

Requires: invoke role

One budget definition. A budget owned by another principal is 404 budget_not_found rather than 403, the same answer as an unknown id.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.get_budget()

Parameters

Responses

Example response 200

{
  "action": "string",
  "created_at": 0,
  "enabled": false,
  "id": "string",
  "limit": 0.0,
  "metric": "tokens",
  "name": "string",
  "principal": "string",
  "revision": 0,
  "scope": "string",
  "subject": "string",
  "updated_at": 0,
  "window": "string"
}

updateBudget

PATCH /api/v2/budgets/{id}

Requires: invoke role

Compare-and-set edit of name, window, limit, action and enabled. expected_revision must equal the current revision or the request fails with 409 revision_mismatch; scope, subject and metric are immutable and any other field is rejected (400 invalid_budget). Disabling a budget suspends enforcement without losing it.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.update_budget()

Parameters

Request body

BudgetUpdate (required)

{
  "expected_revision": 0
}

Responses

Example response 200

{
  "action": "string",
  "created_at": 0,
  "enabled": false,
  "id": "string",
  "limit": 0.0,
  "metric": "tokens",
  "name": "string",
  "principal": "string",
  "revision": 0,
  "scope": "string",
  "subject": "string",
  "updated_at": 0,
  "window": "string"
}

deleteBudget

DELETE /api/v2/budgets/{id}

Requires: invoke role

Delete one budget. expected_revision travels as a query parameter and, when given, must match (409 revision_mismatch). Consumption records are the runtime's own and are untouched.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.delete_budget()

Parameters

Responses

Example response 200

{
  "deleted": false
}

budgetUsage

GET /api/v2/budgets/{id}/usage

Requires: invoke role

Consumption of one budget in its current rolling window, read from usage receipts (tokens, cost_usd) or admitted root traversers (runs), with the derived remaining headroom and whether the limit is reached. This is the same reading the admission path takes; nothing is cached.

Generated Python client internals: atfgraph._generated.api.budgets_api.BudgetsApi.budget_usage()

Parameters

Responses

Example response 200

{
  "action": "string",
  "as_of": 0,
  "budget_id": "string",
  "consumed": 0.0,
  "enabled": false,
  "exceeded": false,
  "limit": 0.0,
  "metric": "tokens",
  "name": "string",
  "remaining": 0.0,
  "scope": "string",
  "subject": "string",
  "window": "string",
  "window_start": 0
}