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

# moorcheh items-get

> Get items by id within a namespace.

## Overview

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

* **Text** namespaces return `id`, `text`, and `metadata`
* **Vector** namespaces return `id` and `metadata` only

Missing ids are omitted from `items` (still returns **200** with `found_items` less than `requested_ids`).

## Synopsis

```bash theme={null}
moorcheh items-get --namespace-name NAME --ids-json '["id1","id2"]' [--base-url URL]
```

## Options

| Flag               | Required | Description                                             |
| ------------------ | -------- | ------------------------------------------------------- |
| `--namespace-name` | Yes      | Namespace to read from                                  |
| `--ids-json`       | Yes      | JSON array of item id strings (max **100** per request) |
| `--base-url`       | No       | Default `http://localhost:8080`                         |

<Note>
  On **Windows PowerShell**, escape inner quotes: `--ids-json '[\"doc-1\",\"doc-2\"]'`. In bash, use single quotes: `'["doc-1","doc-2"]'`.
</Note>

## Examples

```bash theme={null}
moorcheh items-get --namespace-name my-documents --ids-json '["doc-1","doc-2"]'

moorcheh items-get --namespace-name my-embeddings --ids-json '["vec-1"]'
```

## Output

Prints JSON from `POST /namespaces/{namespace_name}/items/get`:

<ResponseField name="status" type="string">
  `"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.
</ResponseField>

<ResponseField name="found_items" type="number">
  Number of items returned in `items`.
</ResponseField>

<ResponseField name="items" type="array">
  Found items. Empty when none of the ids exist.
</ResponseField>

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

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

<ResponseField name="items[].metadata" type="object">
  Metadata stored with the item.
</ResponseField>

```json Example output (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": "CLI upload documents test"
    }
  ]
}
```

```json Example output (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" }
    }
  ]
}
```

## Exit codes

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| `0`  | Lookup completed (including when no ids were found)     |
| `1`  | API error (400, 404, 500, etc.) or invalid `--ids-json` |

## Related

* [CLI: items-delete](/on-prem/cli/items/delete)
* [API: Get items](/on-prem/api-references/items/get)
* [Python: documents.get()](/on-prem/python-client/items/get)