# /search-products

Our /**search-products** endpoint accepts a product description and uses AI to search the web for match candidates. Based on the limited search result text, we can filter out many non-matching results, but to get matching products, the next steps are to visit candidate pages and match using product page data. 

**Search-products/ is part of a multi-step flow** where you bring your own e-commerce page data. The steps are as follows:

1. Search a product with the /search-products endpoint
2. Ping an external API to get detailed product descriptions
3. Score the match with /match-products, using the product data from step 2  

To make this easier, our /**search-products-with-page-visit** endpoint takes care of the full product search flow, including fetching product page data. See [here](/docs/endpoints/search-and-match-products.md). However, visiting ecommerce sites (especially class 1 sites) adds to the cost considerably. 

### /search-products

#### Required Parameters:

* <mark style="background-color:red;">product</mark>: dict. Provide a JSON object of your product with key value pairs such as {'title':'value'}. You must define the product title under the 'title' key. You can specify familiar or unfamiliar keys. Familiar keys such as 'code', 'brand', 'description', and 'price' will be added under their own key value pair. All other key value pairs will be added to the 'description' key value pair. See [guidelines for input data](/docs/topics/guidelines-for-input-data.md).&#x20;
* <mark style="background-color:red;">site</mark>: string. Limit search to a specific domain, such as amazon.com, amazon.ca, amazon.mx, walmart.com, ebay.com, etc.   &#x20;

#### Optional Parameters:&#x20;

* <mark style="background-color:red;">search\_sequence</mark>: list of strings. Provide the sequence of searches you would like to run, with each item specifying the search depth. Defaults to \['standard', 'standard']. While there is currently only one search depth option, 'standard', you have the option to control how many of searches to run. To use one search, use \['standard']. However, we strongly recommend 2 standard searches for a good outcome, i.e., \['standard', 'standard']. Each search in the sequence is a separate charge.&#x20;

### Request

See playground for code in other formats.

```python
import requests
response = requests.post(
    "https://api.theproductllm.com/search-products",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "product": {
            "title":"This is a product title", 
            "description": "this is a product description" #optional
        }
        "site": "amazon.com",
        "search_sequence":["standard","standard"]
    }
)
print(response.json())

```

#### Response:

```
{
    "candidates": [
        "product":{
            "title":"This is a trimmed search result...",
            "description":"This is a search result snippet description"}
        "link":"https://site.com/123",
        "search_rank":1,
        "listing_id":"123",
        "is_candidate":"yes",
    ],
    "cost": 0.001
}
```

<details>

<summary>Tier 1 Costs and Limits</summary>

Across our website, when we quote $0.001 / search, this reflects two "standard" depth searches.&#x20;

| Search      | Tier 1 Cost      | Tier 1 Rate Limit     |
| ----------- | ---------------- | --------------------- |
| Standard    | $0.0005 / search | 30 queries per second |
| Standard x2 | $0.001 / search  | 30 queries per second |

Contact us to increase your rate limit.

</details>

<details>

<summary>Tier 2 Costs and Limits</summary>

Quotes below reflect "standard" depth searches.

**Rate Limit:** 1 query per second.&#x20;

| Search      | Tier 2 Cost       | Tier 2 Rate Limit  |
| ----------- | ----------------- | ------------------ |
| Standard    | $0.00075 / search | 1 query per second |
| Standard x2 | $0.0015 / search  | 1 query per second |

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://theproductllm-com.gitbook.io/docs/endpoints/search-products.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.