§ DOCUMENTATION

AI FinOps

Attribute AI agent spend to cost_center, project, and team dimensions. Generate chargeback CSV reports for finance, set budget caps with alert states, and forecast month-end spend before it surprises you.

§ 01

Cost attribution dimensions

On trace ingest, pass costCenter, project, and/or team fields alongside the standard trace payload. Execlave stores these as dedicated columns on execution_traces and uses them as grouping keys for all cost reporting, budget caps, and forecasts. Tagging is optional per trace; untagged traces are included in totals but cannot be broken down by dimension.

Dimension	Typical use
costCenter	Maps to a finance cost center code for chargeback allocation
project	Groups spend by product initiative or client engagement
team	Groups spend by engineering or business team for internal showback

§ 02

Chargeback reports & CSV export

Tag a trace at ingest time using the costCenter, project, and team fields:

curl -X POST https://api.execlave.com/api/v1/traces/ingest \  -H "Authorization: Bearer $EXECLAVE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "agentId": "agt_01j...",    "input": "Summarise Q2 revenue figures",    "output": "...",    "costCenter": "finance",    "project":    "q2-reporting",    "team":       "data-analytics",    "tokensUsed": 1840,    "modelId":    "claude-sonnet-4-6"  }'

GET /api/v1/cost/report returns spend grouped by any dimension. Add format=csv to receive a properly escaped CSV for your finance team:

# Chargeback report grouped by cost_center (returns JSON by default)curl "https://api.execlave.com/api/v1/cost/report?groupBy=costCenter" \  -H "Authorization: Bearer $EXECLAVE_API_KEY" # Export as CSV for financecurl "https://api.execlave.com/api/v1/cost/report?groupBy=costCenter&format=csv" \  -H "Authorization: Bearer $EXECLAVE_API_KEY" \  -o chargeback.csv

§ 03

Budget caps & status alerts

Set a monthly spend cap for any dimension value. Caps are stored in the budget_caps table (RLS-scoped to your org). GET /api/v1/cost/budgets/status returns current spend versus each cap and an alert state so you can surface warnings in dashboards or alerting pipelines:

# Create a monthly budget cap for the finance cost centercurl -X POST https://api.execlave.com/api/v1/cost/budgets \  -H "Authorization: Bearer $EXECLAVE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "dimension":  "costCenter",    "value":      "finance",    "limitUsd":   500,    "periodType": "monthly"  }' # Check current spend vs capcurl https://api.execlave.com/api/v1/cost/budgets/status \  -H "Authorization: Bearer $EXECLAVE_API_KEY"

§ 04

Month-end cost forecast

GET /api/v1/cost/forecast projects month-end spend from the recent daily cost series. The backend calls the processing service at POST /forecast/cost, which applies time-series forecasting to the daily spend data and returns a projected month-end spend figure alongside a breach probability — the likelihood the current trajectory will exceed any active budget caps.

Because the forecast reads the live daily series at request time, it reflects mid-month spend changes automatically. Call the endpoint from a scheduled job or surface it in the dashboard to give finance and engineering teams early warning before a budget cap is hit.

§ 05

Relation to the real-time cost circuit breaker

AI FinOps budget caps are asynchronous — they accumulate spend, compare against a threshold, and surface an alert state. They are the right tool for monthly planning, chargeback, and trend visibility.

The real-time cost circuit breaker is a synchronous policy that fires in the hot path of every agent action. When per-org or per-agent spend hits the configured cap, the circuit breaker blocks the action immediately rather than surfacing an alert after the fact. See the governance overview for details on configuring the circuit breaker in a policy rule definition.

§ 06

Frequently asked questions

Do I need to tag every trace for cost attribution to work?

No. Tagging is optional per trace. Traces without cost dimensions are still captured and appear in the overall spend total; they simply cannot be broken down by cost_center, project, or team. For chargeback purposes, untagged spend is reported as a separate unattributed line so finance teams can see the full picture.

How does the month-end forecast handle mid-month budget changes?

The forecast endpoint queries the recent daily cost series at request time and sends it to the processing service. Because it reads the current series rather than a cached snapshot, a mid-month budget change or a sudden spike in agent activity is reflected in the next forecast call automatically. The processing service returns both a projected month-end spend figure and a breach probability.

What is the difference between a budget cap and the real-time cost circuit breaker?

Budget caps (POST /api/v1/cost/budgets) are asynchronous spend limits — they track cumulative spend against a threshold and surface an alert state via GET /api/v1/cost/budgets/status. They are intended for FinOps visibility and chargeback enforcement. The real-time cost circuit breaker is a synchronous per-org or per-agent policy that blocks individual agent actions the moment a spend cap is hit. Both are complementary: budget caps govern monthly planning; the circuit breaker governs runtime enforcement.

Is there a feature flag to enable AI FinOps?

No. Cost attribution is available as soon as the migration runs and you begin tagging traces with costCenter, project, or team. There is no feature flag gating the cost endpoints. Budget caps and the forecast endpoint are similarly available without opt-in.