Skip to main content
Modulo

Cost Management

Modulo provides cost controls to help manage token spend across teams and pipelines. Admin users can set daily spend limits, view cost reports, detect anomalies, and schedule cost report exports.

Which tier

  • Community (free, self-hosted) includes per-agent token budgets, the pipeline spend circuit breaker, and the org-wide pause.
  • Team adds organization and team spend limits, the budget overview, the cost breakdown, and spend-anomaly detection.

Spend Limits

Admins can set org-level and team-level daily spend limits. When a spend limit is reached, new runs that would exceed the limit are rejected.

  • Org-level limit: applies to all runs across the entire organization
  • Team-level limit: applies only to runs for pipelines owned by that team
  • Limits are checked atomically using SELECT FOR UPDATE row locking
  • Setting a limit to null clears it (no limit)

Token Budgets

Each agent can carry a token budget. A run that exceeds an agent’s budget is hard-stopped.

Pipeline Circuit Breaker

Each pipeline has a spend circuit breaker. When the pipeline’s rolling monthly spend trips the breaker, Modulo pauses that pipeline’s triggers until an admin resets it with POST /api/v1/admin/costs/circuit-breaker/{pipeline_id}/reset.

For an org-wide stop, an admin can pause all trigger-initiated runs at once. See Org-wide pause.

Spend ceiling

Two hard ceilings sit above the daily limits. Both are expressed in US dollars at the API boundary (GET and PUT /api/v1/admin/costs/ceiling):

  • max_run_cost: per-run hard ceiling. A run that would exceed it is blocked. 0 blocks all runs; null clears the ceiling.
  • spend_ceiling: org lifetime budget. 0 blocks all runs; null clears the ceiling.

Cost Reports

The cost report endpoint (GET /api/v1/admin/costs) returns aggregated spend data grouped by team or org, for day/week/month/year periods.

Export

Cost data can be exported as comma-separated values (CSV) via GET /api/v1/admin/costs/export.

Scheduled Reports

Admins can create scheduled cost reports that are delivered to specified email recipients:

  • Supports daily, weekly, and monthly periods
  • Supports one_time and recurring schedules
  • Reports are delivered in CSV format

Spend Anomalies

Spend-anomaly detection is part of the Team tier. The system detects anomalies by comparing daily org spend against a rolling 7-day average. A day is flagged as anomalous when spend exceeds 2x the 7-day average.

  • Computed anomalies are merged with stored anomalies from the database
  • Anomalies can be dismissed by admins

API Endpoints

All cost management endpoints require admin authentication.

API Endpoints
Endpoint Description
GET /api/v1/admin/costs Cost report (period, group_by)
GET /api/v1/admin/costs/limits Current spend limits
PUT /api/v1/admin/costs/limits/org Set org daily spend limit
PUT /api/v1/admin/costs/limits/teams/{team_id} Set team daily spend limit
GET /api/v1/admin/costs/controls Cost control settings
PUT /api/v1/admin/costs/controls Update cost control settings
GET /api/v1/admin/costs/ceiling Current spend ceiling
PUT /api/v1/admin/costs/ceiling Update spend ceiling
POST /api/v1/admin/costs/circuit-breaker/{pipeline_id}/reset Reset a tripped pipeline circuit breaker
GET /api/v1/admin/costs/export Export cost report as CSV
POST /api/v1/admin/costs/reports Create scheduled report
GET /api/v1/admin/costs/reports List scheduled reports
DELETE /api/v1/admin/costs/reports/{report_id} Delete scheduled report
GET /api/v1/admin/costs/anomalies List spend anomalies
POST /api/v1/admin/costs/anomalies/dismiss/{anomaly_id} Dismiss an anomaly
Next: SCIM Provisioning