Cost & budgets

Every pipeline attempt records its USD cost, and the rollups climb the tree: attempt → subtask → task (phase) → project. Budgets hang off the same tree — a project-level hard cap, optional per-phase and per-step caps from the workflow — and the runner enforces them before dispatching new work.

Project cost fields

On every project object:

Field	What it is
`cost_total_usd`	Running spend, updated as attempts complete.
`cost_budget_usd`	Optional hard cap (USD decimal). `null` = uncapped.
`cost_warning_threshold`	Soft-warning fraction of the budget. Default `0.80`.
`cost_burst_per_minute_usd`	Optional burn-rate guard.

Set the budget at create time (cost_budget_usd in the create body) or later via PATCH /v1/projects/{id} — the HTTP twin of the runtime's pipeline_set_budget tool. Tasks and subtasks carry their own cost_budget_usd / cost_total_usd pair when the workflow declares per-phase or per-step caps.

What happens at the thresholds

Soft (warning) threshold — when spend crosses cost_warning_threshold × budget, a cost_threshold_warning event lands in the project timeline. The portal's budget bar turns amber.
Hard cap — the runner checks the budget before dispatching each step (and re-checks after each attempt's cost lands). On breach it emits cost_budget_breached and pauses the project — work in flight isn't killed, but nothing new starts. The portal's budget bar turns red.

Recovery is deliberate: raise (or clear) the budget via the project Edit sheet or PATCH, then Resume.

The cost endpoint

GET /v1/projects/{project_id}/cost

{
  "project_id": "sustainable-urban-farming-explainer-3f9a1c2b",
  "total_usd": "1.8421",
  "budget_usd": "5.00",
  "budget_burn": 0.37,
  "tasks": [
    { "task_id": "…", "phase_slug": "research", "task_kind": "regular",
      "budget_usd": null, "spent_usd": "0.4210" }
  ]
}

budget_burn is total / budget (0.0 when uncapped). The tasks array is the per-phase breakdown the portal's stat card and the tasks table draw from. All amounts are USD decimal strings — Catentio pipeline costs are never denominated in IDR.

Pre-flight estimates

Backtrack operations estimate before they spend: retrigger responses include cost_estimate_usd derived from historical per-template cost stats, and edit-session plans carry cost/risk in the plan you approve.

Workspace-level cost

Cross-project rollups (today / week / month / all-time totals, top projects, daily series) live at Dashboard → Cost and GET /v1/cost/summary — see API resources.