---
title: Object lookup
description: Fetch specific catalog objects by reference with POST /discovery/v1/objects — no query, no ranking, one round trip.
slug: discovery/objects
docKind: guide
hub: luigisbox-ai
---

`POST /discovery/v1/objects` fetches catalog objects you already know by reference — the
products in a cart, the categories a page references, a hand-picked list — with no query,
no ranking and no pagination.

## Request

```bash
curl -X POST 'https://api.eu1.luigisbox.ai/discovery/v1/objects?channel_id=lbn_4hj9tv' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Lbx-Visitor-Id: 8f14e45f-…' \
  -H 'Content-Type: application/json' \
  -d '{
    "references": [
      "product/@id:product/sku-1001",
      "product/sku:ABC-987"
    ],
    "return_fields": ["@title", "price", "image_url"]
  }'
```

| Query parameter | Required | Notes |
|---|---|---|
| `channel_id` | Yes | Serving destination — the channel's visibility rules still apply |

| Body field | Required | Notes |
|---|---|---|
| `references` | Yes | 1–200 references |
| `return_fields` | No | [Field projection](/discovery/fields/), up to 100 fields |

There is no `surface_id` and no `type` field: each reference names its own type, and
nothing is being ranked.

## Reference format

A reference is three parts:

```text
<type>/<field>:<value>
```

For example:

```text
product/@id:product/sku-1001
product/sku:ABC-123
product/ean:5901234123457
```

- `<type>` is the object type, as in `@type`.
- `<field>` is the field to match on — any field the object carries.
- `<value>` is the value to match.

`product/@id:product/sku-1001` looks the product up by the id discovery returned;
`product/ean:5901234123457` finds the same product by its barcode, so an external key
resolves without a mapping table of your own.

A reference must resolve to at most one object. Two objects matching the same reference is
a `422`.

This is the same reference shape that [analytics events](/analytics/references/) use, so a
reference you already build for reporting can be reused here unchanged.

## Response

```json
{
  "objects": [
    {
      "@id": "product/sku-1001",
      "@type": "product",
      "@title": "Blue Cotton T-Shirt",
      "price": 29.9,
      "image_url": "https://cdn.example.com/products/sku-1001.jpg"
    }
  ]
}
```

- **Order is not guaranteed to match your request.** Key the response by `@id` rather than
  zipping it against your input.
- **References that match nothing are absent.** There is no placeholder and no error. Diff
  the response against what you asked for to find the gaps.

```js
const byId = new Map(objects.map((o) => [o['@id'], o]));
const missing = wantedIds.filter((id) => !byId.has(id));
```

A missing object was deleted or is excluded by the channel's visibility rules; a product
hidden from this channel is invisible here as it is in search.

## When to use it

| Situation | Endpoint |
|---|---|
| Render the cart, or a wishlist | Object lookup |
| Turn `@category` / `@brand` references into titles and URLs | Object lookup |
| Resolve a barcode or partner SKU to a product | Object lookup |
| Hydrate a hand-picked list in an email or CMS block | Object lookup |
| Find products matching a phrase | [Search](/discovery/search/) |
| Show everything in a category | [Collections](/discovery/collections/) |
| Suggest what else to buy | [Recommendations](/discovery/recommendations/) |

Use object lookup when you already know which objects you want and need their data. Use a
discovery endpoint when determining which objects those are is the question.

## Batch, do not loop

Up to 200 references fit in one call. Resolving a 40-item cart with 40 requests costs 40
round trips and 40 rate-limit entries; one request costs one.

```js
async function hydrate(references) {
  const url = `${API}/discovery/v1/objects?channel_id=${channelId}`;
  const results = [];

  for (let i = 0; i < references.length; i += 200) {
    const { objects } = await fetch(url, {
      method: 'POST',
      headers: { ...headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        references: references.slice(i, i + 200),
        return_fields: CARD_FIELDS,
      }),
    }).then((r) => r.json());
    results.push(...objects);
  }
  return results;
}
```

## Reporting

Objects fetched this way were not ranked, so there is no result set to attribute to.
If you render them somewhere a shopper can act on — a cart, a wishlist — report the
interactions as normal. See [Sending events](/analytics/sending-events/).

## See also

- [Object references](/analytics/references/) — the reference format in full
- [Selecting fields](/discovery/fields/) · [Discovery overview](/discovery/overview/)
- [Product variants](/discovery/variants/) — resolving a product's siblings instead