list_runs
Read-only
Every call this account was charged for, newest first. Free read.
Recover a lost response in two calls, never re-charged: list_runs(request_id=...)
for the receipt, then follow `hooks_url` for the hooks it produced. Page with
`cursor` (one pass total) or `offset`; stop only when `exhausted` is true, never
on a short page. Same composed read GET /v1/runs makes, so the two can never
disagree. Errors: unauthorized, invalid_request, rate_limited.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max runs to return, 1-200. Above the ceiling is an invalid_request, never a silent truncation. | |
| cursor | No | Ledger position to resume scanning from (see `next_cursor` on a prior page); not a run count, not an opaque token. Leave at 0 and follow `next_cursor` to walk your whole history in bounded reads. | |
| offset | No | Number of rows to skip for paging, 0-9223372036854775807. Page with offset += the limit you actually requested; `total` in the response is the unpaged count. The ceiling is SQLite's largest bindable integer: above it the read could only ever have been a 500, so it is a typed invalid_request instead. | |
| api_key | No | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (the stdio default). No key resolvable -> unauthorized. | |
| operation | No | Return only runs of this operation: generate_hooks, generate_hooks_batch, remix_hook, score_hook, score_hooks_batch, add_credits. An unknown value returns an empty page, never an error. | |
| request_id | No | Return only the run with this X-Request-Id (the response header on every call, including errors). This is the lookup for a lost response whose id you still have. | |
| charged_only | No | true (default): only calls that COST credits. false: also include grants and zero-cost calls. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runs | No | This page: {request_id, operation, created_at, credits_delta, credits_charged, balance_after, key_prefix, topic, topics, platform, mode, hooks_returned, tags, hooks_url, usage_url, metadata}. hooks_url is set only for a hook-producing operation and follows the SAME id. | |
| limit | No | Page size actually applied. | |
| total | No | Rows matching the filters WITHIN the scanned window (see `scanned`), not over all history unless `exhausted` is also true. | |
| offset | No | Offset this page started at. | |
| scanned | No | Ledger rows examined to build this page. | |
| has_more | No | true when this page is not the whole remainder. Follow `next_cursor` (preferred) or `next_offset`; never infer 'that was all' from a short page. | |
| exhausted | No | true only when the read reached the END of your ledger. `total` is the COMPLETE count only when this is true. | |
| scan_limit | No | Ledger rows one page may examine, however many reads that takes. | |
| next_cursor | No | Pass as `cursor` for the next page (leave offset at 0); null when nothing follows. PREFER this over next_offset for a full walk: it resumes exactly where this page stopped instead of re-scanning from the newest row. | |
| next_offset | No | Pass as `offset` for the next page; null when nothing follows. | |
| credits_remaining | No | Your balance right now. |