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

# Search

The `/v1/search` endpoint is the core of Channel3. Make a requests and get back a list of products with prices, availability, images, and retailer offers.

## Basic search

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Channel3 from "@channel3/sdk";

const client = new Channel3(); // reads CHANNEL3_API_KEY from env

const results = await client.products.search({
  query: "merino wool sweater",
});

console.log(results.products[0].title);
console.log(results.products[0].offers[0].price);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from channel3_sdk import Channel3

client = Channel3()  # reads CHANNEL3_API_KEY from env

results = client.products.search(query="merino wool sweater")

print(results.products[0].title)
print(results.products[0].offers[0].price)
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "merino wool sweater"}'
```

## Filters

Narrow results with `filters`. Every filter is optional — combine as many as you need.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "running shoes",
  filters: {
    price: { min_price: 50, max_price: 150 },
    availability: ["InStock", "LimitedAvailability"],
    gender: "male",
    category: "running-shoes", // category slug
    brand_ids: ["brand_id_1"], // from /v1/brands/search
  },
  limit: 20,
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
results = client.products.search(
    query="running shoes",
    filters={
        "price":        {"min_price": 50, "max_price": 150},
        "availability": ["InStock", "LimitedAvailability"],
        "gender":       "male",
        "category":     "running-shoes",
        "brand_ids":    ["brand_id_1"],
    },
    limit=20,
)
```

### Popular filters

These are the filters most integrations use. See the [API reference](/api-reference/v1/search.md) for the complete list.

| Filter | Type | Description |
| - | - | - |
| `price` | `{ min_price?, max_price? }` | Price range in the request's currency. |
| `availability` | `string[]` | One or more of `InStock`, `LimitedAvailability`, `PreOrder`, `BackOrder`, `SoldOut`, `OutOfStock`. |
| `gender` | `string` | `male`, `female`, or `unisex`. |
| `category` | `string` | A category slug (e.g. `running-shoes`). See [Categories](/categories.md). |
| `brand_ids` | `string[]` | Limit to specific brands. Resolve brand IDs via [`/v1/brands/search`](/api-reference/v1/search-brands). |
| `attributes` | `Record<string, string[]>` | Filter by structured attribute key/value pairs — e.g. `{ "connectivity": ["USB"] }`. Attribute keys come from category detail. See [Advanced Search](/guides/advanced-search). |
| `colors` | `{ hex: string, percentage?: number }[]` | Filter by color palette using hex values **(Beta)**. |
| `age` | `string` | `newborn`, `infant`, `toddler`, `kids`, or `adult`. |
| `dimensions` | `{ length?, width?, height?, weight? }` | Filter by physical size and weight, each `{ min?, max?, unit }`. See [Dimension Filters](/guides/dimension-filters.md). |

## Pagination

Use `next_page_token` from the response to fetch the next page. You can page up to 500 products total. A request with a `next_page_token` costs one credit. See [pricing](/pricing.md).

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const page1 = await client.products.search({ query: "running shoes" });
console.log("Page 1:", page1.products.length, "products");

if (page1.next_page_token) {
  const page2 = await client.products.search({
    query: "running shoes",
    page_token: page1.next_page_token,
  });
  console.log("Page 2:", page2.products.length, "products");
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
page1 = client.products.search(query="running shoes")
print(f"Page 1: {len(page1.products)} products")

if page1.next_page_token:
    page2 = client.products.search(
        query="running shoes",
        page_token=page1.next_page_token,
    )
    print(f"Page 2: {len(page2.products)} products")
```

## Collections

Pass `config.collection_id` to search inside a saved catalog scope (brands, websites, categories, and/or specific products). Request filters still apply and can only narrow the collection. See [Collections](/guides/collections.md).

### Keyword search

Set `mode: "keyword"` to skip semantic (vector) search and use exact keyword matching instead. This path is optimized for **low latency** — use it when users type specific product names or SKUs, or when you need the fastest possible search response.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "Nike Air Max 90",
  config: { mode: "keyword" },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
results = client.products.search(
    query="Nike Air Max 90",
    config={"mode": "keyword"},
)
```


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