calculations_batch_calculate - ARCNM

Create + enqueue one calculation per revision in a single request, grouped under a CalculationBatch — the path an agent triggers when a market signal (a material price move) makes a batch re-cost worth running. Each run is metered on success against the org's subscription (v5/v6 quota + flat overage), exactly like a single /run — there is no separate per-call wallet draw. Free orgs over their included quota are rejected up front (HTTP 402).

Selection is explicit (part_revision_ids) for now; richer criteria (by material category, above-should-cost, …) layer on top of this path later.

Name	Required	Description	Default
`engine`	No		arcnm
`region`	No
`engines`	No	Engines to run per revision. Today a single engine is honoured and any other value is coerced to it. The list shape is preserved for forward-compat with future engines.
`currency`	No
`language`	No		de
`lot_size`	No
`batch_name`	No
`material_ref`	No	Free-form material reference (URN, Werkstoffnummer, AISI/SAE code, trade name, or your SKU); resolved to a material grade for every calculation in the batch. Unresolvable values are rejected with 422 material_unresolved plus ranked candidates. Omit to price the material read from each part's drawing (or the environment default).
`nest_item_id`	No	Price this calculation's material on its part's line of a job nest — the `id` of a line (`items[].id`) of a job nest that has solved it. The material is then the line's share of the sheets the job nest cut it from together with other parts, less its share of what their skeleton and reusable rests earn back; everything else is priced as usual. The line must be of your organization, of this costing environment and of this part revision, and its job nest must have solved it; otherwise the request is rejected with 422 `nest_item_unresolved`, `details.reason` saying why. It cannot be combined with `stock_format_id` or with customer-supplied material. An upload creates a new part revision, so the upload forms reject every line. A line of the sheets an assembly shares among its own components prices that assembly only: naming one is rejected as `not_found`, and a re-run of such a component prices it on its own sheet. Omit it to price the part on its own sheet.
`annual_volume`	No
`stock_format_id`	No	Price this calculation on one stock format — the `id` of a format from `GET /stock-formats`. An id names the format, not only the version it came from: when the format has been changed since, the version current on the day the calculation is created is used. An id your organization cannot price with today (unknown, retired or hidden) is rejected with 422 `stock_format_unresolved`. When the part cannot be cut from that format — too small, not bought in the part's thickness or material, or one the machine cannot load — or is not cut from sheet at all (milled, turned or bought finished), the calculation is priced as if none had been chosen, and `analytics.pipeline_notes` says why (`stock_format_pin_unavailable`). Omit it to price on the format that uses the least material per part.
`material_grade_id`	No
`part_revision_ids`	Yes
`surface_treatments`	No	Deprecated. Surface treatments (e.g. anodizing, zinc plating) do not set the priced cost — treatments are read from the part's drawing and priced on cost_decomposition.subcontract_cost — but this field is part of a calculation's cache identity, so two otherwise-identical batch runs that differ only here are priced as distinct calculations instead of one reusing the other's result. Prefer specifying treatments on the drawing.
`provided_stock_kind`	No		none
`material_is_provided`	No
`raw_material_strategy`	No	Deprecated. The raw-material strategy does not set the priced cost — the material comes from material_ref or the part's own drawing, and its price per kilogram from the costing environment's material rate — but this block is part of a calculation's cache identity, so two otherwise-identical batch runs that differ only here are priced as distinct calculations instead of one reusing the other's result. Set material_ref and the environment's material rate instead. It stays accepted on this endpoint; retiring it would be a breaking change and would ship under a new dated API version with advance notice.
`costing_environment_id`	No	Single environment to cost against. Omit together with ``costing_environment_ids`` to use the organization's baseline environment.
`costing_environment_ids`	No	Environments to cost each revision against, in comparison order. Every (revision, environment) pair becomes one calculation and counts as one against the plan quota. Mutually exclusive with ``costing_environment_id``. Duplicates are collapsed preserving first occurrence; ``revisions x environments`` may not exceed 500.

Name

Required

Description

Default

engine

arcnm

region

engines

Engines to run per revision. Today a single engine is honoured and any other value is coerced to it. The list shape is preserved for forward-compat with future engines.

currency

language

lot_size

batch_name

material_ref

Free-form material reference (URN, Werkstoffnummer, AISI/SAE code, trade name, or your SKU); resolved to a material grade for every calculation in the batch. Unresolvable values are rejected with 422 material_unresolved plus ranked candidates. Omit to price the material read from each part's drawing (or the environment default).

nest_item_id

Price this calculation's material on its part's line of a job nest — the `id` of a line (`items[].id`) of a job nest that has solved it. The material is then the line's share of the sheets the job nest cut it from together with other parts, less its share of what their skeleton and reusable rests earn back; everything else is priced as usual. The line must be of your organization, of this costing environment and of this part revision, and its job nest must have solved it; otherwise the request is rejected with 422 `nest_item_unresolved`, `details.reason` saying why. It cannot be combined with `stock_format_id` or with customer-supplied material. An upload creates a new part revision, so the upload forms reject every line. A line of the sheets an assembly shares among its own components prices that assembly only: naming one is rejected as `not_found`, and a re-run of such a component prices it on its own sheet. Omit it to price the part on its own sheet.

annual_volume

stock_format_id

Price this calculation on one stock format — the `id` of a format from `GET /stock-formats`. An id names the format, not only the version it came from: when the format has been changed since, the version current on the day the calculation is created is used. An id your organization cannot price with today (unknown, retired or hidden) is rejected with 422 `stock_format_unresolved`. When the part cannot be cut from that format — too small, not bought in the part's thickness or material, or one the machine cannot load — or is not cut from sheet at all (milled, turned or bought finished), the calculation is priced as if none had been chosen, and `analytics.pipeline_notes` says why (`stock_format_pin_unavailable`). Omit it to price on the format that uses the least material per part.

material_grade_id

part_revision_ids

Yes

surface_treatments

Deprecated. Surface treatments (e.g. anodizing, zinc plating) do not set the priced cost — treatments are read from the part's drawing and priced on cost_decomposition.subcontract_cost — but this field is part of a calculation's cache identity, so two otherwise-identical batch runs that differ only here are priced as distinct calculations instead of one reusing the other's result. Prefer specifying treatments on the drawing.

provided_stock_kind

none

material_is_provided

raw_material_strategy

Deprecated. The raw-material strategy does not set the priced cost — the material comes from material_ref or the part's own drawing, and its price per kilogram from the costing environment's material rate — but this block is part of a calculation's cache identity, so two otherwise-identical batch runs that differ only here are priced as distinct calculations instead of one reusing the other's result. Set material_ref and the environment's material rate instead. It stays accepted on this endpoint; retiring it would be a breaking change and would ship under a new dated API version with advance notice.

costing_environment_id

Single environment to cost against. Omit together with ``costing_environment_ids`` to use the organization's baseline environment.

costing_environment_ids

Environments to cost each revision against, in comparison order. Every (revision, environment) pair becomes one calculation and counts as one against the plan quota. Mutually exclusive with ``costing_environment_id``. Duplicates are collapsed preserving first occurrence; ``revisions x environments`` may not exceed 500.

ARCNM

Calculations Batch Calculate

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources