wallet.ledger.list

Where the video time went

GET/wallet/ledger

Operation: wallet.ledger.list
MCP tool: wallet_ledger_list

Every movement of this account's seconds, newest first: grants, reservations, charges and releases, each with the row it was for. Joined to a render or an export by refType + refId; the ledger is the record of what was spent, and no other count of seconds is authoritative.

curl 'https://api.gogoscreen.com/api/v1/wallet/ledger?limit=2' \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY"

A request to this operation.

json

{
  "data": [
    {
      "kind": "release",
      "seconds": 300,
      "bucket": "payg",
      "refType": "render",
      "refId": "3f2b0c1a-9d4e-4a61-b8c2-000000000003",
      "note": "returned unspent",
      "balanceAfter": {
        "planId": null,
        "planActive": false,
        "freeSeconds": 0,
        "paygSeconds": 542,
        "planSeconds": 0,
        "planExpiresAt": null,
        "reservedSeconds": 0,
        "availableSeconds": 542
      },
      "createdAt": "2026-09-21T11:01:00.000Z",
      "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000004"
    },
    {
      "kind": "reserve",
      "seconds": 300,
      "bucket": "reserved",
      "refType": "render",
      "refId": "3f2b0c1a-9d4e-4a61-b8c2-000000000003",
      "note": "held 300s (0 plan, 300 payg, 0 free)",
      "balanceAfter": {
        "planId": null,
        "planActive": false,
        "freeSeconds": 0,
        "paygSeconds": 242,
        "planSeconds": 0,
        "planExpiresAt": null,
        "reservedSeconds": 300,
        "availableSeconds": 242
      },
      "createdAt": "2026-09-21T11:02:00.000Z",
      "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000005"
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0wOS0yMVQxMTowMjowMC4wMDBaIiwiaSI6IjNmMmIwYzFhLTlkNGUtNGE2MS1iOGMyLTAwMDAwMDAwMDAwNSJ9"
}

200 response, captured from a real call. Ids, timestamps and signed URLs are replaced; the shape is untouched.

At a glance

Fact	Detail
Scopes	`wallet:read`
Credentials	a signed in dashboard session or an API key.
Rate limit	600 requests a minute per credential, in the `read` class.
Idempotency	Not applicable. This operation changes nothing.
MCP tool	`wallet_ledger_list`
Always sets	`Cache-Control: private, no-store`

Query parameters

Name	Type	Required	Description
limit	integer	Optional	How many rows to return (1–100).Default `20`1–100
cursor	string	Optional	The `nextCursor` of the previous page. Opaque: do not build one.max 512 characters

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

Where the video time went

Name Type Description

data object[]

9 fields inside data

Name	Type	Description
balanceAfter	object \| null	The whole wallet as it stood after this row, so a statement reads down the page without re-summing.any keys
bucket	string \| null
createdAt	string	format: date-time
id	string \| number
kind	string	What happened: a grant, a reservation, a charge, a release, an expiry.
note	string \| null
refId	string \| null
refType	string \| null	What the row is about — `render`, `marketing_export` — and `refId` is that row's id.
seconds	number	Signed: negative took time away.

nextCursor string | null Pass as cursor for the next page; null on the last page.

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
invalid_cursor	400	The `cursor` query parameter was not one this API minted, or it was edited, or it is older than a hundred years either way.	Drop the cursor and start the walk from the first page. Pass back exactly the `nextCursor` string you were given and never build one by hand.
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.