Plan-Time Cost

Stategraph prices a pending change before you apply it. When you run stategraph tf plan, it estimates what the plan would cost and prints a current-vs-planned delta right under the diff, so an expensive change is visible in review rather than on next month's bill.

At Plan Time

stategraph tf plan fetches the cost delta automatically and prints a Costs: block after the plan:

stategraph tf plan --tenant <tenant-id> --out plan.json

Plan: 1 to add, 0 to change, 0 to destroy.

Costs:
  Totals:
    Monthly:  — → 60.74 USD   (+60.74 USD)
    Hourly:   — → 0.08 USD   (+0.08 USD)
    Resources: 0 → 1 (+1)
    Coverage: 100.0% (unchanged)
  Per state:
    cost-preview-demo: +60.74/mo  (resources +1)
      + aws_instance.web                                    +60.74

Each Totals line reads current → planned (±delta). A — means that side had nothing priced; here the state is new, so its current cost is — and the plan adds $60.74/mo. Changing existing infrastructure shows both sides, for example Monthly: 130.82 USD → 140.16 USD (+9.34 USD).

The delta is best-effort and never blocks the plan. If the preview is not ready yet, you will see a hint instead of the block:

Costs: preview not yet ready. Run `stategraph tx costs --tx <tx_id>` to view it later.

On a fetch error, or when pricing is not configured, the plan prints nothing extra. Pass --skip-costs to turn the fetch off entirely.

On Demand

The same delta is available any time for a transaction a plan opened, via the standalone command:

stategraph tx costs --tx <tx-id>

It prints the identical Costs: block. Use it to re-check after the "preview not yet ready" hint, or to inspect a plan's cost later. Only transactions opened through stategraph tf plan or tf mtx have a preview; a tx created by hand has none.

Reading the Delta

The per-state breakdown marks each resource by how the plan changes it:

Marker Meaning
+ Added: a new resource; its full planned cost is the delta
- Removed: a destroyed resource; its cost comes off the total
~ Changed: an in-place update; the delta is the cost difference

A resource with a +0.00 delta changed in a way that does not affect its price, or is not priced at all. States the plan touches but does not change cost for are listed as no cost change.

API

The CLI wraps GET /api/v1/tx/{tx_id}/costs:

curl -H "Authorization: Bearer $STATEGRAPH_API_KEY" \
  http://localhost:8080/api/v1/tx/$TX_ID/costs
  • 200 - a tx-cost-delta: totals (each metric as current_*, planned_*, delta_*), a per-state states[] list with per-resource resources[] (each carrying a change_kind of added, removed, or changed), and by_provider / by_type / by_tag delta breakdowns.
  • 202 - { "status": "computing" }: the preview is still being computed in the background, or the transaction was applied from the console rather than stategraph tf plan. Retry shortly.
  • 404 - the transaction was aborted (aborting deletes its planned cost).
  • 401 - the caller is not a member of the transaction's tenant.
{
  "totals": {
    "currency": "USD",
    "current_monthly_cost": null,
    "planned_monthly_cost": "60.736000",
    "delta_monthly_cost": "60.736000",
    "current_resource_count": 0,
    "planned_resource_count": 1,
    "delta_resource_count": 1
  },
  "states": [
    {
      "state_id": "…",
      "state_name": "cost-preview-demo",
      "delta_monthly_cost": "60.736000",
      "resources": [
        { "address": "aws_instance.web", "type": "aws_instance", "provider": "aws",
          "change_kind": "added", "delta_monthly_cost": "60.736000" }
      ]
    }
  ]
}

Money fields are decimal strings, and null or absent when a side has nothing priced. See the API reference for the full schema.

Requirements

  • A pricing service must be configured; otherwise the plan prints no cost block.
  • The delta is computed from the plan the actuator previews, so it is available for changes planned with stategraph tf plan or tf mtx.

Next Steps