Get Cost Entry AI Allocation Batch
GET/api/cost-entries/:costEntry/ai-allocation/:batch
Returns one AI allocation batch of the cost entry with all of its proposals and summary figures. Use it to poll a batch you started, or to read an older batch.
purchase-orders:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Batch fields: id, cost_entry_id, status (pending, running, completed, failed, cancelled), is_stale (true when the entry's source lines or their allocations changed since the batch was proposed; a stale batch cannot be edited or confirmed), input_hash (64-character fingerprint of the source lines the proposals were made from; send it back on confirm), provider and model (the AI provider and model used, null when every line was resolved without the model), error (why a failed batch failed), tracked_job_log_id, requested_by (user ID), created_at, updated_at, summary and proposals.
summary: ready_count/ready_total (proposals ready to confirm), held_count/held_total (lines AI could not place), needs_look_count (ready proposals with confidence below 70), high_count (ready proposals with confidence 85 and up), accepted_count/accepted_total (proposals already confirmed) and last_decided_at.
Each proposal: id, batch_id, cost_entry_source_line_id, status (pending, ready, held, failed, accepted, rejected, stale), amount, confidence (0–100, derived from the evidence, null for a held line or a product chosen by a person), band (high 85+, check 70–84, low below 70, or null), hold_code and hold_label (why a held line was not placed: not_yet_created, not_stocked, account_fee, no_match, no_period, no_detail), reason, evidence (list of strings), method and method_label (how the product was found: source_product, exact_sku, sku_ignoring_case, purchase_order, returns, history, model, manual), split_of (when one line is split across several products, the number of products it is split across), target and original_target ({type, id, sku, name, url}; original_target keeps the AI's pick after a person changes it), edited, decided_by, decided_at and source_line (the line's id, line_number, external_reference, description, charge_group, charge_type, amount, period_start, period_end, basis, basis_label, basis_note, basis_as_of, snapshot_after_period, origin_label).
404 when the batch does not exist or belongs to another cost entry.
Required permission: cost_entries.ai_allocate (Allocate with AI).
Authentication: Requires Bearer token (scope purchase-orders:read).
Request
Responses
- 200
- 401
- 403
- 404
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.