Skip to main content

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 vs batch comparison
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โ€‹

Signature
client.multiGetObjects(input: MultiGetObjectsParams): Promise<SuiObjectResponse[]>

Parametersโ€‹

The method accepts a configuration object with the following properties:

ParameterTypeRequiredDescription
idsstring[]YesAn array of 32-byte hexadecimal Object IDs.
optionsSuiObjectDataOptionsNoConfiguration flags to toggle specific data fields. Applies to all requested objects.
note

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:

Response
[
{
"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:

bulkFetch.js
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:

chunking.js
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 to ids[0]
  • results[1] corresponds to ids[1]

You can rely on this ordering to map results directly back to your original data source.


See alsoโ€‹