> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get objects

> Get one or more records using their object IDs.

export const Legacy = ({title, href}) => {
  return <Note>

    This page documents an earlier version of the API client.
    For the latest version, see <a href={href}>{title}</a>.

    </Note>;
};

<Legacy title="Retrieve records" href="/doc/libraries/sdk/methods/search/get-objects" />

**Required ACL:** `search`

You can use three methods 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.

<Info>
  When retrieving large numbers of records, be aware of the [rate limitations](/doc/guides/scaling/algolia-service-limits#application-record-and-index-limits) on these processes and the [impact on your analytics data](/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/concepts/indices-analytics).
</Info>

To get **all** records from an index, use the [`browse`](/doc/libraries/sdk/v1/methods/browse) method.

## Examples

### Return a list of records by their IDs

<CodeGroup>
  ```cs C# theme={"system"}
  IEnumerable<Contact> contacts = index.GetObjects<Contact>(new List<string> {"myId1", "myId2"});

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

  ```go Go theme={"system"}
  err := index.GetObjects([]string{"myId1", "myId2"}, &objects)
  ```

  ```java Java theme={"system"}
  // Sync version
  List<Contact> contacts =
    index.getObjects(Arrays.asList("myId", "myId2"));

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

  ```js JavaScript theme={"system"}
  index.getObjects(['myId1', 'myId2']).then(({ results }) => {
    console.log(results);
  });
  ```

  ```kotlin Kotlin theme={"system"}
  index.getObjects(listOf(ObjectID("myID1"), ObjectID("myID2")))
  ```

  ```php PHP theme={"system"}
  $index->getObjects(['myId1', 'myId2']);
  ```

  ```python Python theme={"system"}
  index.get_objects(['myId1', 'myId2'])
  ```

  ```ruby Ruby theme={"system"}
  res = index.get_objects(['myId', 'myId2'])
  ```

  ```scala Scala theme={"system"}
  client.execute {
    get from "index" objectIds Seq("myId2", "myId2")
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Return a list of records with a subset of their attributes

<CodeGroup>
  ```cs C# theme={"system"}
  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" });
  ```

  ```go Go theme={"system"}
  err := index.GetObjects([]string{"myId1", "myId2"}, &objects, opt.AttributesToRetrieve("firstname"))
  ```

  ```java Java theme={"system"}
  // 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")
  );
  ```

  ```js JavaScript theme={"system"}
  index.getObjects(['myId1', 'myId2'], {
    attributesToRetrieve: ['firstname', 'lastname']
  }).then(({ results }) => {
    console.log(results);
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val objectIDs = listOf(ObjectID("myID1"), ObjectID("myID2"))
  val attributes = listOf(Attribute("firstname"), Attribute("lastname"))

  index.getObjects(objectIDs, attributes)
  ```

  ```php PHP theme={"system"}
  $index->getObjects(['myId1', 'myId2'], [
    'attributesToRetrieve' => ['firstname', 'lastname']
  ]);
  ```

  ```python Python theme={"system"}
  index.get_objects(['myId1', 'myId2'], {
      'attributesToRetrieve': ['firstname', 'lastname']
  })
  ```

  ```ruby Ruby theme={"system"}
  res = index.get_objects(['myId', 'myId2'], { attributesToRetrieve: ['firstname', 'lastname'] })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    get from "index" objectIds Seq(
      "myId2",
      "myId2"
    ) attributesToRetrieve Seq("firstname")
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```cs C# theme={"system"}
  // 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" });
  ```

  ```go Go theme={"system"}
  // 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"))
  ```

  ```java Java theme={"system"}
  // 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"));
  ```

  ```js JavaScript theme={"system"}
  // 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);
  });
  ```

  ```kotlin Kotlin theme={"system"}
  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)
  ```

  ```php PHP theme={"system"}
  // Retrieves all attributes
  $index->getObject('myId');

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

  ```

  ```python Python theme={"system"}
  # 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']
  })
  ```

  ```ruby Ruby theme={"system"}
  # 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'] })
  ```

  ```scala Scala theme={"system"}
  // 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")
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

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

### Return records from multiple indices

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  requests := []IndexedGetObject{
      {IndexName: "index1", ObjectID: "myId1"},
      {IndexName: "index2", ObjectID: "myId2"},
    }
    
    res, err = client.MultipleGetObjects(requests, &objects)
  ```

  ```java Java theme={"system"}
      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();
  ```

  ```js JavaScript theme={"system"}
  client.multipleGetObjects([
    { indexName: 'index1', objectID: 'myId1' },
    { indexName: 'index2', objectID: 'myId2' }
  ]).then(({ results }) => {
    console.log(results);
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val requests = listOf( 
    RequestObject(
      IndexName("index1"),
      ObjectID("myId1")
    ),
    RequestObject(
      IndexName("index2"),
      ObjectID("myId2")
    )
  )

  client.multipleGetObjects(requests)
  ```

  ```php PHP theme={"system"}
  $client->multipleGetObjects(array(
    [
      "indexName" => "index1",
      "objectID" => "myId1"
    ], 
    [
      "indexName" => "index2",
      "objectID" => "myId2"
    ]
  ));
  ```

  ```python Python theme={"system"}
  client.multiple_get_objects([
    {'indexName': 'index1', 'objectID': 'myId1'}, 
    {'indexName': 'index2', 'objectID': 'myId2'}
  ])
  ```

  ```ruby Ruby theme={"system"}
  client.multiple_get_objects([
    { "indexName" => "index1", "objectID" => "myId1" },
    { "indexName" => "index2", "objectID" => "myId2" }
  ])
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Return a list of records and send extra HTTP headers

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  extraHeaders := opt.ExtraHeaders(map[string]string{
      "X-Algolia-User-ID": "userID2",
  })

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

  ```java Java theme={"system"}
  // 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")
  );
  ```

  ```js JavaScript theme={"system"}
  index.getObjects(['myId1', 'myId2'], {
    headers: {
      'X-Forwarded-For': '94.228.178.246'
    }
  }).then(({ results }) => {
    console.log(results);
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val requestOptions = requestOptions {
      headerAlgoliaUserId(UserID("user123"))
  }

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

  ```php PHP theme={"system"}
  $objectIDs = [/* objectIDs */];

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

  ```python Python theme={"system"}
  index.get_objects(['myId1', 'myId2'], {
      'X-Forwarded-For': '94.228.178.246'
  })
  ```

  ```ruby Ruby theme={"system"}
  res = index.get_objects(['myId1', 'myId2'], {
    headers: {
      'X-Algolia-User-ID': 'user123'
    }
  })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    get from "index" objectIds Seq(
      "myId1",
      "myId2"
    ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
    )
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="multipleObjects" type="object[]" required>
  A list of key-value pairs that represent specific records in specific indices.
  (Required for `multipleGetObjects`).

  <Expandable>
    <ParamField body="indexName" type="string" required>
      Index in which to search.
    </ParamField>

    <ParamField body="objectId" type="string" required>
      Object ID of the record to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="objectID" type="string" required>
  Object ID for the record you want to get.
  (Required for `getObject`)
</ParamField>

<ParamField body="objectIDs" type="string[]" required>
  List of objectIDs to retrieve.
  (Required for `getObjects`).
</ParamField>

<ParamField body="attributesToRetrieve" type="string | string[]">
  Comma-separated list of attributes to include with each record.

  By default, all retrievable attributes are returned.
</ParamField>

<ParamField body="requestOptions" type="object">
  request options to add to the request.

  <Info>
    You can't use [search parameters](/doc/api-reference/search-api-parameters) with `getObjects`.
  </Info>
</ParamField>

## Response

<ResponseField name="results" type="list">
  List of the retrieved records.
</ResponseField>

### Response as JSON

This section shows the JSON response returned by the API.
Each API client wraps this response in language-specific objects, so the structure may vary.
To view the response, use the `getLogs` method.
Don't rely on the order of properties—JSON objects don't preserve key order.

```jsonc JSON icon=braces theme={"system"}
{
  "results": [
    {
      "objectID": "1182729442",
      "name": "product 1"
    }
  ]
}
```