Agent Completion cost: cap, billable_amount_usd_micros, or usage?

Read three things in order. The spend cap you sent, generation_spend_cap_usd, is a ceiling and not a charge. The run receipt's usage.billable_amount_usd_micros is the generation spend of that run. GET /v1/usage remains the authoritative billing record when the two seem to disagree.

Agent Completions return the same receipt shape as schedule runs and Format runs, so the field notes in Sume's Scheduled docs apply.

The cap is required and has no default

An Agent Completion is an unattended agent with tools and access to your generation wallet. In the chat UI an interactive approval prompt protects you. A backend caller gets no prompt, so Sume makes generation_spend_cap_usd a required field. If you leave it out, the call fails with 400 invalid_request.

The cap is in dollars. The receipt echoes it in micros: a cap of 5 appears as generation_spend_cap_usd_micros: 5000000 in the docs example.

What the receipt's usage holds

On a finished run, usage is an object with currency, billable_amount_usd_micros and generation_spend_cap_usd_micros, or null when Sume could not read the spend at all. The billable amount is the generation spend of the run, and the Scheduled docs note it does not include the cost of the language-model turn itself. A null usage is not the same as zero, so do not sum nulls as zeros.

Convert micros to dollars

One million micros is one dollar. A billable amount of 1,250,000 micros is $1.25. A cap of 5,000,000 micros is $5. Keep micros as integers in your database and divide only for display; that avoids float drift when you add many runs.

curl -sS "https://api.sume.com/v1/agent-runs" \
  -H "Authorization: Bearer $SUME_API_KEY"

List runs for a review

GET /v1/agent-runs lists your completions, newest first. It needs a key with agent_completions:read; keys made before the scope existed fail with 403 insufficient_scope, and you must create a new key. Read each receipt's usage and compare the sum with GET /v1/usage for the same window.

If a run was cancelled, its status shows canceled and usage still records whatever was spent before the stop.

A weekly review in three steps

First, list the week's runs and group them by status. Second, sum usage.billable_amount_usd_micros over completed runs and count the runs whose usage is null. Third, compare the sum with the usage total for the same dates. A gap that is only the null runs is expected. A gap larger than that deserves a look at cancelled runs and at spend by other keys in the workspace.

Store the receipt id with each row. A support request about one run is quick when you can name the exact receipt.

Choose caps from rates

Work out a cap from the metered rates on the API pricing page and then add a margin for retries. A cap that is too low ends the run early with part of the work done; a cap that is too high removes the point of having one.