Skip to main content
POST
/
v1
/
tools
/
commerce
/
search
Search Products
curl --request POST \
  --url https://api.example.com/v1/tools/commerce/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123
}
'

​
Overview

Search for products across Amazon, Shopify, and other supported retailers. Returns product information including prices, availability, and purchase URLs.

​
Request Body

​
query
string
required
Search query (e.g., “wireless bluetooth headphones”)
​
limit
number
default:10
Maximum number of results to return (max: 50)

​
Response (202 - Processing)

{
  "request_id": "req_abc123",
  "status": "processing",
  "tool": "commerce_search",
  "message": "Search job queued successfully"
}

​
Job Result

Poll /v1/requests/{request_id} for results: 
{
  "status": "completed",
  "result": {
    "status": "success",
    "query": "wireless bluetooth headphones",
    "products": [
      {
        "product_url": "https://amazon.com/dp/B09XS7JWHH",
        "title": "Sony WH-1000XM5 Wireless Headphones",
        "price": 348.00,
        "currency": "USD",
        "image_url": "https://...",
        "vendor": "Sony",
        "rating": 4.7,
        "review_count": 12500,
        "in_stock": true,
        "description": "Industry-leading noise canceling..."
      }
    ],
    "count": 10
  }
}

​
SDK Usage

const results = await agent.commerceSearch({
  query: "wireless bluetooth headphones",
  limit: 10,
});

for (const product of results.products) {
  console.log(`${product.title}: $${product.price}`);
  console.log(`  URL: ${product.product_url}`);
}

​
Example: Search and Buy Flow

// 1. Search for products
const search = await agent.commerceSearch({
  query: "USB-C hub",
  limit: 5,
});

// 2. Pick the best result
const bestProduct = search.products[0];

// 3. Purchase it
const order = await agent.commerceBuy({
  product_url: bestProduct.url,
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip_code: "94102",
    phone: "4155550100",
  },
});