---
title: "Runs and their wallets"
method: GET
path: "/v1/runs"
tags: ["Effects"]
---

# Runs and their wallets

`GET /v1/runs`

## Request

- Base URL: `https://ratchetgate.com`
- URL: `https://ratchetgate.com/v1/runs`
- Auth: HTTP bearer

Every run seen in the window, whether or not a wallet was opened for it. Runs with no ceiling are included deliberately: the job quietly spending with nothing bounding it is the row you came here to find, and a list filtered to budgeted runs would never show it. Where a wallet exists, spend is what the gate counted and enforced against; where none does, it is summed from what callers declared. spend_source says which, because those are not the same kind of number.

## Query parameters

- `days` integer
- `limit` integer

## Response `200`

Default Response

- object
  - `runs` object[]
    - `run_id` string
    - `limit_micros` integer, nullable: Null when no wallet was opened — an unbudgeted run is not capped.
    - `spent_micros` integer
    - `remaining_micros` integer, nullable
    - `exhausted` boolean
    - `spend_source` 'wallet' | 'declared': "wallet" is what the gate counted and enforced against. "declared" is summed from what callers declared on an unbudgeted run — an estimate, not a ledger.
    - `declared_micros` integer: Everything declared on this run in the window. Reported alongside spent, not instead of it: a ceiling opened part-way through a run starts its ledger at zero, so spent alone would read as "plenty of room" on a run that has already spent heavily.
    - `effects` integer
    - `last_activity_at` string, date-time, nullable
    - `agent_ids` string[]

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Insufficient prepaid credit.
- `403`: Scope, policy, or budget refusal.
- `404`: Not found.
- `409`: Conflicting state or idempotency-key reuse.
- `413`: Payload too large.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ratchetgate/apis/ratchet-api.md) · [All operations](https://skmtc.dev/ratchetgate/apis/ratchet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ratchetgate/apis/ratchet-api/revisions/5712f33c692f?raw)