Reconcile an overnight Sume Format batch: list runs, limit and cursor

To reconcile an overnight batch on Sume, list the Format's runs with GET /v1/formats/{handle}/{slug}/runs, which returns newest first, takes limit from 1 to 100 and a cursor, and gives next_cursor and has_more for paging. There is no endpoint that lists runs across Formats, so a batch that used three Formats takes three listings.

The list call

The listing is scoped to one Format by handle and slug. Pass limit up to 100 and, for the next page, the cursor you received. A response with has_more true carries a next_cursor to send back. Runs are ordered newest first, so an overnight batch is at the top of the first page and you can stop paging once you reach runs older than the batch start.

Paging through a batch

The loop below pages one Format until has_more is false and prints each page's data. It does not parse a run row, because the run row key names are not something this page relies on; pipe the output to jq and inspect one page first.

BASE="https://api.sume.com/v1/formats/$HANDLE/$SLUG/runs"
CURSOR=""
while :; do
  URL="$BASE?limit=100"
  [ -n "$CURSOR" ] && URL="$URL&cursor=$CURSOR"
  PAGE=$(curl -sS "$URL" -H "Authorization: Bearer $SUME_API_KEY")
  echo "$PAGE" | jq '.data'
  [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break
  CURSOR=$(echo "$PAGE" | jq -r '.next_cursor')
done

What to check against the queue

Compare the listing with the queue record. A queue reports completed when every item is terminal, which does not mean every run succeeded, so read counts.failed and counts.canceled on the queue and then find those runs in the listing. A queued item that never started has run_id null and has no run to list.

A good morning routine is three steps: read the queue counts, page the run listing back to the batch start, and total usage.debited_usd_micros across the runs in the window. If the sum is far from your plan, look first at failed and canceled children, since they were billed for partial work.

Keep the queue id with the batch notes. The listing finds runs by Format, not by queue, so the queue record is what ties a run back to the batch it came from.

Page size does not change what is billed; the listing is a read call.

• Order is newest first, so start paging from the top.
• Page with a fixed limit of 100 to keep the number of calls low.
• Use the debited figure, not the billable one, for the wallet.