Get Items

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.

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

Parameters

string

required

Namespace to read from.

array

required

Non-empty array of item id strings. Maximum 100 ids per request.

Examples

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

string

"success" when the lookup completed.

string

Human-readable result description.

number

Number of ids sent in the request.

number

Number of items returned in items. May be less than requested_ids if some ids were not found.

array

Array of found items. Empty when none of the requested ids exist.

string

Item id.

string

Stored document text. Present for text namespace items only.

object

Metadata stored with the item (custom fields from upload).

Example return value (text namespace)

{
  "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",
    },
  ],
}

Example return value (vector namespace)

{
  "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.

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

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

Getting Started

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

documents.get

Parameters

Examples

Returns

Error Handling

​documents.get

​Parameters

​Examples

​Returns

​Error Handling

​Related Operations

documents.get

Parameters

Examples

Returns

Error Handling

Related Operations