Export API usage to CSV: turning Sume's usage ledger into rows

The Sume docs list no CSV export, in the dashboard or the API. What they do list is GET /v1/usage, which returns your workspace's usage ledger as JSON, newest rows first. Turn that JSON into CSV yourself, and keep the refunded rows out of any total.

This comes from the Usage dashboard and Billing and credits pages and the Sume API reference, read 2026-09-29. Exact schemas live in the reference.

How do I get the usage rows out?

Call GET /v1/usage with your key. The limit parameter takes 1 to 100 and returns that many of the newest rows. The rows sit under data.usage. The script below writes a header once, then appends one line per row.

echo 'id,job_id,operation_type,status,billable_amount_usd_micros,created_at' > usage.csv

curl -sS "https://api.sume.com/v1/usage?limit=100" \
  -H "Authorization: Bearer $SUME_API_KEY" \
| jq -r '.data.usage[]
    | [.id, .job_id, .operation_type, .status,
       .billable_amount_usd_micros, .created_at]
    | @csv' >> usage.csv

Why does the list stop at 100 rows?

The plain usage list is capped at 100 newest rows a call, and the reference shows no cursor parameter for it. The job list is different: it has a starting_after cursor. So a usage export is a scheduled snapshot, not a one-time history dump. Run it often enough that fewer than 100 new rows arrive between runs, then de-duplicate on the row id when you merge files.

The docs do not say how far back the ledger goes. Check a real response for your workspace before you plan an audit window around it.

Which rows count as spend?

Only captured rows. The three statuses are in the table. The usage page warns against summing rows yourself: a refunded row keeps its hold amount in billable_amount_usd_micros, so a naive sum of the column overstates spend. In the CSV, keep the status column and filter to captured before you total anything.

How do I get the total for one run or job?

Skip the spreadsheet math. Add run_id, job_id or thread_id to the call and the response adds a summary folded over every ledger row that scope caused. debited_usd_micros and debited_usd are what the wallet deducted, and the page calls that the figure to quote.

curl -sS "https://api.sume.com/v1/usage?run_id=arun_demo&limit=50" \
  -H "Authorization: Bearer $SUME_API_KEY"

What unit is billable_amount_usd_micros?

USD micros, meaning millionths of a dollar. The response also carries billable_amount_usd_cents, and balance is USD-denominated; the cent and credit_amount fields are rounded compatibility values. Convert micros yourself and keep the micros column if you reconcile against an invoice. The job_id and request_id columns join each row back to a job, as in the job-recovery post.

Top-ups are dashboard operations. The public API exposes balance and usage reads, not a top-up call, though top-up activity can appear in the ledger. For rates, see API pricing. For what one run cost, see the per-run cost post.