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

# Products and Search

> Search a merchant's catalog. Prices are integer minor units. Results include availability and variants.

![Search query returns a grid of product results](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/products.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=c339ac7365301ac69d35d575e9c78284)

`search_catalog` returns real products from the merchant you name, with prices in integer minor units of the merchant's currency (cents for USD, pence for GBP).

## Search sources

| Source | Speed | How it works | Needs `session_id` |
| - | - | - | - |
| `"oxylabs"` | \~5s | The merchant's result page, scraped and reranked by relevance. The default. | No |
| `"catalog"` | \~1s | Channel3 product index. Returned when it answers first and titles match. | No |
| `"merchant"` | varies | Opens merchant search in the session browser. Slowest, but sees live results. | Yes |

Omit `source` to use the default (`oxylabs`). When `oxylabs` is chosen and Channel3 answers first with matching titles, the response arrives faster with `source: "catalog"`.

## Results

Each search returns up to 10 products:

```json theme={null}
{
  "id": "123456789",
  "merchant_id": "mrc_walmart",
  "title": "Energizer MAX AA Batteries, 24 Pack",
  "brand": "Energizer",
  "url": "https://www.walmart.com/ip/123456789",
  "image_url": "https://i5.walmartimages.com/...",
  "price": 1697,
  "currency": "USD",
  "availability": "in_stock"
}
```

`price` is integer minor units of `currency`. `1697` means \$16.97 in USD, or £16.97 in GBP. `availability` is `"in_stock"`, `"out_of_stock"`, or `null` when unknown.

## Relevance

Oxylabs and catalog results include a `relevance` field: `"ok"` or `"low"`. When relevance is low, the response includes a `hint` explaining why. Always check titles before using a result — a search for "AA batteries" may return phone chargers when relevance is low.

## Caching

Repeating the same `oxylabs` or `catalog` query within 15 minutes returns the cached result. The response includes `cached_at` with the original search time. Merchant search is never cached.

## Reading a product page

`get_product` reads one product page by URL. It returns the same fields as search, plus `reviews` when the page has them:

```json theme={null}
{
  "product": { "...same fields as search..." },
  "reviews": { "rating": 4.6, "count": 12847 }
}
```

### Variants

When a product has selectable options (size, colour, pack count), the response includes `options` and `variants`.

`options` lists the axes:

```json theme={null}
[
  {
    "name": "Size",
    "values": [
      { "label": "24 Pack", "available": true },
      { "label": "48 Pack", "available": true }
    ]
  }
]
```

`variants` lists every combination:

```json theme={null}
[
  {
    "id": "987654321",
    "url": "https://www.walmart.com/ip/987654321",
    "options": [{ "name": "Size", "label": "48 Pack" }],
    "price": 2894,
    "unit_price": null,
    "availability": "in_stock",
    "featured": false
  }
]
```

The variant matching the original URL has `featured: true`. Use the variant `id` in `update_cart` `line_items[].item.id` and its `url` in `line_items[].item.url`.

## Batch lookup

`lookup_catalog` reads up to 10 product pages in one call. Pass `ids` as an array of search `id` values or product URLs. A plain item id reads that merchant's product page (on Walmart, `"123456789"` reads `https://www.walmart.com/ip/123456789`).

Returns `products` (the ones that loaded) and `failed` (`{ id, error }` for each page that did not). One bad page does not fail the call.

## Daily search cap

Each API key has a daily search allowance, resetting at UTC midnight. When the cap is hit, `search_catalog` returns `daily_limit_reached` with `used_today` and `daily_cap`. Non-search tools do not consume the allowance. Failed searches with auth or rate errors are not counted.

See [Rate limits](https://agentmall.mintlify.site/reference/rate-limits.md) for details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.