Queries are requests that do not require network consensus. Queries are processed only by the single node the request is sent to. Below is a list of network queries by service.
Recommend Using Mirror Node REST API
For obtaining token information and historical data, consider using the Mirror Node REST API endpoint Get Token Account Balance which offers several advantages:
- Cost-effective and scalable: Mirror node providers offer paid plans with a large number of queries included. The Hedera-hosted mirror node offers free queries with specific throttles for testing. While some SDK queries are currently free, these are subject to change in the future.
- Performance: Mirror nodes don’t burden consensus nodes, allowing them to focus on processing transactions and providing efficient access to historical data without impacting network performance.
- Historical data: Mirror nodes store complete transaction history, records, and events - ideal for analytics, auditing, and monitoring past activity.
📚 For more details on querying data, read: Querying Data on Hedera: SDK vs Mirror Node REST API
DEPRECATION NOTICE: AccountBalanceQuery
AccountBalanceQuery reads the consensus node’s cryptoGetBalance query, which is being throttled to zero as part of its deprecation. It has been throttled to zero on testnet (August 13, 2026) and is scheduled for mainnet on September 9, 2026 (consensus node release 0.77, an estimate subject to change). After removal, AccountBalanceQuery will no longer function.JavaScript/TypeScript developers: migrate to MirrorNodeAccountBalanceQuery, available now in @hiero-ledger/sdk v2.87.0+. See Get account balance. Java and Go implementations are in progress. For Rust, and for Java and Go until those ship, call the Mirror Node REST API directly. MirrorNodeAccountBalanceQuery returns HBAR balances only; for token balances, use the Mirror Node REST API token balances endpoint.📚 For the full migration guide, read: Migrating from AccountBalanceQuery: What You Need to Know
Get Query Cost
A query that returns the cost of a query prior to submitting the query to the network node for processing. If the cost of the query is greater than the default max query payment (1 HBAR) you can use setMaxQueryPayment(<hbar>) to change the default.
MirrorNodeAccountBalanceQuery has no getCost() or query-payment concept. It is a free Mirror Node REST call, not a paid consensus-node query, so the Get Query Cost pattern below does not apply to it. The example below uses AccountBalanceQuery because query-cost estimation is inherently a consensus-node-query concept.
| Method | Type | Description |
|---|
getCost(<client>) | Client | Get the cost of the query in HBAR |
getCost(<client, timeout>) | Client, Duration | The max length of time the SDK will attempt to retry in the event of repeated busy responses from the node(s) |
getCostAsync(<client>) | Client | Get the cost of a query asynchronously |