> ## 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

> Get items by id using the Python client

## documents.get

Fetch stored items by id within a namespace. Item ids are unique **per namespace**, not globally. Missing ids are omitted from `items` without failing the request.

```python theme={null}
client.documents.get(
    namespace_name: str,
    *,
    ids: list[str],
) -> dict[str, Any]
```

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

**API:** `POST /namespaces/{namespace_name}/items/get` — see [Get items](/on-prem/api-references/items/get)

### Parameters

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

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

### Examples

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    # Text namespace
    result = client.documents.get(
        "my-documents",
        ids=["doc-1", "doc-2"],
    )

    for item in result["items"]:
        print(item["id"], item.get("text"), item["metadata"])

    # Vector namespace (no text or vector in response)
    result = client.documents.get(
        "my-embeddings",
        ids=["vec-1"],
    )

    for item in result["items"]:
        print(item["id"], item["metadata"])
```

## Returns

<ResponseField name="status" type="string">
  `"success"` when the lookup completed.
</ResponseField>

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

<ResponseField name="requested_ids" type="number">
  Number of ids sent in the request.
</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.
</ResponseField>

<ResponseField name="items" type="array">
  Array of found items. Empty when none of the requested ids exist.
</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>

```python Example return value (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",
    },
  ],
}
```

```python Example return value (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"},
    },
  ],
}
```

### Error Handling

Non-2xx responses raise `MoorchehApiError`. A successful lookup with missing ids does **not** raise — check `found_items` vs `requested_ids`.

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        result = client.documents.get("my-documents", ids=["doc-1"])
except MoorchehApiError as e:
    print(e.status_code, e.body)
```

| Status | Cause                                              |
| ------ | -------------------------------------------------- |
| 400    | Empty `ids`, more than 100 ids, or empty id string |
| 404    | Namespace not found                                |

<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 Operations

* [Delete Items](/on-prem/python-client/items/delete)
* [API: Get items](/on-prem/api-references/items/get)
* [CLI: moorcheh items-get](/on-prem/cli/items/get)