API clients / Methods / Indexing

Mar 27, 2025

Get objects

This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.

This is documentation for v2 of the Ruby API clients, which is not the latest version. To see the documentation for the latest version, see Ruby v3.

This is documentation for v4 of the JavaScript API clients, which is not the latest version. To see the documentation for the latest version, see JavaScript v5.

This is documentation for v3 of the Python API clients, which is not the latest version. To see the documentation for the latest version, see Python v4.

This is documentation for v8 of the Swift API clients, which is not the latest version. To see the documentation for the latest version, see Swift v9.

This is documentation for v2 of the Kotlin API clients, which is not the latest version. To see the documentation for the latest version, see Kotlin v3.

This is documentation for v6 of the C# API clients, which is not the latest version. To see the documentation for the latest version, see C# v7.

This is documentation for v3 of the Java API clients, which is not the latest version. To see the documentation for the latest version, see Java v4.

This is documentation for v3 of the Go API clients, which is not the latest version. To see the documentation for the latest version, see Go v4.

This is documentation for v1 of the Scala API clients, which is not the latest version. To see the documentation for the latest version, see Scala v2.

Required API Key: any key with the search ACL

Method signature

$index->getObjects(array objectIds)
$index->getObjects(array objectIds, [
  // All the following parameters are optional
  'attributesToRetrieve' => array
  // Any other requestOptions
])

// Get a single record
$index->getObject(string objectId)
$index->getObject(string objectId, [
  // All the following parameters are optional
  'attributesToRetrieve' => array
  // Any other requestOptions
])

// Get multiple records
$client->getMultipleObject(array multipleObjects)

index.get_objects(
  Array objectIds
)
index.get_objects(
  Array objectIds,
  Hash opts = {
    nil|Array|String attributesToRetrieve: nil,
    # any requestOptions
  }
)

// Get a single record
index.get_object(
  String objectId,
)
index.get_object(
  String objectId,
  Hash opts = {
    nil|Array|String attributesToRetrieve: nil,
    # any requestOptions
  }
)

// Get multiple records
client.multiple_get_objects(Array multipleObjects, Hash opts = {
  # any requestOptions
})

index.getObjects(array objectIDs)

index.getObjects(array objectIDs, {
  // All the following parameters are optional
  attributesToRetrieve: array
  // Any other requestOptions
})

// Get a single record
index.getObject(str objectID)

index.getObject(str objectID, {
  // All the following parameters are optional
  attributesToRetrieve: array
  // Any other requestOptions
})

client.multipleGetObjects(array multipleObjects)

client.multipleGetObjects(array multipleObjects, {
  // Any other requestOptions
})

index.get_objects(list objectIds)

index.get_objects(list objectIds, {
    // All the following parameters are optional
    'attributesToRetrieve': list
    // Any other requestOptions
})

// Get a single record
index.get_object(str objectId)
index.get_object(str objectId, {
    // All the following parameters are optional
    'attributesToRetrieve': list
    // Any other requestOptions
})

client.multiple_get_objects(list multipleObjects)

index.getObjects<T: Decodable>(
  withIDs objectIDs: [ObjectID],
  attributesToRetrieve: [Attribute] = [],
  requestOptions: RequestOptions? = nil,
  completion: Result<ObjectsResponse<T>> -> Void
)

// Get a single record
index.getObject(
  withID objectID: ObjectID,
  attributesToRetrieve: [Attribute] = [],
  requestOptions: RequestOptions? = nil,
  completion: Result<T> -> Void
)

// Get multiple records
client.multipleGetObjects(
  requests: [ObjectRequest],
  requestOptions: RequestOptions? = nil,
  completion: Result<ObjectsResponse<T>> -> Void
)

suspend fun <T : Indexable> Index.getObject(
    serializer: KSerializer<T>,
    objectID: ObjectID,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): T

suspend fun Index.getObject(
    objectID: ObjectID,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): JsonObject

suspend fun Index.getObjects(
    objectIDs: List<ObjectID>,
    attributesToRetrieve: List<Attribute>? = null,
    requestOptions: RequestOptions? = null
): ResponseObjects

suspend fun Client.multipleGetObjects(
    multipleObjects: List<RequestObjects>
): ResponseObjects

index.GetObjects(
  IEnumerable<String> objectIds,

  // All the following parameters are optional
  attributesToRetrieve: IEnumerable<String>,
  requestOptions: RequestOptions
)

// Get a single record
index.GetObject(
  String objectId,

  // All the following parameters are optional
  attributesToRetrieve: IEnumerable<String>,
  requestOptions: RequestOptions
)

// Get multiple records
client.MultipleGetObjects(
  multipleObjects: IEnumerable<MultipleGetObject>
)

index.getObjects(
  List<String> objectIds
)
index.getObjects(
  List<String> objectIds,
  List<String> attributesToRetrieve,
  RequestOptions requestOptions
)

// Get a single record
index.getObject(
  String objectId
)
index.getObject(
  String objectId,
  List<String> attributesToRetrieve,
  RequestOptions requestOptions
)

// Get multiple records
client.multipleGetObjects(
  List<MultipleGetObject> multipleObjects
)

index.GetObjects(
  []String objectIDs
)
index.GetObjectsAttrs(
  []String objectIDs,
  []String attributesToRetrieve,
  RequestOptions requestOptions
)
index.GetObjects(
  []String objectIDs,
  RequestOptions requestOptions
)

// Get a single record
index.GetObject(
  String objectID
)
index.GetObjectAttrs(
  String objectID,
  []String attributesToRetrieve,
  RequestOptions requestOptions
)
index.GetObject(
  String objectID,
  RequestOptions requestOptions
)

// Get multiple records
client.MultipleGetObjects(
  []IndexedGetObject multipleObjects
)

get from "index_name" objectIds objectIDs
get from "index_name" objectIds objectIDs attributesToRetrieve attributesToRetrieve options requestOptions

// Get a single record
get from "index_name" objectId objectID
get from "index_name" objectId objectID attributesToRetrieve attributesToRetrieve options requestOptions

// multipleGetObjects is not implemented

See code examples

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Get one or more records using their object IDs.

There are three methods you can use to get records from your indices:

getObject: get a single record from an index.
getObjects: get multiple records from an index.
multipleGetObjects: get multiple records from multiple indices within the same Algolia application.

Records are returned in the order in which they were requested.

When retrieving large numbers of records, be aware of the rate limitations on these processes and the impact on your analytics data.

To get all records from an index, use the browse method.

Examples

Read the Algolia CLI documentation for more information.

Return a list of records by their IDs

Copy

1
$index->getObjects(['myId1', 'myId2']);

1
2
3
4
5
6
7
8
9
10
11
struct Contact: Codable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
}

index.getObjects(withIDs: ["myId1", "myId2"]) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
IEnumerable<Contact> contacts = index.GetObjects<Contact>(new List<string> {"myId1", "myId2"});

// Asynchronous
IEnumerable<Contact> contacts = await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"});

1
2
3
4
5
6
7
8
// Sync version
List<Contact> contacts =
  index.getObjects(Arrays.asList("myId", "myId2"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "myId2")
);

Return a list of records with a subset of their attributes

Copy

1
2
3
$index->getObjects(['myId1', 'myId2'], [
  'attributesToRetrieve' => ['firstname', 'lastname']
]);

1
2
3
4
5
6
7
8
9
10
struct Contact: Codable {
  let firstname: String
}

index.getObjects(withIDs: ["myId1", "myId2"],
                 attributesToRetrieve: ["firstname"]) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
val objectIDs = listOf(ObjectID("myID1"), ObjectID("myID2"))
val attributes = listOf(Attribute("firstname"), Attribute("lastname"))

index.getObjects(objectIDs, attributes)

1
2
3
4
IEnumerable<Contact> contacts = index.GetObjects<Contact>(new List<string> {"myId1", "myId2"}, attributesToRetrieve: new String[] { "firstname" });

// Asynchronous
IEnumerable<Contact> contacts = await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"}, attributesToRetrieve: new String[] { "firstname" });

1
2
3
4
5
6
7
8
9
// Sync version
List<Contact> contacts =
  index.getObjects(Arrays.asList("myId", "myId2"), Arrays.asList("firstname"));

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "myId2"),
  Arrays.asList("firstname")
);

If an object ID isn’t found in your index, the result is null for that object ID.

Return a single record by its ID

Copy

1
2
3
4
5
6
7
// Retrieves all attributes
$index->getObject('myId');

// Retrieves only firstname and lastname attributes
$index->getObject('myId', [
  'attributeToRetrieve' => ['firstname', 'lastname'],
]);

1
2
3
4
5
6
# Retrieves all attributes
index.get_object('myId')
# Retrieves firstname and lastname attributes
res = index.get_object('myId', { attributesToRetrieve: ['firstname', 'lastname'] })
# Retrieves only the firstname attribute
res = index.get_object('myId', { attributesToRetrieve: ['firstname'] })

1
2
3
4
5
6
7
8
9
10
11
// Retrieves all attributes
index.getObject('myId').then(object => {
  console.log(object);
});

// Retrieves only firstname and lastname attributes
index.getObject('myId', {
  attributesToRetrieve: ['firstname', 'lastname']
}).then(object => {
  console.log(object);
});

1
2
3
4
5
6
7
8
9
10
11
12
# Retrieves all attributes
index.get_object('myId')

# Retrieves firstname and lastname attributes
index.get_object('myId', {
    'attributesToRetrieve': ['firstname, lastname']
})

# Retrieves only the firstname attribute
index.get_object('myId', {
    'attributesToRetrieve': ['firstname']
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
struct Contact: Codable {
  let firstname: String
  let lastname: String?
}

// Retrieve all attributes.
index.getObject(withID: "myId") { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Retrieves `firstname` and `lastname` attributes.
index.getObject(withID: "myId",
                attributesToRetrieve: ["firstname", "lastname"]) { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

// Retrieve only the `firstname` attribute.
index.getObject(withID: "myId",
                attributesToRetrieve: ["firstname"]) { (result: Result<Contact, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
index.getObject(ObjectID("myID1"))

@Serializable
data class Contact(
    val firstname: String,
    val lastname: String,
    override val objectID: ObjectID
) : Indexable

val objectID = ObjectID("myID1")

index.getObject(objectID)
index.getObject(Contact.serializer(), objectID)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Retrieves all attributes
Contact res = index.GetObject<Contact>("myId");

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId");

// Retrieves firstname and lastname attributes
Contact res = index.GetObject<Contact>("myId", attributesToRetrieve: new List<string> { "firstname", "lastname" });

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId", attributesToRetrieve: new List<string> { "firstname", "lastname" });

// Retrieves only the firstname attribute
Contact res = index.GetObject<Contact>("myId", attributesToRetrieve: new List<string> { "firstname" });

// Asynchronous
Contact res = await index.GetObjectAsync<Contact>("myId", attributesToRetrieve: new List<string> { "firstname" });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Retrieves all attributes
Contact contact = index.getObject("myId");

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId");

// Retrieves firstname and lastname attributes
Contact contact = index.getObject("myId", Arrays.asList("firstname", "lastname"));

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId", Arrays.asList("firstname", "lastname"));

// Retrieves only the firstname attribute
Contact contact = index.getObject("myId", Arrays.asList("firstname"));

// Async version
// CompletableFuture<Contact> contact =
  index.getObject("myId", Arrays.asList("firstname"));

1
2
3
4
5
6
7
8
// Retrieves the object with all its attributes
err := index.GetObject("myId", &object)

// Retrieves the object with only its `firstname` attribute
err := index.GetObject("myId", &object, opt.AttributesToRetrieve("firstname"))

// Retrieves the object with only its `firstname` and `lastname` attributes
err := index.GetObject("myId", &object, opt.AttributesToRetrieve("firstname", "lastname"))

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Retrieves all attributes
client.execute {
  get from "index" objectId "myId"
}

// Retrieves firstname and lastname attributes
client.execute {
  get from "index" objectId "myId" attributesToRetrieve Seq("firstname", "lastname")
}

// Retrieves only the firstname attribute
client.execute {
  get from "index" objectId "myId" attributesToRetrieve Seq("firstname")
}

If the object ID doesn’t exist in your index, this method returns an error.

Return records from multiple indices

Copy

1
2
3
4
5
6
7
8
9
10
$client->multipleGetObjects(array(
  [
    "indexName" => "index1",
    "objectID" => "myId1"
  ], 
  [
    "indexName" => "index2",
    "objectID" => "myId2"
  ]
));

1
2
3
4
5
6
client.multipleGetObjects([
  { indexName: 'index1', objectID: 'myId1' },
  { indexName: 'index2', objectID: 'myId2' }
]).then(({ results }) => {
  console.log(results);
});

1
2
3
4
5
6
7
8
9
10
let requests: [ObjectRequest] = [
  .init(indexName: "index1", objectID: "myId1"),
  .init(indexName: "index2", objectID: "myId2"),
]

client.multipleGetObjects(requests: requests) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
val requests = listOf( 
  RequestObject(
    IndexName("index1"),
    ObjectID("myId1")
  ),
  RequestObject(
    IndexName("index2"),
    ObjectID("myId2")
  )
)

client.multipleGetObjects(requests)

1
2
3
4
5
6
7
8
9
10
var objectsToRetrieve = new List<MultipleGetObject>
{
  new MultipleGetObject { IndexName = "index1", ObjectID = "myId1" },
  new MultipleGetObject { IndexName = "index2", ObjectID = "myId2" }
};

IEnumerable<Object> objects = client.MultipleGetObjects<Object>(objectsToRetrieve);

// Asynchronous
IEnumerable<Object> objects = await client.MultipleGetObjectsAsync<Object>(objectsToRetrieve);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<MultipleGetObject> objectsToRetrieve =
    Arrays.asList(
        new MultipleGetObject("index1", "myId1"),
        new MultipleGetObject("index2", "myId2")
    );
    
    MultipleGetObjectsResponse<AlgoliaMultipleOpObject> multipleGet =
    searchClient
      // Async
      .multipleGetObjectsAsync(objectsToRetrieve, AlgoliaMultipleOpObject.class)
      .join();

      // Sync
      .multipleGetObjects(objectsToRetrieve, AlgoliaMultipleOpObject.class)
      .join();

1
2
3
4
5
6
requests := []IndexedGetObject{
    {IndexName: "index1", ObjectID: "myId1"},
    {IndexName: "index2", ObjectID: "myId2"},
  }
  
  res, err = client.MultipleGetObjects(requests, &objects)

Return a list of records and send extra HTTP headers

Copy

1
2
3
4
5
$objectIDs = [/* objectIDs */];

$index->getObjects($objectIDs, [
  'X-Forwarded-For' => '94.228.178.246'
];

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

struct Contact: Codable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
}

index.getObjects(withIDs: ["myId1", "myId2"],
                 requestOptions: requestOptions) { (result: Result<ObjectsResponse<Contact>, Error>) in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

index.getObjects(listOf(ObjectID("myID1"), ObjectID("myID2")), requestOptions = requestOptions)

1
2
3
4
5
6
7
8
9
RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.GetObjects(new List<string> {"myId1", "myId2"}, requestOptions);

// Asynchronous
await index.GetObjectsAsync<Contact>(new List<string> {"myId1", "myId2"}, requestOptions);

1
2
3
4
5
6
7
8
9
10
11
// Sync version
List<Contact> contacts = index.getObjects(
  Arrays.asList("myId", "myId2"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

// Async version
CompletableFuture<List<Contact>> contacts = index.getObjectsAsync(
  Arrays.asList("myId", "myId2"),
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

1
2
3
4
5
extraHeaders := opt.ExtraHeaders(map[string]string{
    "X-Algolia-User-ID": "userID2",
})

err := index.GetObjects([]string{"myId1", "myId2"}, &objects, extraHeaders)

1
2
3
4
5
6
7
8
client.execute {
  get from "index" objectIds Seq(
    "myId1",
    "myId2"
  ) options RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
}

Parameters

`objectIDs`	type: list Required List of objectIDs to retrieve.
`attributesToRetrieve`	type: string \| array Optional Comma-separated list of attributes to include with each record. By default, all retrievable attributes are returned.
`requestOptions`	type: key-value pairs default: "" Optional request options to add to the request. You can’t use search parameters with `getObjects`.
`objectID`	type: integer\|string Required Object ID for the record you want to get.
`multipleObjects`	type: list of multipleObject true (for multipleGetObjects) A list of key-value pairs that represent specific records in specific indices.

multipleObjects ➔ multipleObject

Each multipleObject parameter must have two attributes:

indexName. The index in which to search (as a string).
objectId. The object ID of the record to retrieve (as a string).

Check the example Return records from multiple indices for reference.

Response

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format

Copy

          {
  "results": [
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ]
}

        

The following example tries to get two records. The first object ID doesn’t exist: null is returned. The second object ID exists and the record is returned.

Copy

          {
  "results": [
    null,
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ],
  "message": "ObjectID 1182729441 does not exist."
}

        

Field	Description
`results`	list List of the retrieved records.

Did you find this page helpful?

Get objects

About this method

Examples

Return a list of records by their IDs

Return a list of records with a subset of their attributes

Return a single record by its ID

Return records from multiple indices

Return a list of records and send extra HTTP headers

Parameters

multipleObjects ➔ multipleObject

Response

JSON format

On this page