# tokenAccounts

query · in the family [Token account](/reference/token-account/)

## What it does

The token account list — each entry is your group’s kernel wallet — the prepaid balance that pays for platform usage.

The caller's org-group family's ACTIVE LISTING of TokenAccounts — doomed records DROP from listings. PAGINATED: `limit` clamps to \[1, 200], default 100; `nextToken` = the prior page's cursor, verbatim — opaque + tenant-bound (a malformed or foreign token → VALIDATION/INVALID). Walk until `nextToken` is null (a page may hold fewer than `limit` — doomed drop per page). STRUCTURED FILTER + SORT: `filter` = AND across clauses, OR within a clause's values; `sort` = one declared field, asc/desc. The declared TokenAccount roster: `caption` (text) · `status` (enum) · `createdAt` (date) · `updatedAt` (date). An illegal filter/sort refuses VALIDATION/INVALID NAMING the exact problem (an unknown field teaches the roster). A filtered/sorted read evaluates the WHOLE family server-side, returns the EXACT `matchCount`, and its `nextToken` binds to THE ONE filter+sort that minted it — replaying it under a different filter/sort refuses. Absent both, the unfiltered lane is unchanged (`matchCount` null).

## What happens

Reads only — changes nothing.

## Who may call it

Capability area: **Billing and the wallet** — Your platform bill, token purchases and the usage and cost reads.

- Owner
- Manager
- Associate Manager
- An API key whose scope allows `api:tokenAccounts`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `filter` | [FilterInput](/types/FilterInput/) | no | Which records to answer — clauses over the family’s filterable fields (the FilterInput type and the paging guide carry the grammar). |
| `sort` | [SortInput](/types/SortInput/) | no | The order to answer in — one declared field and a direction (the SortInput type carries the grammar). |
| `limit` | [Int](/types/#scalars) | no | How many records to answer at most; a page may hold fewer. |
| `nextToken` | [String](/types/#scalars) | no | The cursor from the previous page, passed back exactly as received. |

## Returns

[TokenAccountPage](/types/TokenAccountPage/) `TokenAccountPage!` — One page of the tokenAccounts listing — the records + the opaque resume cursor.

This is a page: `items` holds the records and `nextToken` the cursor for the next page — pass it back verbatim until it is null. See [paging](/guides/paging-and-the-cursor-grammar/).

## Example request

```graphql
query ExampleTokenAccounts($filter: FilterInput) {
  tokenAccounts(filter: $filter) {
    items {
      id
      sysId
      type
      caption
      status
      parentId
      rootId
      createdAt
      updatedAt
      revisionNum
      revision
      balance
      lowBalanceThreshold
      dailyBurnThresholdKernels
      autoTopOffMonth
      autoTopOffSpentUsdCents
      autoTopOffDay
      autoTopOffSpentDayUsdCents
      autoTopOffPendingMethod
      autoTopOffPrimaryFailedDay
      autoTopOffBackupFailedDay
      burn7dKernels
      runwayDays
      microTokenCarry
      lowBalanceSince
      autoTopOffPendingPurchaseId
      topOffCappedSince
      baseFeePaidMonth
      includedMonth
      includedGranted
      includedRemaining
      affiliateCreditCents
      frozenKernels
      storageSnapshotDay
      currency
    }
    nextToken
    matchCount
  }
}
```

Variables:

```json
{
  "filter": {
    "clauses": [
      {
        "field": "caption",
        "op": "contains",
        "values": [
          "Blue"
        ]
      }
    ]
  }
}
```

## Example response

```json
{
  "data": {
    "tokenAccounts": {
      "items": [
        {
          "id": "01900000-0000-7000-8000-37386ae00000",
          "sysId": "TA-EXMP-0000-000F",
          "type": "TokenAccount",
          "caption": "Blue jeans",
          "status": "active",
          "parentId": "01900000-0000-7000-8000-065235280000",
          "rootId": "01900000-0000-7000-8000-a093dd800000",
          "createdAt": "2027-01-31T00:00:00.000Z",
          "updatedAt": "2027-01-31T00:00:00.000Z",
          "revisionNum": 1,
          "revision": "01900000-0000-7000-8000-b7960e180000",
          "balance": 1,
          "lowBalanceThreshold": 1,
          "dailyBurnThresholdKernels": 1,
          "autoTopOffMonth": "<auto top off month>",
          "autoTopOffSpentUsdCents": 1,
          "autoTopOffDay": "2027-01-31",
          "autoTopOffSpentDayUsdCents": 1,
          "autoTopOffPendingMethod": "<auto top off pending method>",
          "autoTopOffPrimaryFailedDay": "2027-01-31",
          "autoTopOffBackupFailedDay": "2027-01-31",
          "burn7dKernels": 1,
          "runwayDays": 1.5,
          "microTokenCarry": 1,
          "lowBalanceSince": "<low balance since>",
          "autoTopOffPendingPurchaseId": "01900000-0000-7000-8000-80a20c5b0000",
          "topOffCappedSince": "<top off capped since>",
          "baseFeePaidMonth": "<base fee paid month>",
          "includedMonth": "<included month>",
          "includedGranted": 1,
          "includedRemaining": 1,
          "affiliateCreditCents": 1,
          "frozenKernels": 1,
          "storageSnapshotDay": "2027-01-31",
          "currency": "USD"
        }
      ],
      "nextToken": "<the cursor from the previous page>",
      "matchCount": 1
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))