Wallet

Balance

GET https://api.usegoro.ai/v1/wallet/balance

curl https://api.usegoro.ai/v1/wallet/balance \
  -H "Authorization: Bearer $GORO_API_KEY"

{
  "plan": "build",
  "balance_micro": 4250000,
  "promo_micro": 18400000,
  "included_remaining_micro": 18400000,
  "available_micro": 22650000,
  "balance_usd": "$4.25",
  "promo_usd": "$18.40",
  "included_remaining_usd": "$18.40",
  "available_usd": "$22.65",
  "renews_at": "2026-10-02T09:14:07.000Z"
}

Field	Type	Notes
`plan`	string	`free`, `build` or `scale`. `free` means the workspace has never subscribed, or its plan has ended
`balance_micro`, `balance_usd`	integer, string	Cash you topped up. Never expires
`promo_micro`, `promo_usd`	integer, string	Credit that expires: included plan credit while you are on a plan, or promotional credit Goro has granted by hand otherwise. Reads zero once expired
`included_remaining_micro`, `included_remaining_usd`	integer, string	The unexpired included credit from the current plan period. Zero on a workspace with no plan
`available_micro`, `available_usd`	integer, string	Cash plus unexpired included or promo credit. What you can spend right now
`renews_at`	string or null	ISO 8601. When the plan renews and a fresh cycle of included credit lands. `null` on the Free plan
`plan_name`	string	`Free`, `Build` or `Scale`, for display
`plan_ending`	boolean	`true` when the plan is cancelled and `renews_at` is the date it ends instead of renews
`top_up_url`, `billing_url`	string	The same address: the Billing page, where a plan or one-time credit can be added. `top_up_url` is the historical name and stays

available_micro is the number to check before a run. Anything currently held by an in-flight run has already left balance_micro, so the available figure never double-counts a run you have not settled yet. A workspace with plan: "free" cannot run tools. It keeps its wallet, including any cash or promotional credit sitting on it, but POST /v1/run and POST /v1/uploads answer 402 subscription_required until it subscribes. Reading the balance, discover and inspect all work regardless of plan. Promotional credit is spent before cash, and it expires. Goro grants it by hand, for support or goodwill, rather than automatically at signup. An expired promo drops out of the balance automatically. Promotional credit and included plan credit share the same expiring bucket: on a plan, included_remaining_micro is the period’s included credit, it is spent before cash in the same way, and it expires at the end of the period rather than rolling over. The next cycle lands at renews_at. This is also the fastest check an agent can make after a 402 insufficient_funds: it tells you exactly how much is there so you can tell a human what to top up, or when the plan’s included credit comes back.

Activities

GET https://api.usegoro.ai/v1/wallet/activities

The append-only ledger, newest first. Every movement of money is a row here, and nothing is ever edited or deleted.

Parameter	Type	Notes
`limit`	integer	Default 20, maximum 100
`cursor`	string	`next_cursor` from the previous page

curl "https://api.usegoro.ai/v1/wallet/activities?limit=3" \
  -H "Authorization: Bearer $GORO_API_KEY"

{
  "items": [
    {
      "id": 4417,
      "kind": "hold_release",
      "amount_micro": 34500,
      "amount_usd": "$0.0345",
      "balance_after_micro": 4250000,
      "balance_after_usd": "$4.25",
      "run_id": "8c3a1f42-2d7b-4a15-9f0e-6b2c8d5e7a91",
      "stripe_ref": null,
      "note": null,
      "created_at": "2026-07-30T11:04:29.150Z"
    },
    {
      "id": 4416,
      "kind": "debit_capture",
      "amount_micro": 10500,
      "amount_usd": "$0.0105",
      "balance_after_micro": 4215500,
      "balance_after_usd": "$4.2155",
      "run_id": "8c3a1f42-2d7b-4a15-9f0e-6b2c8d5e7a91",
      "stripe_ref": null,
      "note": null,
      "created_at": "2026-07-30T11:04:29.148Z"
    }
  ],
  "next_cursor": "eyJpZCI6NDQxNn0"
}

Field	Type	Notes
`id`	integer	Ledger sequence number. Higher is newer
`kind`	string	See the table below
`amount_micro`, `amount_usd`	integer, string	The size of this entry, unsigned
`balance_after_micro`, `balance_after_usd`	integer, string	Wallet balance after this entry
`run_id`	string or null	The run this entry belongs to, for run entries
`stripe_ref`	string or null	The Stripe reference: the payment for a top-up or refund, the invoice id for plan credit
`note`	string or null	Free text, when there is any
`created_at`	string	ISO 8601

Entry kinds

`kind`	What it means
`credit`	A top-up landed
`promo`	Promotional credit was granted
`plan_credit`	One billing cycle of included plan credit landed. `stripe_ref` is the Stripe invoice id
`debit_hold`	A run reserved funds. The full amount leaves the balance here
`debit_capture`	A run was charged. Records what the run actually cost
`hold_release`	The unused part of a hold came back
`refund`	Money was returned to you

Do not sum these as signed amounts. debit_hold is what leaves the balance when a run starts; debit_capture records the charge but does not itself move the balance again, and hold_release returns the unused remainder. Treating hold and capture as two separate debits double-counts every run. Read balance_after_micro on each row instead of deriving a running total.

A completed run leaves three rows: one debit_hold, one debit_capture for the actual cost, and one hold_release for the difference. A run that failed, timed out or was stopped leaves a debit_hold and a hold_release for the whole amount, and no capture.

Errors

Status	`code`	When
400	`validation_error`	`limit` is not a positive integer, or the cursor is not one Goro issued
401	`unauthorized`	Missing or invalid API key

How pricing works

Rates, totals and ceilings, in plain terms.

Guide

CLI reference

API reference

Tools

Balance

Activities

Entry kinds

Errors

How pricing works

​Balance

​Activities

​Entry kinds

​Errors

How pricing works

Balance

Activities

Entry kinds

Errors