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

> Text search, filters, and pagination across the Channel3 product catalog.

The `POST /v1/search` endpoint is the core of Channel3. Pass a free-text query and get back a ranked list of products with prices, availability, images, and merchant offers.

## Basic search

<CodeGroup>
  ```typescript TypeScript theme={null}
  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={null}
  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={null}
  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"}'
  ```
</CodeGroup>

## Filters

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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={null}
  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,
  )
  ```
</CodeGroup>

### Popular filters

These are the filters most integrations use. See the [API reference](/api-reference/v1/search) 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).                                                                                                         |
| `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`.                                                                                                                            |

## Pagination

Use `next_page_token` from the response to fetch the next page. You can page up to 500 products total.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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={null}
  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")
  ```
</CodeGroup>

## Low-latency keyword search

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const results = await client.products.search({
    query: "Nike Air Max 90",
    config: { keyword_search_only: true },
  });
  ```

  ```python Python theme={null}
  results = client.products.search(
      query="Nike Air Max 90",
      config={"keyword_search_only": True},
  )
  ```
</CodeGroup>

<Cards>
  <Card title="Advanced Search" icon="sliders" href="/guides/advanced-search" arrow="true">
    Use structured attributes to find products by feature — e.g. "sofas with USB charging ports."
  </Card>

  <Card title="Localization" icon="globe" href="/guides/localization" arrow="true">
    Set country, language, and currency for market-specific results.
  </Card>

  <Card title="Caching" icon="database" href="/guides/caching" arrow="true">
    Cache product IDs safely while refreshing prices and availability at display time.
  </Card>
</Cards>