Cost Controls API

The cost controls surface has two layers:

community-visible routes for pricing and usage summary
non-community routes for budget creation, enforcement, alerts, and deeper usage analytics

That split is important for engineers evaluating AxonFlow. You can start by observing LLM usage and pricing, then move into evaluation or paid deployments when you need budget enforcement, alerting, and operational guardrails around spend.

SDK Support

All Cost Controls endpoints are available through the official SDKs:

Base URL: http://localhost:8080 via Agent proxy, or http://localhost:8081 if you expose the Orchestrator directly.

Authentication

All endpoints require:

Authorization: Basic base64(clientId:clientSecret) header
Content-Type: application/json header for POST and PUT requests

Optional:

Tenant context (derived from Basic auth credentials) and X-Org-ID scope usage and budgets
X-User-ID is used on budget writes for audit attribution

Overview

Verified route families:

Method	Path	Availability
`GET`	`/api/v1/pricing`	Community-visible
`GET`	`/api/v1/usage`	Community-visible
`POST`	`/api/v1/budgets`	Non-community
`GET`	`/api/v1/budgets`	Non-community
`POST`	`/api/v1/budgets/check`	Non-community
`GET`	`/api/v1/budgets/{id}`	Non-community
`PUT`	`/api/v1/budgets/{id}`	Non-community
`DELETE`	`/api/v1/budgets/{id}`	Non-community
`GET`	`/api/v1/budgets/{id}/status`	Non-community
`GET`	`/api/v1/budgets/{id}/alerts`	Non-community
`GET`	`/api/v1/usage/breakdown`	Non-community
`GET`	`/api/v1/usage/records`	Non-community

Budget limits can be applied at these verified scopes:

Scope	Description
`organization`	Organization-wide budget
`team`	Budget for a specific team
`agent`	Budget for an individual agent
`workflow`	Budget for a workflow
`user`	Budget for a specific user

Budget Management

Create Budget

Create a new budget with spending limits. The handler applies defaults when omitted:

scope defaults to organization
on_exceed defaults to warn
alert_thresholds defaults to [50, 80, 100]

POST /api/v1/budgets

Headers:

Content-Type: application/json
Authorization: Basic base64(clientId:clientSecret)
tenant derived from Basic auth: tenant-123
X-User-ID: [email protected]

Request Body:

{
  "id": "monthly-budget",
  "name": "Monthly Production Budget",
  "scope": "organization",
  "limit_usd": 1000.00,
  "period": "monthly",
  "on_exceed": "warn",
  "alert_thresholds": [50, 80, 100]
}

Field	Type	Required	Default	Description
`id`	string	Yes	-	Unique budget identifier
`name`	string	Yes	-	Human-readable budget name
`scope`	string	No	`organization`	Budget scope
`scope_id`	string	No	`null`	ID of the scoped entity when needed
`limit_usd`	number	Yes	-	Budget limit in USD
`period`	string	Yes	-	`daily`, `weekly`, `monthly`, `quarterly`, or `yearly`
`on_exceed`	string	No	`warn`	`warn`, `block`, or `downgrade`
`alert_thresholds`	number[]	No	`[50,80,100]`	Percentage thresholds

List Budgets

List budgets with filters for scope, tenant, organization, or enabled state. The handler supports:

scope
scope_id
limit
offset
enabled
tenant_id
org_id

Check Budget (Pre-flight)

Check if a request should be allowed based on budget constraints. Use this before making LLM requests.

POST /api/v1/budgets/check

Request Body:

{
  "org_id": "your-org-id",
  "team_id": "engineering",
  "agent_id": "support-bot"
}

Response (Allowed):

{
  "allowed": true
}

Response (Blocked):

{
  "allowed": false,
  "action": "block",
  "budget_id": "monthly-budget",
  "budget_name": "Monthly Production Budget",
  "used_usd": 1100,
  "limit_usd": 1000,
  "percentage": 110,
  "message": "Budget exceeded"
}

Why Teams Use This API

Engineering leads use pricing and usage endpoints to understand real provider cost patterns before production rollout.
Platform teams use budgets to prevent one workflow, one user group, or one agent from exhausting shared spend.
Procurement and architecture reviewers often care about this surface because cost governance is part of the production-readiness story, not just an ops afterthought.

Authentication​

Overview​

Budget Management​

Create Budget​

List Budgets​

Check Budget (Pre-flight)​

Why Teams Use This API​

Related Docs​