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

# Get Items by ID

> Retrieve items by id within a namespace (up to 100 ids per request).

## Overview

Fetch stored items by id within a namespace. Item ids are unique **per namespace**, not globally.

* **Text** namespaces return `id`, `text`, and `metadata` for each found item
* **Vector** namespaces return `id` and `metadata` only (vectors are not returned)

Ids that do not exist are omitted from `items`; the request still returns **200** with `found_items` less than `requested_ids`.

## Path parameters

<ParamField path="namespace_name" type="string" required>
  Namespace to read from.
</ParamField>

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Body

<ParamField body="ids" type="array" required>
  Non-empty array of item id strings. Maximum **100** ids per request.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST "http://localhost:8080/namespaces/my-documents/items/get" \
    -H "Content-Type: application/json" \
    -d '{
      "ids": ["doc-1", "doc-2"]
    }'
  ```
</RequestExample>

## Response fields

<ResponseField name="status" type="string">
  Request outcome. `"success"` when the lookup completed; `"failure"` on error.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result or error description.
</ResponseField>

<ResponseField name="requested_ids" type="number">
  Number of ids sent in the request. Present on successful lookup.
</ResponseField>

<ResponseField name="found_items" type="number">
  Number of items returned in `items`. May be less than `requested_ids` if some ids were not found. Present on successful lookup.
</ResponseField>

<ResponseField name="items" type="array">
  Array of found items. Empty array when none of the requested ids exist. Present on successful lookup.
</ResponseField>

<ResponseField name="items[].id" type="string">
  Item id.
</ResponseField>

<ResponseField name="items[].text" type="string">
  Stored document text. Present for **text** namespace items only.
</ResponseField>

<ResponseField name="items[].metadata" type="object">
  Metadata stored with the item (custom fields from upload).
</ResponseField>

<ResponseExample>
  ```json 200 - Text namespace theme={null}
  {
    "status": "success",
    "message": "Successfully retrieved 1 items from namespace 'my-documents'.",
    "requested_ids": 2,
    "found_items": 1,
    "items": [
      {
        "id": "doc-1",
        "metadata": { "team": "ai" },
        "text": "Moorcheh on-prem retrieval test"
      }
    ]
  }
  ```

  ```json 200 - Vector namespace theme={null}
  {
    "status": "success",
    "message": "Successfully retrieved 1 items from namespace 'my-embeddings'.",
    "requested_ids": 1,
    "found_items": 1,
    "items": [
      {
        "id": "vec-1",
        "metadata": { "source": "demo" }
      }
    ]
  }
  ```

  ```json 200 - None found theme={null}
  {
    "status": "success",
    "message": "Successfully retrieved 0 items from namespace 'my-documents'.",
    "requested_ids": 1,
    "found_items": 0,
    "items": []
  }
  ```

  ```json 400 - Empty ids array theme={null}
  {
    "status": "failure",
    "message": "Bad Request: ids must be a non-empty array."
  }
  ```

  ```json 400 - Too many ids theme={null}
  {
    "status": "failure",
    "message": "Bad Request: at most 100 ids are allowed per get request."
  }
  ```

  ```json 400 - Empty id string theme={null}
  {
    "status": "failure",
    "message": "Bad Request: each id must be a non-empty string."
  }
  ```

  ```json 404 - Namespace not found theme={null}
  {
    "status": "failure",
    "message": "Namespace 'my-documents' not found."
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "status": "failure",
    "message": "Internal Server Error retrieving namespace items."
  }
  ```
</ResponseExample>

## Important Notes

<Warning>
  * Maximum **100** ids per request — use multiple requests for larger batches
  * Missing ids are skipped; check `found_items` vs `requested_ids`
  * Vector embeddings are not included in the response
</Warning>

## Related

* [Delete items by ID](/on-prem/api-references/items/delete)
* [CLI: moorcheh items-get](/on-prem/cli/items/get)
* [Python: documents.get()](/on-prem/python-client/items/get)