Beamer

Complexity Cost API Reference

Home Account
v2.1.0

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

GET/v1/health
Health check. Public. No API key required.
POST/v2/calculate
Calculate the cost of complexity for one typical change. JSON body with the parameters below.
POST/v1/calculate
Deprecated. Still answers so existing integrations keep working. See v1.

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):

LevelMeaning
0No AI adoption
1AI helps with coding, for example Copilot-style completion
2AI does all the coding; people review it
3AI 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, null on 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 with expected, low, high and no_ai values, 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.

LeverWhat it protectsWhat it costsStarting values
human_interfaces: people design and review every change that crosses a module boundary, AI writes inside modulesUnderstanding of the boundaries, which drives coupling work, coordination and half of incidentsReview hours for every module a change pulls along95% 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 changeUnderstanding of the code itselfPart of the AI speedupKeeps 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 rollbackHow often incidents happen and what they costA 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 again80 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 codeFewer people in each decision, and fewer meeting hoursA written record of each decision for the people who left the roomHalf 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

PlanRequests / DayPrice
Free100$0
Pro10,000$29/mo
EnterpriseCustomContact

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.

Read The Engineering Tax →

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.