> For the complete documentation index, see [llms.txt](https://docs.triton.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.triton.one/solana/reading-account-state/cloudbreak-indexed-accounts.md). # Cloudbreak Accounts Cloudbreak custom indexes serve getProgramAccounts, getTokenAccountsByOwner and getTokenAccountsByDelegate: parameters, commitment, limits and error codes. On an endpoint where Cloudbreak is enabled, Cloudbreak answers the supported methods from its index automatically. There is nothing to enable or route on your side. ## Use cases * **Reading many program accounts at scale** (AMMs, indexers): repeated `getProgramAccounts` queries with `memcmp` or `dataSize` filters are served from a matching index instead of a full scan. * **SPL token queries** by owner or delegate. **What not to use it for.** Cloudbreak answers point-in-time queries on current account state and does not serve transaction history. For a live stream of account changes, use [Dragon's Mouth](/solana/real-time-streaming/dragon-s-mouth-grpc.md). `processed` requests on Cloudbreak-routed methods are answered at `confirmed` commitment. ## Features and benefits
:magnifying-glass: Fast getProgramAccountsgetProgramAccounts against a program with a large account set, especially with memcmp or dataSize filters you run repeatedly.
:check-double: Standard Solana RPC formatRequests and responses match standard Solana JSON-RPC for every supported method, so existing clients work without changes.
:coins: SPL token queriesToken account queries by owner or delegate, plus Token and Token-2022 getProgramAccounts queries with memcmp filters.
:bolt: Dynamic indexing on live trafficIndexes are built automatically from real query traffic: heavily requested filter shapes get their own index, with nothing to configure on your side.
## How it works Cloudbreak builds its index from a validator snapshot for the starting state and a Yellowstone gRPC stream of account updates to stay current. It tracks both `confirmed` and `finalized` commitment as the chain advances, so a query reads the same state the chain has reached at the commitment you ask for. ```mermaid %%{init: {'theme':'base','themeVariables':{'primaryColor':'#F2EDF6','primaryBorderColor':'#7A4BA0','primaryTextColor':'#171717','lineColor':'#956FB3','secondaryColor':'#E4DBEC','tertiaryColor':'#D7C9E3','edgeLabelBackground':'#F2EDF6'},'flowchart':{'nodeSpacing':35,'rankSpacing':55,'curve':'linear'}}}%% flowchart LR vsnap["Validator snapshot"] --> state["Account
state"] live["Live gRPC updates"] --> state live --> idx["Cloudbreak indexes"] state --> q["JSON-RPC
query layer"] idx --> q q --> you["Your app"] idx -.- tracker["Query tracker"] tracker -.- you style you fill:#D6EAF8,stroke:#259DD0 ``` ### How indexes get created A `getProgramAccounts` query is fast when an index matches its filter shape. Cloudbreak creates these indexes from real traffic: it counts the query shapes it receives, and once a shape is requested often enough it builds the matching index automatically, backing off while the index catches up so index creation does not compete with ingestion. Token and Token-2022 program queries with `memcmp` filters use Cloudbreak's dedicated token indexes rather than this path. A query with no matching index yet still returns correct results, it just runs slower until the index is built. ## Supported methods | Method | Returns | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `getProgramAccounts` | All accounts owned by a program, with filters, including Token and Token-2022 program queries with `memcmp` filters. | | `getTokenAccountsByOwner` | SPL Token and Token-2022 token accounts owned by a wallet. | | `getTokenAccountsByDelegate` | SPL Token and Token-2022 token accounts a delegate controls. | Other account methods, such as `getAccountInfo`, `getMultipleAccounts`, `getBalance` and `getTokenAccountBalance`, are served by Triton's standard RPC nodes, not Cloudbreak. Other methods Cloudbreak does not cover (`getVoteAccounts`, transaction methods, block methods) are not accelerated, and your endpoint serves them as usual. `getTokenAccountsByMint` is not available on shared endpoints and returns JSON-RPC error `-32601 Method not found`. ### getProgramAccounts Returns every account owned by a program, with optional filtering. This is the method Cloudbreak is built to accelerate. Compatible with the standard [Solana `getProgramAccounts` API](https://solana.com/docs/rpc/http/getprogramaccounts). Position 0 is the program pubkey (base58 string), required. Position 1 is an optional config object: | Field | Required | Default | Description | | ---------------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `encoding` | optional | `binary` | `base64`, `base58`, `base64+zstd`, or `jsonParsed`. | | `filters` | optional | none | Array of `memcmp`, `dataSize`, and `tokenAccountState` filters. All filters must match. There's no limit on the number of filters. Results are always sorted by pubkey. | | `dataSlice` | optional | full data | `{ "offset": , "length": }`. Returns only that byte range of account data. | | `commitment` | optional | `finalized` | `confirmed` or `finalized`. | | `minContextSlot` | optional | none | Fail with `-32016` if the index has not reached this slot yet. | | `withContext` | optional | `false` | When `true`, wrap the result in `{ "context": { "slot": N }, "value": [...] }`. | A `memcmp` filter matches a base58-encoded byte sequence at a fixed offset: `{ "memcmp": { "offset": 32, "bytes": "" } }`. A `dataSize` filter matches accounts of an exact data length: `{ "dataSize": 165 }`. On shared endpoints, SPL Token and Token-2022 queries need a `memcmp` filter with the full 32-byte owner pubkey at offset `32` or the full mint pubkey at offset `0`, and System Program queries need a `memcmp` filter. Calls without them are rejected with HTTP `403` before they reach Cloudbreak. A shorter `bytes` value at offset `0` or `32` returns `-32602`. Other programs need no filter. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "getProgramAccounts", "params": [ "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", { "encoding": "base64", "commitment": "confirmed", "withContext": true, "filters": [{ "dataSize": 752 }] } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": { "context": { "slot": 250000042 }, "value": [ { "pubkey": "58oQChx4yWmvKdwLLZzBi4ChoCc2fqCUWBkwMihLYQo2", "account": { "lamports": 1234567, "owner": "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", "executable": false, "rentEpoch": 18446744073709551615, "space": 752, "data": ["", "base64"] } } ] } } ``` {% endtab %} {% endtabs %} Without `withContext`, `result` is the array directly rather than the `{ context, value }` envelope, matching standard Solana RPC behavior. {% hint style="info" %} `getProgramAccounts` responses are streamed back as a chunked HTTP body, so a client can begin parsing accounts before the query finishes and peak memory stays bounded on both ends. Standard HTTP and JSON-RPC clients consume the chunked body transparently. If a request fails before the first batch is sent, you get a normal JSON-RPC error. If it fails partway through streaming, the connection is aborted and your client reports a transport error. A response still streaming at the 90-second limit ends early, and your JSON parser reports an incomplete document. Treat a transport error or a JSON parse error on `getProgramAccounts` as a failed request, and retry. {% endhint %} ### getTokenAccountsByOwner Returns the SPL Token and Token-2022 token accounts owned by a wallet. Cloudbreak indexes the token owner and mint as dedicated columns, so this method stays fast even though the SPL Token program has a very large account set. Compatible with the standard [Solana `getTokenAccountsByOwner` API](https://solana.com/docs/rpc/http/gettokenaccountsbyowner). {% hint style="info" %} For SPL token data, use the token methods rather than a raw `getProgramAccounts` against the Token program. The token methods use Cloudbreak's dedicated token indexes; a `getProgramAccounts` over the Token program without an owner or mint `memcmp` filter is rejected on shared endpoints. {% endhint %} Position 0 is the owner pubkey (base58), required. Position 1 is a filter object, required, with exactly one of: | Filter | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `{ "mint": "" }` | Restrict to a single mint. | | `{ "programId": "" }` | Restrict to SPL Token (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) or Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`). | Position 2 is an optional config object accepting `encoding`, `dataSlice`, `commitment`, and `minContextSlot`, with the same meanings as in `getProgramAccounts`. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "getTokenAccountsByOwner", "params": [ "", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, { "encoding": "jsonParsed", "commitment": "confirmed" } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": { "context": { "slot": 250000042 }, "value": [ { "pubkey": "", "account": { "lamports": 2039280, "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "executable": false, "rentEpoch": 18446744073709551615, "space": 165, "data": { "program": "spl-token", "parsed": { "type": "account", "info": { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "owner": "", "tokenAmount": { "amount": "1000000", "decimals": 6, "uiAmount": 1.0, "uiAmountString": "1" }, "state": "initialized", "isNative": false } }, "space": 165 } } } ] } } ``` {% endtab %} {% endtabs %} The token methods always wrap their result in the `{ context, value }` envelope, matching standard Solana RPC. ### getTokenAccountsByDelegate Identical parameters and response shape to `getTokenAccountsByOwner`, but position 0 is the delegate pubkey and results are the SPL Token and Token-2022 token accounts that delegate has authority over. Compatible with the standard [Solana `getTokenAccountsByDelegate` API](https://solana.com/docs/rpc/http/gettokenaccountsbydelegate). {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "getTokenAccountsByDelegate", "params": [ "", { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, { "encoding": "jsonParsed" } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": { "context": { "slot": 250000042 }, "value": [ { "pubkey": "", "account": { "lamports": 2039280, "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "executable": false, "rentEpoch": 18446744073709551615, "space": 165, "data": { "program": "spl-token", "parsed": { "type": "account", "info": { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "owner": "", "delegate": "", "delegatedAmount": { "amount": "500000", "decimals": 6, "uiAmount": 0.5, "uiAmountString": "0.5" }, "state": "initialized", "isNative": false } }, "space": 165 } } } ] } } ``` {% endtab %} {% endtabs %} ## Making requests The Cloudbreak-accelerated methods are standard Solana JSON-RPC, so you call them the same way you call any other method on your RPC endpoint. There is nothing Cloudbreak-specific to install or configure on the client side, and existing Solana clients (`@solana/web3.js`, `solana-py`, and others) work without changes. Every call is an HTTP POST with `Content-Type: application/json`: ```shell curl https:// \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"getTokenAccountsByOwner","params":["",{"programId":"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},{"encoding":"base64"}]}' ``` * **Coverage is automatic.** Every program's accounts are indexed except a few excluded programs (see the FAQ), and query shapes that receive enough traffic get their own index over time, so common queries are fast with no setup on your side. See [How indexes get created](#how-indexes-get-created). * **Commitment levels** are `confirmed` and `finalized`. The default is `finalized`. `processed` requests are answered at `confirmed` commitment on Triton endpoints. See [Commitment and consistency](#commitment-and-consistency). * **Encodings** are `base64`, `base58`, `base64+zstd`, and `jsonParsed`. If you do not set `encoding`, the response uses the legacy `binary` format, which is a single base58 string rather than a `[data, encoding]` array. Set `encoding` to `base64` for most uses. {% hint style="warning" %} The default `binary` encoding and `base58` only work for account data of 128 bytes or fewer, after any `dataSlice`. Larger accounts return `-32600` with a message telling you to switch to `base64`. Because the default is `binary`, set `encoding` to `base64` whenever an account can exceed 128 bytes. {% endhint %} ## Batch requests Send an array of request objects to run several in one round trip. The response is an array with one result per request. On Triton endpoints, a batch that contains `getProgramAccounts`, `getTokenAccountsByOwner`, or `getTokenAccountsByDelegate` is split, so every request in it runs individually, and each result is added to the one response array as it completes. Results can arrive in a different order from your requests, so match each result to its request by `id`. A `getProgramAccounts` result inside a batch is returned in full rather than streamed. {% tabs %} {% tab title="Request" %} ```json [ { "jsonrpc": "2.0", "id": 1, "method": "getTokenAccountsByOwner", "params": [ "", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, { "encoding": "base64" } ] }, { "jsonrpc": "2.0", "id": 2, "method": "getTokenAccountsByDelegate", "params": [ "", { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, { "encoding": "base64" } ] } ] ``` {% endtab %} {% tab title="Response" %} ```json [ { "jsonrpc": "2.0", "id": 1, "result": { "context": { "slot": 250000042 }, "value": [] } }, { "jsonrpc": "2.0", "id": 2, "result": { "context": { "slot": 250000042 }, "value": [] } } ] ``` {% endtab %} {% endtabs %} ## Commitment and consistency Cloudbreak tracks two commitment levels and serves point-in-time reads against them. * **`confirmed`** reflects account state as soon as a block is confirmed. The indexer writes the slot's accounts first, then advances the confirmed marker, so a confirmed read never sees a half-written slot. * **`finalized`** (the default) reflects account state at the latest finalized slot. `processed` requests are answered at `confirmed` commitment on Triton endpoints. Use `minContextSlot` to guarantee freshness. If you read a slot from one call and want a later query to be at least as fresh, pass that slot as `minContextSlot`. If the index has not reached it, the call fails with `-32016` rather than returning stale data. `getProgramAccounts` and the token methods check it on every call. Use `withContext: true` on `getProgramAccounts` when you need to know which slot a result corresponds to. The token methods always include the context. ## Performance characteristics * **`getProgramAccounts` and token queries** return in milliseconds once an index matches the query shape. A shape with no matching index still returns correct data, it just runs slower until the index exists. See [How indexes get created](#how-indexes-get-created). * **Large repeated queries are cached.** Triton runs Cloudbreak with response caching on. For a large response (about 200 KB or more), the serialized result is kept per query shape (program, filters, encoding, data slice, and commitment), and the next time you run that query only the accounts that changed since the last response are read and re-encoded. Frequent polling of the same large query stays fast. * **Large results stream back.** A response is sent as the index reads it, so a large `getProgramAccounts` result starts arriving right away. Queries have a 45-second limit (20 seconds for the token methods and Token or Token-2022 `getProgramAccounts` queries). A query that exceeds it before the first result is sent returns error `-32603`; a `getProgramAccounts` response that has already started streaming ends early. Responses have a 90-second limit; a response still streaming at the limit ends early, so your JSON parser reports an incomplete document. Treat that as a failed request and retry. Narrow large queries with filters or `dataSlice`. ## Benchmarks Cloudbreak serves indexed `getProgramAccounts` reads faster than a full Agave scan, with latency that scales with the size of the result rather than the program. Measured end-to-end within a single datacenter for responses up to 10 MB (`getProgramAccounts`, base64): | Response size | Agave avg | Cloudbreak avg | Agave p90 | Cloudbreak p90 | | ------------- | --------- | -------------- | --------- | -------------- | | 1-10 KB | 1,725 ms | 4 ms | 2,478 ms | 5 ms | | 10-100 KB | 2,725 ms | 7 ms | 4,699 ms | 11 ms | | 100 KB-1 MB | 3,971 ms | 8 ms | 4,693 ms | 13 ms | | 1-10 MB | 3,693 ms | 47 ms | 4,708 ms | 25 ms | Full benchmarks and methodology: [Inside Cloudbreak](https://blog.triton.one/inside-cloudbreak-indexing-architecture-for-performant-account-reads). ## Error reference | Code | Name | Meaning | | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | `-32601` | Method not found | The method is not implemented. See [Supported methods](#supported-methods). | | `-32010` | Key excluded from secondary index | The program is excluded from Cloudbreak's index, so `getProgramAccounts` isn't served for it. | | `-32602` | Invalid params | Bad pubkey, malformed filter, or a Token program `memcmp` whose `bytes` isn't a full 32-byte pubkey. | | `-32600` | Invalid request | `binary` or `base58` requested for account data over 128 bytes. Use `base64`. | | `-32016` | Minimum context slot not reached | The index has not yet reached your `minContextSlot`. `data.contextSlot` holds the slot it has reached. | | `-32005` | Node is unhealthy | Sent with HTTP `503` while a node catches up with the chain. Retry with backoff. | | `-32603` | Internal error | A database error or a query that exceeded the server-side timeout. | ## FAQ
Can I send the exact same requests I send to a normal Solana RPC node? Yes, for the supported methods. The request and response formats are JSON-RPC 2.0 and match standard Solana RPC, so existing clients and tooling work without changes.
Why does my getProgramAccounts for a program return -32010? The program is on Cloudbreak's exclusion list, so `getProgramAccounts` isn't served for it on shared endpoints. Every other program is indexed. The excluded keys are currently: * Serum DEX v3 (`9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin`) * Candy Machine v1 and v2 (`cndyAnrLdpjq1Ssp1z8xxDsB8dxe7u4HL5Nxi2K5WXZ`, `cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ`) * Legacy Metaplex auction programs (`auctxRXPeJoc4817jDhf4HbjnhEcr1cCXenosMhK5R8`, `p1exdMJcjVao65QdewkaZRUnU6VPSXhus9n2GzWfh98`) * Kin token mint (`kinXdEcpDQeHPEuQnqmUgtYykqKGVFq6CeVX5iAHJq6`) Light Protocol account compression (`compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq`) is served by standard RPC nodes on shared endpoints, without Cloudbreak's index. SPL Token and Token-2022 queries are served by Cloudbreak's token indexes instead. If you need data from an excluded program, contact support.
Why is one getProgramAccounts query fast and a similar one slow? The fast one has a matching index and the slow one does not. A new query shape becomes fast once it is requested often enough for automatic index creation to pick it up. Both return correct data regardless.
My large getProgramAccounts response failed to parse. What happened? A stream that errors partway through aborts the connection, so your client sees a transport error. A response still streaming at the 90-second limit ends early, so your JSON parser reports an incomplete document. Treat either as a failed request and retry; do not treat a partial body as a partial result.
How fresh is the data? A `confirmed` read reflects state at the latest confirmed slot; a `finalized` read reflects the latest finalized slot. Use `withContext: true` to see the exact slot, and `minContextSlot` to require a minimum. If a node is behind the chain, it answers HTTP `503` (`-32005`) rather than serve stale data. Retry with backoff.
Can I get a live stream of changes instead of polling? Use Dragon's Mouth. Cloudbreak answers point-in-time queries; Dragon's Mouth streams updates as they occur.
## Pricing For rates, see [triton.one/pricing](https://triton.one/pricing). For how usage is billed, see [Plans and billing](/account-and-billing/plans-and-billing.md). ## What's next
:play: QuickstartQuery account state via JSON-RPC and set up Account Sync.Reading account state quickstart
:arrows-rotate: Account SyncStreams account updates into your process, so Triton SDK reads of tracked accounts resolve from memory instead of RPC.Account Sync
:list-check: Best practicesHow to keep account, program and token reads fast and fresh at scale.Reading account state best practices
*** :life-ring: Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ :briefcase: Sales questions? [Contact us](https://triton.one/contact)\ :sparkles: AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ :rss: Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)