Get multiple documents

Gets a selection of documents based on their IDs.

This endpoint accepts the application/json content type.

GET /indexes/{index_name}/documents

Path parameters

Name	Type	Description
`index_name`	String	name of the index

Query parameters

Search parameter	Type	Default value	Description
`expose_facets`	Boolean	False	If true, the documents' tensor facets are returned. This is a list of objects. Each facet object contains document data and its associated embedding (found in the facet's _embedding field)

Response

The response of the get_multiple_documents endpoint in Marqo operates on two levels. Firstly, a status code of 200 in the overall response indicates that the batch request has been successfully received and processed by Marqo.

The response has the following fields:

Field	Type	Description
`results`	Array	An array of objects, each representing a document. Each object contains the document's data.

However, a 200 status does not necessarily imply that each individual document within the batch was processed without issues. For each document in the batch, there will be an associated response code that specifies the status of that particular document's processing. These individual response codes provide granular feedback, allowing users to discern which documents were successfully processed, which encountered errors, and the nature of any issues encountered. If Marqo finds the document, the document will be returned with the _found field set to true in an object. For documents not found, the _found field will be set to false, with the document ID returned in the _id field and details of the error in the message field.

For this endpoint, a 200 status code is not used to indicate successful document retrieval, as we aim to avoid adding extra fields to the returned documents. Here is the HTTP status code of the individual document responses (non-exhaustive list of status codes):

Status Code	Description
`400`	Bad request. Returned for invalid input (e.g., invalid field types). Inspect `message` for details.
`404`	The target document is not in the index.
`429`	Marqo vector store receives too many requests. Please try again later.
`500`	Internal error.

Body

An array of IDs. Each ID is a string.

["article_152", "article_490", "article_985"]

Example

Marqo Open SourceMarqo Cloud

cURLPython

curl -XGET http://localhost:8882/indexes/my-first-index/documents -H 'Content-Type: application/json' -d '
    ["article_152", "article_490", "article_985"]
'

mq.index("my-first-index").get_documents(
    document_ids=["article_152", "article_490", "article_985"]
)

For Marqo Cloud, you will need to access the endpoint of your index and replace your_endpoint with this. To do this, visit Find Your Endpoint. You will also need your API Key. To obtain this key visit Find Your API Key.

cURLPython

curl -XGET your_endpoint/indexes/my-first-index/documents \
-H 'x-api-key: XXXXXXXXXXXXXXX' \
-H 'Content-Type: application/json' -d '
    ["article_152", "article_490", "article_985"]
'

mq.index("my-first-index").get_documents(
    document_ids=["article_152", "article_490", "article_985"]
)

Response `200 OK`

{'results': [{'Blurb': 'A rocket car is a car powered by a rocket engine. This '
                       'treatise proposes that rocket cars are the inevitable '
                       'future of land-based transport.',
              'Title': 'Treatise on the viability of rocket cars',
              '_found': true,
              '_id': 'article_152'},
             {'_found': false, '_id': 'article_490'},
             {'Blurb': "One must maintain one's space suite. It is, after all, "
                       'the tool that will help you explore distant galaxies.',
              'Title': 'Your space suit and you',
              '_found': true,
              '_id': 'article_985'}]}

In this response, the index has no document with and ID of article_490. As a result, the _found field is false.