The Complexity Cost Calculator API returns three numbers: the Sync Tax multiplier (how much coupling and coordination inflate each change), the Total Cost of Complexity (what that costs per quarter, including maintenance and incident risk), and the Failure Risk Multiplier. It also shows how your level of AI adoption changes those costs over time.
Authentication
All endpoints except /v1/health require an API key in the X-API-Key header:
curl -H "X-API-Key: cc_abc123def456..." https://api.complexity-cost-calculator.beamercloud.com/v2/calculate ...
Get your free API key at your account page. No credit card required for the Free plan.
Endpoints
Base URL: https://api.complexity-cost-calculator.beamercloud.com
Parameters
Describe one typical change (a feature) and your organization. All hours are engineering hours. Unknown fields are rejected, so typos surface as errors.
vacuum_effort number required
Hours a typical change would take in a perfectly modular system: one module, no dependencies, no meetings.
Where to get it: Ask a senior engineer: "If this were the only code we had, how long would this change take?"
connascence_degree number required
How many other modules typically have to change together with the main one. A count, not a score. Averages such as 2.5 are fine; 0 means changes stay inside one module.
Where to get it: Look at recent changes: how many unrelated modules did each one drag along?
coordination_hours number required
Hours per change spent in meetings, threads, calls and reviews that exist only because the system is tangled. 0 for a change nobody else has to hear about.
Where to get it: An estimate is enough: how much time did the last few changes cost other people?
engineers integer required
Engineers in the organization. Used to express costs as a share of capacity and as engineers' worth of time.
teams integer required
Engineering teams in the organization.
teams_per_change integer optional
Teams a typical change crosses, at most teams. Defaults to one more than the connascence degree, capped at teams.
decision_people number optional
How many people outside the teams take part in a typical cross-team decision: engineering managers, directors, product managers, architects, a VP. 0 to 100, default 2. Count people, not layers, because a layer usually brings more than one person. Under AI adoption each of them adds their own share of lost understanding, because they rely on what the teams understand.
interdependence_factor number optional
Extra effort each dragged module adds, as a share of the vacuum effort. Defaults to 0.5. Tightly coupled systems often run above 1.0; loosely coupled ones can be 0.2 or lower. Pro users can fit it from their own changes (see Pro features).
features_per_year number optional
Changes shipped per year. Defaults to 20.
maintenance_hours_per_quarter, infrastructure_hours_per_quarter number optional
Hours per quarter spent keeping the tangle running: patches, migrations, sync jobs, and infrastructure that exists only because of the coupling. Convert money to hours by dividing by your hourly rate. Default 0.
incident_likelihood, incident_cost_hours number optional, together
The chance that a change causes an incident (0 to below 1), and the average cost of one incident in hours (detect, fix, validate, plus business loss divided by your hourly rate). Give both to get the Failure Risk Multiplier.
hourly_rate number optional
Fully loaded cost per engineering hour. Adds _usd fields next to the hour fields.
projection_quarters integer optional
How many quarters ahead to project, 1 to 20. Defaults to 12.
AI adoption
Pass ai_adoption with a level and how many quarters you have been at it (quarters_at_level, default 0):
| Level | Meaning |
|---|---|
| 0 | No AI adoption |
| 1 | AI helps with coding, for example Copilot-style completion |
| 2 | AI does all the coding; people review it |
| 3 | AI does the coding, checks, reviews, and monitoring |
AI makes the hands-on work faster. It also erodes team ownership: how much of its own code the team actually understands. Ownership falls gradually while code is rewritten at the higher levels, and lost ownership makes coordination slower, decisions worse, incidents more likely and harder to fix. Every team a change crosses and every person outside the teams who takes part in the decision adds their own share of lost understanding, with no ceiling, so organizations whose changes cross more teams and involve more people pay more.
The response's ai.change_vs_no_ai_hours shows, per feature, which costs AI made cheaper and which it made more expensive: own work, coupling work, coordination, safeguards and expected incidents. The costs that grow are the places where putting people back in the loop, or automating, can lower the final cost.
The response shows the result today and a projection, with a low, expected and high band, because how much lost ownership costs has not been measured yet. AI tool and inference spend is not part of the calculation.
Response
sync_tax_multiplier: total effort of a change divided by its vacuum effort. 1.0 is a perfectly modular change.per_feature: hours of own work, coupling work, coordination and safeguards (the hours the levers add), the total, the expected incident hours of one change, and the all-in total including them.per_quarter: complexity cost, failure risk cost, Total Cost of Complexity, Failure Risk Multiplier, all engineering hours, and the share of capacity lost to complexity.per_year: the quarterly totals times four.ai: team ownership, understanding of the module boundaries, teams a change typically crosses, people outside the teams, decision participants, lost understanding added up over the participants, the chance a cross-team decision is made without full understanding, the adjusted incident likelihood, engineers' worth of capacity freed by AI (negative means lost), what got cheaper and what got more expensive per feature against no AI, and the same change without AI.horizon: engineering hours over the projection, with and without AI, including any one-off safety net build.levers: the levers applied and the one-off safety net build hours.plan: Pro only,nullon the Free plan. See Levers.notice: present when the request sent Pro fields on the Free plan. It lists the ignored fields and links to the upgrade.projection: one entry per quarter withexpected,low,highandno_aivalues, each with hours per feature and all-in hours per feature (expected incidents included).assumptions: the starting values used for this response, including the lever values. They are starting values, not fitted.
Pro features
These fields need a Pro plan. The Free plan accepts the AI adoption level and uses starting values for everything else. If a Free request sends these fields, the API still answers, leaves them out, uses the starting values listed under assumptions, and lists what it ignored in notice.
calibration_changes array
Fit the interdependence factor from your own changes. Each item: vacuum_effort, connascence_degree, coordination_hours, actual_hours. Include changes that stayed inside one module as a control, and ideally ten or more that did not. The response's calibration field reports the fitted value and warns when coupled changes show no extra hours.
team_adoption array
Different teams at different levels. Each item: teams, level, quarters_at_level. Team counts must add up to teams. Use instead of ai_adoption.
ai_assumptions object
Replace the starting values with your own: per level (levels, keys "1" to "3") the AI speedup, understanding kept, review share, the share of safety net work AI writes and the share of incident cost AI removes by reacting to events; plus code turnover per quarter and the coordination, decision and incident penalties. Setting any penalty replaces the band with a single line.
connascence_degree_change_per_quarter number
How the connascence degree moves each quarter in the projection. Negative for a modularization plan, positive for growing coupling.
levers object
Turn levers on with true: human_interfaces, explain_before_merge, safety_net, decision_rights. The result, the projection and the horizon then include their effects and their costs.
lever_assumptions object
Replace the lever starting values with your own, per lever. Any value you leave out keeps its starting value.
Levers
Showing that AI costs more is a diagnosis. The levers are the treatment: each one puts people back in the loop, or automates, where AI makes a cost worse, and each has its own cost. Moving one lever changes what the others are worth, so the API tries every combination.
| Lever | What it protects | What it costs | Starting values |
|---|---|---|---|
human_interfaces: people design and review every change that crosses a module boundary, AI writes inside modules | Understanding of the boundaries, which drives coupling work, coordination and half of incidents | Review hours for every module a change pulls along | 95% understanding kept at the boundaries, review of 10% of the vacuum effort per coupled module, half of incidents start at a boundary |
explain_before_merge: the engineer must be able to explain the AI's change | Understanding of the code itself | Part of the AI speedup | Keeps 55% of the understanding AI would lose, gives up 30% of the speedup |
safety_net: contract tests at every boundary, monitoring, canary releases with automatic rollback | How often incidents happen and what they cost | A one-off build, upkeep every quarter, and test hours per coupled module. AI writes part of it, more at the higher levels, and at levels 2 and 3 AI reacting to events makes incidents cheaper again | 80 build hours and 10 upkeep hours per team per quarter, tests of 5% of the vacuum effort per coupled module, half of incidents prevented, 30% of incident cost removed |
decision_rights: decisions move to the teams that own the code | Fewer people in each decision, and fewer meeting hours | A written record of each decision for the people who left the room | Half of the people outside the teams leave the decision, one hour of writing per change |
On Pro, every response carries a plan:
plan.current: for your own adoption, the hours over the horizon with no levers, the best combination and its hours, the hours it saves, the quarter in which it has paid back its up-front cost, and per lever the hours it saves on its own and next to the rest of the best combination.plan.by_level: the same for every team at level 0, 1, 2 and 3, starting now.plan.cheapest: the level and levers with the lowest engineering hours over the horizon.
A lever that saves hours on its own can be worth nothing next to another one. For example, once people own the interfaces, asking engineers to explain every change often costs more speed than the understanding it adds. A safety net only pays when incidents cost more than its upkeep, which usually means higher AI levels or larger organizations.
Examples
A feature that drags three modules along
curl -X POST https://api.complexity-cost-calculator.beamercloud.com/v2/calculate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key-here" \
-d '{
"vacuum_effort": 20,
"connascence_degree": 3,
"coordination_hours": 10,
"engineers": 8,
"teams": 2,
"hourly_rate": 120
}'
Response (abridged):
{
"model_version": "2.0.0",
"sync_tax_multiplier": 3,
"per_feature": {
"vacuum_effort_hours": 20,
"own_work_hours": 20,
"coupling_hours": 30,
"coordination_hours": 10,
"sync_tax_hours": 40,
"total_hours": 60,
"sync_tax_usd": 4800,
"total_usd": 7200
},
"per_quarter": { "changes": 5, "total_cost_of_complexity_hours": 200, ... },
"ai": { "team_ownership": 1, ... },
"projection": [ ... ],
"assumptions": { "status": "starting values, not fitted", ... }
}
The same team, a year into AI writing all the code
curl -X POST https://api.complexity-cost-calculator.beamercloud.com/v2/calculate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key-here" \
-d '{
"vacuum_effort": 20,
"connascence_degree": 3,
"coordination_hours": 10,
"engineers": 8,
"teams": 2,
"hourly_rate": 120,
"ai_adoption": { "level": 2, "quarters_at_level": 4 }
}'
Response (abridged): the hands-on work is faster, but the change still costs about as much as without AI.
{
"sync_tax_multiplier": 3.33,
"per_feature": { "own_work_hours": 13, "coupling_hours": 28.81, "coordination_hours": 17.78, "total_hours": 59.59, ... },
"ai": {
"team_ownership": 0.7228,
"uninformed_decision_chance": 0.4776,
"engineers_freed": 0,
"no_ai": { "sync_tax_multiplier": 3, "hours_per_feature": 60, ... }
},
...
}
v1 (deprecated)
POST /v1/calculate still accepts connascence_degree, n_authors, n_teams, dept_size, vacuum_effort, hourly_rate and features_per_year, and returns the same response as before. It estimates coordination from team counts instead of asking for it and does not include maintenance, incident risk or AI adoption. Move to /v2/calculate.
Rate Limits
| Plan | Requests / Day | Price |
|---|---|---|
| Free | 100 | $0 |
| Pro | 10,000 | $29/mo |
| Enterprise | Custom | Contact |
Rate limits reset at midnight UTC. Visit your account to view usage and upgrade.
The Engineering Tax
The calculator is built on The Engineering Tax, David Vartanian's article series on the invisible costs that destroy software product margins.
MCP Server
AI agents and coding assistants can call the calculator directly through its MCP server, without writing raw API calls.
Connect your MCP client to https://mcp.complexity-cost-calculator.beamercloud.com/mcp and send your API key in the X-API-Key header.
The calculate tool takes the same inputs as POST /v2/calculate and returns the same response, with the same Free and Pro rules.
In Claude Code:
claude mcp add --transport http complexity-cost https://mcp.complexity-cost-calculator.beamercloud.com/mcp --header "X-API-Key: YOUR_KEY"
In clients that read an mcpServers file, such as Cursor:
{
"mcpServers": {
"complexity-cost": {
"url": "https://mcp.complexity-cost-calculator.beamercloud.com/mcp",
"headers": { "X-API-Key": "YOUR_KEY" }
}
}
}
It is listed on the official MCP Registry, and its source is on GitHub.