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

<CodeGroup>
  ```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"}'
  ```
</CodeGroup>

## Filters

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

<CodeGroup>
  ```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,
  )
  ```
</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`. |
| `dimensions` | `{ length?, width?, height?, weight? }` | Filter by physical size and weight, each `{ min?, max?, unit }`. See [Dimension Filters](/guides/dimension-filters). |

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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

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

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

<CodeGroup>
  ```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"},
  )
  ```
</CodeGroup>


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