Skip to main content

Get Latest Cost Entry AI Allocation

GET 

/api/cost-entries/:costEntry/ai-allocation

Returns the cost entry's most recent AI allocation batch with all of its proposals, plus whether AI allocation can run for the calling user.

Required scope: purchase-orders:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Response: data is the batch, or null when AI allocation has never been run on the entry. availability is {available, message, code}; when available is false, message explains why and code is ai_disabled, ai_not_permitted or ai_scope_blocked. Checking availability never counts against the workspace's AI request limit.

Poll this endpoint (or Get Cost Entry AI Allocation Batch) after starting a batch until data.status is completed or failed.

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 cost entry does not exist.

Required permission: cost_entries.ai_allocate (Allocate with AI).

Authentication: Requires Bearer token (scope purchase-orders:read).

Request​

Responses​

OK

Response Headers
    Content-Type