multiGetObjects
Retrieves on-chain details and metadata for many Sui objects in one batch request by their 32-byte hexadecimal Object IDs.
Use this method to combine many object queries in one network call. This approach reduces latency compared to querying objects individually. multiGetObjects reads directly from the fullnode's local state. It runs immediately without a transaction or gas.
- Class:
SuiClient - Package:
@mysten/sui/client - Operation type: read operation
Overviewโ
Calling multiGetObjects proves much more efficient than calling getObject in a loop. It reduces network latency by combining many object queries in one Remote Procedure Call (RPC).
Sequential getObject (N Round Trips):
App โโ getObject(A) โโโบ Fullnode โโโบ App โโ getObject(B) โโโบ Fullnode
Batch multiGetObjects (1 Round Trip):
App โโโโโโโโโโโโ multiGetObjects([A, B, C]) โโโโโโโโโโโโโบ Fullnode
App โโโโโโโโโโโโ [ResultA, ResultB, ResultC] โโโโโโโโโโโ Fullnode
Signatureโ
client.multiGetObjects(input: MultiGetObjectsParams): Promise<SuiObjectResponse[]>
Parametersโ
The method accepts a configuration object with the following properties:
| Parameter | Type | Required | Description |
|---|---|---|---|
ids | string[] | Yes | An array of 32-byte hexadecimal Object IDs. |
options | SuiObjectDataOptions | No | Configuration flags to toggle specific data fields. Applies to all requested objects. |
Most public RPC nodes enforce a limit of typically 50 IDs per request. For larger batches, you must split your array into chunks.
Return valueโ
Returns a Promise that resolves to an array of SuiObjectResponse objects.
The array order corresponds exactly to the order of the ids passed in the request:
[
{
"data": { "objectId": "0xA...", "version": "1" }
},
{
"error": { "code": "notExists", "object_id": "0xB..." }
},
{
"data": { "objectId": "0xC...", "version": "5" }
}
]
Usage examplesโ
Bulk fetch non-fungible token metadata and display attributesโ
Query a list of Non-Fungible Token (NFT) IDs. The request displays on-chain fields and image URLs:
const objectIds = ['0x123...', '0x456...', '0x789...'];
const results = await client.multiGetObjects({
ids: objectIds,
options: {
showContent: true,
showDisplay: true
}
});
// Process the results
results.forEach((result) => {
if (result.data) {
console.log("Found Item:", result.data.display?.data?.name);
} else {
console.warn("Item failed to load:", result.error);
}
});
Chunk large ID lists for batching limitsโ
Since a limit of 50 items applies per request on most public RPC nodes, use a chunking helper for large lists:
import { chunk } from 'lodash'; // or your own helper
const allIds = [/* ... array of 200 IDs ... */];
const CHUNK_SIZE = 50;
const chunks = chunk(allIds, CHUNK_SIZE);
for (const batch of chunks) {
const batchResults = await client.multiGetObjects({
ids: batch,
options: { showType: true }
});
// Process batchResults...
}
Best practicesโ
Handle partial failures per itemโ
Unlike a standard database query that might stop the whole batch on error, multiGetObjects returns a result for every ID. Even if one object fails, such as when a transaction deleted it, the remaining items in the batch still return successfully. Always check data versus error for each item in the returned array.
Rely on index-order preservationโ
The SDK preserves the index order of the input array:
results[0]corresponds toids[0]results[1]corresponds toids[1]
You can rely on this ordering to map results directly back to your original data source.
See alsoโ
getObject: retrieve details for an individual on-chain object.getOwnedObjects: list all objects owned by a specific address.- How to fetch object data: step-by-step tutorial that uses read operations in a Node.js script.
- The SuiClient architecture: conceptual overview of
SuiClientand read operations.