Explain Cost
explain_costRead-onlyIdempotent
Explain what a priced calculation costs and why, in one short structured answer. Use it first once a calculation has succeeded. Returns the unit, total and setup cost, the prediction band and confidence, the cost categories, the machine used, how many times each machine clamps the part, work the drawing asks for that is not in the price, and the top cost drivers: the cost categories with their share of the unit cost first, then the features. The drivers show what to change in the design or to challenge in a quote. For the itemised line items, use get_cost_breakdown. For the status of a calculation that is still running, use get_calculation. Read-only and free.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | How many cost drivers to list: 'concise' (the default) lists the top 3 cost categories and the top 3 features (an assembly's top 3 rows), 'detailed' the top 10. | concise |
| calculation_id | Yes | Id of a calculation, as upload_and_quote, quote_part or list_calculations return it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| error | No | Why this calculation produced no price, in one sentence, when its status is terminal (failed / cancelled). Absent while it is still running and on a priced calculation. | |
| route | No | Every machine / work centre the priced route runs on, in order — the same chain get_process_plan lists. One entry on a single-machine quote; e.g. [bandsaw, lathe] when the blank is sawn first. Empty when the calculation carries no process plan. | |
| times | No | Time per category behind the cost lines — programming, inspection, finishing, deburring, packaging, and the machine-side phases. Every line except material, tooling and outsourced work is time x rate, so this is the basis the money is struck on. Absent on a calculation that recorded no time breakdown. | |
| status | Yes | ||
| machine | No | Machine the part was priced on. | |
| coverage | No | Present only when status is 'blocked': the calculation was created but not run because the organization has no included calculations left, has reached its monthly overage cap, or has its billing paused. Carries {reason, message, remaining, used, included, tier_slug, window}: 'reason' says which, 'message' states it in a sentence. The part is saved; a later calculation of it runs once the block is lifted. Never a 402. | |
| currency | No | The calculation's currency. EVERY money figure on this result is stated in it — unit_cost, offer_price, total_cost, setup_cost, the band, every cost_breakdown line and every driver. | |
| guidance | Yes | What to do next to act on or reduce the cost. | |
| lot_size | No | ||
| material | No | Material, when known. | |
| unpriced | No | Work the drawing requires that no machine in this environment can do, so it is not in the price. Each entry names the process and why. Absent when the route covers what the drawing asks for. | |
| clampings | No | How many times each machine on the route clamps the part, in route order — the same count the route was costed on. Absent when the route did not state a count. | |
| cost_band | No | [low, high] prediction band for the unit cost. | |
| unit_cost | No | Unit cost per part: direct cost plus overhead_var and overhead_fixed. Where the costing environment states no Material-/Fertigungsgemeinkosten, overhead_var is the flat variable overhead the environment states (none by default); once it states them, those overheads sit above unit_cost as cost-sheet rungs, with administration and selling, margin and the other surcharges. Not the price to quote: that is offer_price, equal to unit_cost only where no surcharges are stated. | |
| confidence | No | Quote-trust signal: calibrated to the shop, or a model estimate — read together with the prediction band. | |
| setup_cost | No | One-time setup cost of the lot, on the same basis as unit_cost (below the cost-sheet rungs). | |
| total_cost | No | unit_cost for the whole lot (unit_cost x lot_size), on the same basis as unit_cost; the lot at the offer price is offer_price x lot_size. | |
| offer_price | No | The offer price per unit — unit_cost plus the cost-sheet surcharges the costing environment states (scrap, overheads, administration and selling, freight, duty, mark-up). Equal to unit_cost when no sheet is stated; this is the figure the tenant's cost sheet and the calculation's own analytics headline as the price. This is the authoritative price: quote from it, not from cost_breakdown.angebotspreis, which is the cost sheet's own total and can differ from it. Absent on older calculations. | |
| top_drivers | No | What drives the cost, largest first. On a part: the cost categories first (setup, subcontract, material, machine …), each with its cost and its share of unit_cost, and an 'other' row with the categories not listed, so these rows add up to unit_cost; then the features (pocket, hole, slot), which split the run-time categories (machine, labour, finishing) and so are part of those rows, never added to them. A part with no machined features (a flat pattern) lists the categories alone; one priced before the cost sheet existed, the features alone. On an assembly: its components and its own joining. The top 3 categories and the top 3 features (an assembly's top 3 rows), or 10 with detail 'detailed'. | |
| unit_time_s | No | Total time per unit in seconds, every work system: the machine run, the finishing pass and the bench work (deburring, packaging) under the allowance, plus the per-unit shares of programming and inspection. Excludes the lot setup (setup_time_s). | |
| cycle_time_s | No | Machining cycle time per unit, in seconds. | |
| needs_review | No | ||
| setup_time_s | No | One-time setup time for the whole lot, in seconds (NOT per unit; divide by the lot size for the per-unit share). Time and cost side by side, for quoting / scheduling / capacity planning. | |
| material_note | No | Plain-language material assumption (which grade was priced, or that a default was used). | |
| calculation_id | Yes | ||
| cost_breakdown | No | Cost figures per unit, keyed by line, all in `currency` (the calculation's currency — the same basis as unit_cost and offer_price, so the lines add up to the headline). The LINES that sum to unit_cost are material_cost, machine_cost, labour_cost, programming_cost, tooling_cost, finishing_cost, inspection_cost, subcontract_cost, overhead_var and overhead_fixed. Six keys RESTATE money already inside those lines and must not be added again: machine_setup_cost and labour_setup_cost are the setup shares machine_cost and labour_cost already include (the tenant's cost sheet shows the same money as a separate 'setup' row and correspondingly smaller machine and labour rows); transfer_cost is the inter-machine hand-off charge on a composed route, which is priced inside overhead_fixed; and material_purchased_cost and remnant_credit derive material_cost, which is material_purchased_cost minus remnant_credit — the stock bought, less what its reusable remnant is worth back in stock (0 unless the costing environment credits remnants). scrap_credit is what the scrap fetches (0 unless the environment credits scrap): a cost-sheet rung SUBTRACTED inside herstellkosten, before scrap_cost and material_overhead are struck on the net material. direct_unit_cost, herstellkosten, selbstkosten, barverkaufspreis and zielverkaufspreis are SUBTOTALS; angebotspreis is the cost sheet's own offer-price total — offer_price is the authoritative price and the one to quote from, and the two can differ; scrap_cost, material_overhead, production_overhead, sga_cost, packaging_cost, freight_cost, duty_cost, margin (the profit mark-up on selbstkosten), cash_discount, sales_commission and customer_discount are the cost-sheet rungs between unit_cost and offer_price. cost_categories holds the sheet's buckets as the page shows them (setup separate); for the itemised sheet with the tiers beneath each line use get_cost_breakdown. | |
| machine_time_s | No | Machine time per unit in seconds: the billed run plus the finishing pass, under the allowance — the time one piece occupies the machine, and the t_e the product's cost sheet states. | |
| review_reasons | No | ||
| cost_categories | No | The cost sheet's own buckets per unit (material, setup, machine, labour, programming, tooling, finishing, overheads …) in the quote's currency — exactly the lines the product shows, setup as its own line. On an assembly: its roll-up terms (components_cost, joining_cost, …) and the cost-sheet rungs above them, the same map get_cost_breakdown states, adding up to offer_price. Absent on calculations priced before the sheet existed. | |
| drawing_pairing | No | Whether the drawing sent with this calculation describes its model: {status (matched | suspect | mismatched | unverified), drawing_excluded, checks[{name, status}]}. When drawing_excluded is true the drawing describes another part and was left out — the price is the model's alone. Absent when no drawing was paired. | |
| material_priced | No | The material this calculation was priced as, by its short name — the environment's default material when material_resolved is false. On an assembly whose components name their own materials, each one, comma-separated. | |
| material_source | No | Where material_priced came from: 'request', 'drawing_title_block' (the part's drawing), 'step_material_property' (the material its STEP file names), 'assembly_parts_list' (the assembly drawing's parts-list row naming the component), 'assembly_drawing_title_block', 'assembly_parts_list_dominant' (the grade most of that list's made rows name, inferred for a component no row names) or 'environment_default'. The first that names a material wins, in that order: request, drawing, parts-list row, assembly drawing or dominant grade, STEP file, environment default. | |
| material_resolved | No | False when no material grade resolved and the part was priced on the environment's default — set material_ref and re-run to correct. | |
| selection_failure | No | The same refusal as data when no machine in the costing environment could make the part: the requirement that stopped it, the machine that came closest with its measured values, and how much of the fleet shares the blocker. Absent unless that is why it failed. | |
| price_completeness | No | 'partial' when `unpriced` lists work the price leaves out — then unit_cost is a LOWER BOUND for the drawing, not a price for it; 'complete' when the price covers everything. Absent on a calculation from before the contract and on one without a price. | |
| assembly_completeness | No | ASSEMBLIES ONLY. Whether `unit_cost` is a price or a LOWER BOUND. Carries {n_unique, n_priced, n_pending, n_unpriced, n_excluded, n_partial, total_is_lower_bound, priced_complete, unpriced[], partial[], unpriced_steps[]}, where each unpriced entry has a closed-enum `reason_code`, a `by_design` flag and, where one exists, a `remedy`. `priced_complete` and `total_is_lower_bound` cover the COMPONENTS only (the BOM rows counted in n_unique): `priced_complete` is true when every component priced, and when `total_is_lower_bound` is true a component is missing, so `unit_cost` is a lower bound, not a complete price. `unpriced_steps` lists the assembly's own route steps that carry no price, with their reason, worded as get_process_plan words them (e.g. 'Straightening — unpriced (straightening_shop_specific)'); they are not in `unit_cost` whatever the two flags say. A `by_design` reason (a part budget, a plan quota, a cancellation) is a configured limit, not a processing error. | |
| costing_environment_id | No | The costing environment this was priced in: the machines, rates and overheads behind these numbers (list_environments names it). | |
| inputs_changed_since_run | No | Null when this price reflects every input on its part revision. Otherwise {roles, corrections, latest_at}: files attached and corrections applied to the part after the run read its inputs, which a new calculation reads and this one did not. | |
| environment_changed_since_run | No | Null when this price was computed on its costing environment as it stands. Otherwise {latest_at}: the environment was edited after the run read it, and a new calculation prices with the current setup while this result does not. |